AwesomeAnnotate

AwesomeAnnotate adds generated schema and route comments to Rails applications.

This gem is intended as a small replacement-style tool for the basic features of the original annotate gem:

• annotate model files with Active Record schema information
• annotate config/routes.rb with the application's route table
• replace previous AwesomeAnnotate blocks instead of appending duplicates
• remove generated AwesomeAnnotate blocks

• Ruby 3.0 or later, below 4.0
• Active Record 6.1 or later, below 8.0
• Rails application layout with config/environment.rb

Development currently uses the Ruby version in .ruby-version.

Add this line to your Rails application's Gemfile:

gem 'awesome_annotate'

Then run:

bundle install

If you are using this repository directly before publishing the gem, use a Git source instead:

gem 'awesome_annotate', git: 'https://github.com/wisdom-plus/awesome_annotate'

Run commands from the root directory of a Rails application.

Available commands:

bundle exec awesome_annotate model user
bundle exec awesome_annotate models
bundle exec awesome_annotate models user article admin/user
bundle exec awesome_annotate routes
bundle exec awesome_annotate all
bundle exec awesome_annotate init
bundle exec awesome_annotate remove model user
bundle exec awesome_annotate remove models
bundle exec awesome_annotate remove routes
bundle exec awesome_annotate remove all

Annotate a model:

bundle exec awesome_annotate model user

Annotate all models:

bundle exec awesome_annotate models

Annotate specific models:

bundle exec awesome_annotate models user article admin/user

Annotate all models and routes:

bundle exec awesome_annotate all

Remove generated annotations:

bundle exec awesome_annotate remove model user
bundle exec awesome_annotate remove models
bundle exec awesome_annotate remove routes
bundle exec awesome_annotate remove all

Create a configuration file:

bundle exec awesome_annotate init

This creates config/initializers/awesome_annotate.yml:

# AwesomeAnnotate configuration
#
# Change these paths when your Rails app uses non-standard locations.
env_file_path: config/environment.rb
model_dir: app/models
route_file_path: config/routes.rb
annotation_position: top
exclude_model_files: []
include_indexes: true
exclude_columns: []
include_column_defaults: true
exclude_routes: []

When this file exists, annotation and removal commands use these values. This allows applications with non-standard model, route, or environment file paths to change command behavior without passing Ruby options directly. Set annotation_position to top or bottom to choose where new annotation blocks are inserted. Set exclude_model_files to relative file paths or glob patterns under model_dir to skip them during model discovery. Set include_indexes to false to omit the Indexes section from model schema annotations. Set exclude_columns to column names to omit them from model schema annotations. Set include_column_defaults to false to omit default(...) details. Set exclude_routes to route line patterns to omit them from route annotations.

This loads config/environment.rb, resolves User, reads its Active Record columns, and writes a schema block before the class definition in app/models/user.rb:

# == AwesomeAnnotate: columns
# == Schema Information
#
# Table name: users
#
#  id         :integer  not null, primary key
#  name       :string
#  email      :string   not null, default("")
#  created_at :datetime not null
#  updated_at :datetime not null
#
# Indexes
#
#  (email)       UNIQUE, index_users_on_email
#  (name,email)  index_users_on_name_and_email
#
# == /AwesomeAnnotate: columns
class User < ApplicationRecord
end

Annotate routes:

bundle exec awesome_annotate routes

This writes a generated route block before Rails.application.routes.draw do in config/routes.rb:

# == AwesomeAnnotate: routes
# Prefix Verb URI Pattern Controller#Action
# users GET /users(.:format) users#index
# == /AwesomeAnnotate: routes
Rails.application.routes.draw do
end

Print the gem version:

bundle exec awesome_annotate --version

Short aliases are also available:

bundle exec awesome_annotate -m user
bundle exec awesome_annotate -r
bundle exec awesome_annotate -v

AwesomeAnnotate wraps generated comments with start and end markers:

# == AwesomeAnnotate: columns
# ...
# == /AwesomeAnnotate: columns

When the command is run again, the existing block with the same marker is replaced. This prevents duplicate annotations from being appended on repeated runs.

• Only model schema blocks and routes are supported.
• Model annotations include column type, nullability, primary key, and default values, plus basic index information.
• Model annotation currently targets files under app/models.
• Model class detection expects a simple class declaration such as class User < ApplicationRecord.
• Existing comments generated by other annotate tools are not migrated or removed automatically.
• Ruby 4 is not currently supported.

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Run RuboCop:

bundle exec rubocop

Build the gem locally:

bundle exec rake build

Bug reports and pull requests are welcome on GitHub at https://github.com/wisdom-plus/awesome_annotate.

The gem is available as open source under the terms of the MIT License.