Source Code analysis gem for Ruby and Rails
Clone or download
Latest commit 6097bec Jan 6, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin added support for ignored pathd, fixes #31 Nov 15, 2013
lib/simplabs 2.1.1 Jun 18, 2014
spec support new AR validations, fixes #29 Oct 22, 2013
.gitignore ignore the build gem Sep 22, 2012
.rbenv-version added .rbenv-version Sep 21, 2012
.rspec moved spec/spec.opts to .rspec Jun 28, 2013
.travis.yml run latest bundler on travis (#36) Jan 2, 2017 2.1.1 Jun 18, 2014
Gemfile switch to rspec 2 Jun 28, 2013
Gemfile.lock updated Gemfile.lock Jun 18, 2014
LICENSE fix copyright notice Jan 3, 2018 fix copyright notice Jan 3, 2018
Rakefile added default rake task Sep 18, 2009
VERSION.yml updated history, version Jun 27, 2013
excellent.gemspec 2.1.1 Jun 18, 2014


Build Status

Excellent finds the nasty lines in your code. It implements a comprehensive set of checks for possibly buggy parts of your app that would otherwise make it into your repo and eventually to the production server.

See the API documentation at and the Wiki at


Simply install with Ruby Gems:

gem install excellent


Assume you have the following class definition,

class ShoppingBasket < ActiveRecord::Base

  def initialize(items = [])
    self.items = items


then Excellent will report the problems in this piece of code:

$ excellent shopping_basket.rb

  Excellent result:

    * Line   1: ShoppingBasket does not validate any attributes.
    * Line   1: ShoppingBasket defines initialize method.
    * Line   1: ShoppingBasket does not specify attr_accessible.

  Found 3 warnings.

To analyse all the models in your Rails application, just do

excellent app/models

in your RAILS_ROOT. You can also invoke analysation through the Simplabs::Excellent::Runner class. Excellent can also produce HTML output. To get a formatted HTML report, just specify html:<filename>:

excellent -o out.html app/models

You can also use Excellent in a Rake task:

require 'simplabs/excellent/rake' do |t|
  t.html  = 'doc/excellent.html' # optional, if you don't specify html, output will be written to $stdout
  t.paths = %w(app lib)


You can configure which checks to run and which thresholds etc. to use. Simply place a .excellent.yml in the root directory of you project (the directory that you will be starting excellent from). You can enable/disable by using the check name as hash key and specifying a truthy/falsy value:

AbcMetricMethodCheck: true
AssignmentInConditionalCheck: false

By default all checks are enabled so you would usually only switch off certain checks you're not interested in. Some checks also take cofngigurations like thresholds, patterns etc. You can configure those by simply defining nested hashes in the YAML:

  threshold: 500
  pattern: '^[a-z].*'

This would for example only report classes with more than 500 lines and require that all method names start with a lower case letter.

You can get a list of the enabled checks and their configurations by running:

excellent --checks

You can also place a .excellent.yml file in your home directory that contains default settings you always want to apply. Settings in project-specific configuration files will override these default settings.

Excellent now also supports ignore paths. Simple place a .excellentignore file in the root directory of your project and these directories will be ignored, e.g.:


Static analysis

A few words regarding static code analysis: Static code analysis tools like Excellent can never really understand the code. They just search for patterns that might inidicate problematic code. The word might really has to be stressed here since static analysis will usually return a reasonable number of false positives. For example, there might be pretty good reasons for empty +rescue+ blocks that suppress all errors (Excellent itself does it). So, don't try and code with the aim of passing Excellent with zero warnings. That will most likely make your code a mess. Instead use Excellent as a helper to find potentially problematic code early.


Copyright (c) 2009-2018 simplabs GmbH ( and contributors, released under the MIT license.

Excellent was inspired by roodi (, reek ( and flog (