Rails::Diff

Compare your Rails application files with the ones generated by Rails main branch. This helps you keep track of changes between your customized files and the latest Rails templates.

Installation

Add this line to your application's Gemfile:

gem 'rails-diff'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install rails-diff

Usage

Compare specific files

# Compare a single file
rails-diff file Dockerfile

# Compare multiple files
rails-diff file Dockerfile Gemfile

# Force regenerate Rails app by clearing cache
rails-diff file Dockerfile --clear-cache

# Fail if there are differences (useful for CI)
rails-diff file Dockerfile --fail-on-diff

# Compare a specific ref (tag, branch, or commit SHA)
rails-diff file Dockerfile --ref v8.0.0

Compare generator files

# Compare files that would be created by a generator
rails-diff generated authentication

# Compare files with generator arguments
rails-diff generated scaffold Post title:string body:text

# Force regenerate Rails app by clearing cache
rails-diff generated scaffold Post --clear-cache

# Skip specific files or directories during the diff
rails-diff generated scaffold Post --skip app/views app/helpers

# Fail if there are differences (useful for CI)
rails-diff generated scaffold Post --fail-on-diff

# Compare a specific ref (tag, branch, or commit SHA)
rails-diff generated authentication --ref v8.0.0

Compare dotfiles (configuration files)

# Compare configuration files like .gitignore, .rspec, .rubocop.yml
rails-diff dotfiles

Compare infrastructure files

Compare all Rails-generated infrastructure files at once. This includes everything except app/ and lib/ (your application code): bin/, config/, db/, public/, Dockerfile, Gemfile, Rakefile, dotfiles, and more.

# Compare all infrastructure files
rails-diff infra

# Compare only specific directories
rails-diff infra --only bin config

# Skip additional directories
rails-diff infra --skip db

# Fail if there are differences (useful for CI)
rails-diff infra --fail-on-diff

Global Options

These options can be used with any of the commands above.

--fail-on-diff

If this option is specified, the command will exit with a non-zero status code if there are any differences between your files and the generated ones. This can be particularly useful when using the gem in Continuous Integration (CI) environments.

--ref

Specify a tag, branch, or commit SHA to compare against. If not provided, the latest commit on main will be used by default. --commit is kept as an alias.

[!NOTE] When using a commit SHA, the full 40-character SHA is required (short SHAs are not supported).

--new-app-options

Specify additional options to be used with the rails new command. This allows you to customize the generated Rails application, for example, by specifying a different database.

Example:

rails-diff file Dockerfile --new-app-options="--database=postgresql"

--skip

Skip specific files or directories during the diff.

rails-diff generated scaffold Post --skip app/views app/helpers

--only

Only include specific files or directories in the diff.

rails-diff generated scaffold Post --only app/models app/controllers

--clear-cache/--no-cache

Clear the cache directory to force cloning Rails and regenerating the Rails template app.

rails-diff file Dockerfile --clear-cache

--debug

Print debug information.

rails-diff file Gemfile --debug

or with an environment variable:

DEBUG=1 rails-diff file Gemfile

How it works

When you run the diff, it will:

  1. Clone the latest Rails from main branch
  2. Generate a new Rails app with the same name as yours
  3. Show you a colored diff between your file and the generated one

Cache

The gem caches the generated Rails application to avoid regenerating it on every run. The cache is automatically invalidated when:

  • Rails has new commits on main
  • The cache directory doesn't exist (or is cleared with the --clear-cache option)
  • You use --new-app-options with different options
  • You change your ~/.railsrc file
  • You use --ref with a different ref

You can also force clear the cache by using the --no-cache option (or its alias --clear-cache) with any command.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/matheusrich/rails-diff.

License

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