Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
118 lines (87 sloc) 2.85 KB


Extracts and displays annotations from source code comments like these:

class MyModel
  def find(id)
    # TODO: Find the thing

The output looks like this:

  * [ 17] [TODO] Find the thing

Annotations is a standalone library derived from the notes tasks in Rails 3.2.1, extracted into its own gem so it can be used in non-Rails (or even non-Ruby) projects.

Annotations looks for TODO, FIXME, and OPTIMIZE comments in the following kinds of source code files:

Syntax Supported file extensions
Ruby .rb, .builder, Gemfile, Rakefile
ERb .erb, .rhtml
CoffeeScript .coffee
Sass .scss, .sass
PHP .php


Add this line to your application's Gemfile:

gem 'annotations'

Or install it yourself as:

$ gem install annotations


Add the Annotations tasks to your Rakefile:

require 'annotations/rake_task'

This will add the following tasks:

$ bundle exec rake -T notes
rake notes                     # Enumerate all annotations
rake notes:custom[annotation]  # Enumerate a custom annotation
rake notes:fixme               # Enumerate all FIXME annotations
rake notes:optimize            # Enumerate all OPTIMIZE annotations
rake notes:todo                # Enumerate all TODO annotations

If you want to name the tasks something other than "notes", just pass the name you want to use into

You can also set the default tag list when defining the task, using this block syntax: do |t|
  # This will add an additional 'WTF' annotation; it will be included in
  # `rake notes`, and a `rake notes:wtf` task will be added
  t.tags = [:fixme, :optimize, :todo, :wtf]

Once your Rakefile is set up, run the tasks to view your notes:

rake notes

Runtime options

Filter by file extension: Only display annotations for certain kinds of files. (Thanks for Gabriel Schammah for contributing this feature.)

rake notes:todo ext=js,rb,coffee


  • Ability to set/limit the search path(s) for annotations (currently set to '.')
  • Color output
  • Standalone command-line tool (e.g. annotations wtf todo --color)
  • More robust handling of different extensions/comment formats, plus the ability to easily add in new ones
  • Test coverage!!


Fork the project, make some changes on a feature branch, then send a pull request.

Something went wrong with that request. Please try again.