Humanize elapsed time from some Time instance to, e.g. '2 hours and 1 minute ago'. ATTENTION: NOT MAINTAINED
Failed to load latest commit information.
spec Added Rubinius support. Replaced RUBY_PLATFORM check with RUBY_ENGINE Dec 13, 2013
.gitignore Fixed Travis install command to avoid --deployment bundler_args. Dec 13, 2013
.rspec RSpec fail fast. Require new improved RSpec expect() syntax Dec 13, 2013
.ruby-gemset Play nice with rvm and rbenv Dec 13, 2013
.ruby-version Play nice with rvm and rbenv Dec 13, 2013
.travis.yml Added travis_retry to RETRY! after a strange Gem::RemoteFetcher::Fetc… Dec 15, 2013
.yardopts Initial commit as of gem-newgem generated it Mar 6, 2013 Bump version to 0.1.0 Mar 6, 2013
Gemfile.lock Improving rubygems workflow by using rubygems-tasks Dec 15, 2013 Initial commit as of gem-newgem generated it Mar 6, 2013 Removed Gemnasium badge since is buggy, repos disappear… Dec 15, 2013
Rakefile Improving rubygems workflow by using rubygems-tasks Dec 15, 2013
time_ago_in_words.gemspec Improving rubygems workflow by using rubygems-tasks Dec 15, 2013


Gem Version Build Status Code Climate Coverage Status alpha


This is just a proof-of-concept gem. Please review the following production-ready suggestions i have for you:

Rails apps

You can use classic Rails time ago in words

time_ago_in_words( - 60*60*2) + ' ago'
#=> "about 2 hours ago"

# Note that all these returns the same
distance_of_time_in_words(, 15.seconds.from_now, include_seconds: true)
distance_of_time_in_words(, 15.seconds.ago, include_seconds: true)
time_ago_in_words(15.seconds.from_now, include_seconds: true)
#=> "less than 20 seconds"

For localization or changing the words to be used, look at this file

Non-Rails apps

Same as before but you will need some explicit requires:

require 'action_view'
require 'action_view/helpers'
include ActionView::Helpers::DateHelper
time_ago_in_words( - 60*60*2) + ' ago'
#=> "about 2 hours ago"

# If you need to take advantage of Numeric ActiveSupport extensions:
require 'active_support/core_ext/numeric/time'
time_ago_in_words( - 2.hours) + ' ago'
#=> "about 2 hours ago"
# note that ( - 2.hours) == (2.hours.ago)

Web apps, client side:

If you are programming for the web and don't want to mess your caching strategies then client-side update libraries came to your rescue:

Name Pure Javascript + Rails integration jQuery library jQuery + Rails integration
37signals Local Time local_time smart-time-ago timeago-rails
Smart Time Ago smart-time-ago timeago-rails
Timeago jquery-timeago rails-timeago


If you are looking for results that looks like this

    "1 year, 2 months, 4 hours, 5 minutes, and 6 seconds"

There is also time-lord if you want to look around

require 'time-lord'
1.hour.ago.to_i                     #=> -3600
200.minutes.ago.to_words            #=> "3 hours ago"
(200.years + 400.days).ago.to_words #=> "201 years ago"
1.hour.ago.to_range                 #=> 1379701707..1379705307

Related: Natural Language Date Parser

If you are working in the opposite direction chronic natural language date parsing to the rescue.

require 'chronic' #gem install chronic
Chronic.parse("1 year from now").year #=> 2014

The Javascript version of chronic is date and can be used within your browser (client-side) or nodejs (server-side).


Humanize elapsed time from some Time instance to, e.g. '2 hours and 1 minute ago'

This gem provides slightly different approach to the others but still needs some work to be production-ready, check TODO section.


$ gem install time_ago_in_words or add to your Gemfile this line: gem 'time_ago_in_words' then run bundle install


Just require 'time_ago_in_words' and then call Time#ago_in_words method:

require 'time_ago_in_words'

# Comparing from now:
( - 10).ago_in_words #=> "10 seconds ago"
( - 1).ago_in_words  #=> "1 second ago"
( - 60).ago_in_words #=> "1 minute ago"
( - 63).ago_in_words #=> "1 minute and 3 seconds ago"

# This is my current time so you can compare #=> 2013-03-06 02:19:23 -0300

Time.local(1981,03,03,20,30,40).ago_in_words #=> "690 days and 5 hours ago"
Time.local(2013,03,03,20,30,40).ago_in_words #=> "2 days and 5 hours ago"
Time.local(2013,03,04,20,30,40).ago_in_words #=> "1 day and 5 hours ago"
Time.local(2013,03,05,20,30,40).ago_in_words #=> "5 hours and 48 minutes ago"
Time.local(2013,03,05,21,13,40).ago_in_words #=> "5 hours and 5 minutes ago"
Time.local(2013,03,06,00,30,40).ago_in_words #=> "1 hour and 48 minutes ago"
Time.local(2013,03,06,01,11,40).ago_in_words #=> "1 hour and 7 minutes ago"
Time.local(2013,03,06,01,27,40).ago_in_words #=> "51 minutes and 43 seconds ago"
Time.local(2013,03,06,02,19,20).ago_in_words #=> "3 seconds ago"


  1. Fork it.
  2. Make your feature addition or bug fix and create your feature branch.
  3. Update the Change Log.
  4. Add specs/tests for it. This is important so I don't break it in a future version unintentionally.
  5. Commit, create a new Pull Request.
  6. Check that your pull request passes the build.


  • Add DateTime support. Currently only available for Time objects.
  • Add "N months ago"
  • Add "N years ago"
  • Add "N decades ago"
  • Add "N centuries ago"
  • Add more rspec Examples
  • Implement Time mocking for testing, instead of abusing on spec
  • Extract time_ago_in_words and implement that alternative precision syntax, e.g. "less than a minute ago"


Released under the MIT License. See the LICENSE file for further details.


RubyGems | Documentation | Source | Bugtracker | Build Status | Dependency Status | Code Climate