RuboCop<\/strong> is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide.<\/p>\nMost aspects of its behavior can be tweaked via various configuration options.<\/p>\n
Apart from reporting problems in your code, RuboCop can also automatically fix some of the problems for you.<\/p>\n
![](\"http:\/\/badges.gitter.im\/Join%20Chat.svg\")
<\/p>\n
You can support my work on RuboCop and all my other projects via gratipay.<\/p>\n
![](\"http:\/\/cdn.rawgit.com\/gratipay\/gratipay-badge\/2.1.3\/dist\/gratipay.png\")
<\/p>\n
This documentation tracks the master<\/code> branch of RuboCop. Some of the features and settings discussed here might not be available in older releases (including the current stable release). Please, consult the relevant git tag (e.g. v0.30.0) if you need documentation for a specific RuboCop release.<\/strong><\/p>\nInstallation<\/h2>\n
RuboCop<\/strong>‘s installation is pretty standard:<\/p>\n$ gem install rubocop\n<\/code><\/pre>\nIf you\u2019d rather install RuboCop using bundler<\/code>, don\u2019t require it in your Gemfile<\/code>:<\/p>\ngem 'rubocop', require: false\n<\/code><\/pre>\nBasic Usage<\/h2>\n
Running rubocop<\/code> with no arguments will check all Ruby source files in the current directory:<\/p>\n$ rubocop\n<\/code><\/pre>\nAlternatively you can pass rubocop<\/code> a list of files and directories to check:<\/p>\n$ rubocop app spec lib\/something.rb\n<\/code><\/pre>\nHere\u2019s RuboCop in action. Consider the following Ruby source code:<\/p>\n
def badName\n if something\n test\n end\nend\n<\/code><\/pre>\nRunning RuboCop on it (assuming it\u2019s in a file named test.rb<\/code>) would produce the following report:<\/p>\nInspecting 1 file\nW\n\nOffenses:\n\ntest.rb:1:5: C: Use snake_case for method names.\ndef badName\n ^^^^^^^\ntest.rb:2:3: C: Use a guard clause instead of wrapping the code inside a conditional expression.\n if something\n ^^\ntest.rb:2:3: C: Favor modifier if usage when having a single-line body. Another good alternative is the usage of control flow &&\/||.\n if something\n ^^\ntest.rb:4:5: W: end at 4, 4 is not aligned with if at 2, 2\n end\n ^^^\n\n1 file inspected, 4 offenses detected\n<\/code><\/pre>\nFor more details check the available command-line options:<\/p>\n
$ rubocop -h\n<\/code><\/pre>\n\n\n| Command flag<\/th>\n | Description<\/th>\n<\/tr>\n |
\n-v\/--version<\/code><\/td>\n| Displays the current version and exits.<\/td>\n<\/tr>\n | \n-V\/--verbose-version<\/code><\/td>\n| Displays the current version plus the version of Parser and Ruby.<\/td>\n<\/tr>\n | \n-F\/--fail-fast<\/code><\/td>\n| Inspects in modification time order and stops after first file with offenses.<\/td>\n<\/tr>\n | \n-d\/--debug<\/code><\/td>\n| Displays some extra debug output.<\/td>\n<\/tr>\n | \n-D\/--display-cop-names<\/code><\/td>\n| Displays cop names in offense messages.<\/td>\n<\/tr>\n | \n-c\/--config<\/code><\/td>\n| Run with specified config file.<\/td>\n<\/tr>\n | \n-f\/--format<\/code><\/td>\n| Choose a formatter.<\/td>\n<\/tr>\n | \n-o\/--out<\/code><\/td>\n| Write output to a file instead of STDOUT.<\/td>\n<\/tr>\n | \n-r\/--require<\/code><\/td>\n| Require Ruby file (see Loading Extensions).<\/td>\n<\/tr>\n | \n-R\/--rails<\/code><\/td>\n| Run extra Rails cops.<\/td>\n<\/tr>\n | \n-l\/--lint<\/code><\/td>\n| Run only lint cops.<\/td>\n<\/tr>\n | \n-a\/--auto-correct<\/code><\/td>\nAuto-correct certain offenses. Note:<\/em> Experimental – use with caution.<\/td>\n<\/tr>\n\n--only<\/code><\/td>\n| Run only the specified cop(s) and\/or cops in the specified departments.<\/td>\n<\/tr>\n | \n--except<\/code><\/td>\n| Run all cops enabled by configuration except the specified cop(s) and\/or departments.<\/td>\n<\/tr>\n | \n--auto-gen-config<\/code><\/td>\n| Generate a configuration file acting as a TODO list.<\/td>\n<\/tr>\n | \n--show-cops<\/code><\/td>\n| Shows available cops and their configuration.<\/td>\n<\/tr>\n | \n--fail-level<\/code><\/td>\nMinimum severity for exit with error code. Full severity name or upper case initial can be given. Normally, auto-corrected offenses are ignored. Use A<\/code> or autocorrect<\/code> if you\u2019d like them to trigger failure.<\/td>\n<\/tr>\n<\/table>\nCops<\/h3>\nIn RuboCop lingo the various checks performed on the code are called cops. There are several cop departments.<\/p>\n You can also load custom cops.<\/p>\n Style<\/h4>\nMost of the cops in RuboCop are so called style cops that check for stylistics problems in your code. Almost all of the them are based on the Ruby Style Guide. Many of the style cops have configurations options allowing them to support different popular coding conventions.<\/p>\n Lint<\/h4>\nLint cops check for possible errors and very bad practices in your code. RuboCop implements in a portable way all built-in MRI lint checks (ruby -wc<\/code>) and adds a lot of extra lint checks of its own. You can run only the lint cops like this:<\/p>\n$ rubocop -l\n<\/code><\/pre>\nThe -l<\/code>\/--lint<\/code> option can be used together with --only<\/code> to run all the enabled lint cops plus a selection of other cops.<\/p>\nDisabling any of the lint cops is generally a bad idea.<\/p>\n Metrics<\/h4>\nMetrics cops deal with properties of the source code that can be measured, such as class length, method length, etc. Generally speaking, they have a configuration parameter called Max<\/code> and when running rubocop --auto-gen-config<\/code>, this parameter will be set to the highest value found for the inspected code.<\/p>\nRails<\/h4>\nRails cops are specific to the Ruby on Rails framework. Unlike style and lint cops they are not used by default and you have to request them specifically:<\/p>\n $ rubocop -R\n<\/code><\/pre>\nor add the following directive to your .rubocop.yml<\/code>:<\/p>\nAllCops:\n RunRailsCops: true\n<\/code><\/pre>\nConfiguration<\/h2>\nThe behavior of RuboCop can be controlled via the .rubocop.yml configuration file. It makes it possible to enable\/disable certain cops (checks) and to alter their behavior if they accept any parameters. The file can be placed either in your home directory or in some project directory.<\/p>\n RuboCop will start looking for the configuration file in the directory where the inspected file is and continue its way up to the root directory.<\/p>\n The file has the following format:<\/p>\n inherit_from: ..\/.rubocop.yml\n\nStyle\/Encoding:\n Enabled: false\n\nMetrics\/LineLength:\n Max: 99\n<\/code><\/pre>\nNote<\/strong>: Qualifying cop name with its type, e.g., Style<\/code>, is recommended, but not necessary as long as the cop name is unique across all types.<\/p>\nInheritance<\/h3>\nThe optional inherit_from<\/code> directive is used to include configuration from one or more files. This makes it possible to have the common project settings in the .rubocop.yml<\/code> file at the project root, and then only the deviations from those rules in the subdirectories. The files can be given with absolute paths or paths relative to the file where they are referenced. The settings after an inherit_from<\/code> directive override any settings in the file(s) inherited from. When multiple files are included, the first file in the list has the lowest precedence and the last one has the highest. The format for multiple inheritance is:<\/p>\ninherit_from:\n - ..\/.rubocop.yml\n - ..\/conf\/.rubocop.yml\n<\/code><\/pre>\nDefaults<\/h3>\nThe file config\/default.yml under the RuboCop home directory contains the default settings that all configurations inherit from. Project and personal .rubocop.yml<\/code> files need only make settings that are different from the default ones. If there is no .rubocop.yml<\/code> file in the project or home directory, config\/default.yml<\/code> will be used.<\/p>\nIncluding\/Excluding files<\/h3>\nRuboCop checks all files found by a recursive search starting from the directory it is run in, or directories given as command line arguments. However, it only recognizes files ending with .rb<\/code> or extensionless files with a #!.*ruby<\/code> declaration as Ruby files. Hidden directories (i.e., directories whose names start with a dot) are not searched by default. If you\u2019d like it to check files that are not included by default, you\u2019ll need to pass them in on the command line, or to add entries for them under AllCops<\/code>\/Include<\/code>. Files and directories can also be ignored through AllCops<\/code>\/Exclude<\/code>.<\/p>\nHere is an example that might be used for a Rails project:<\/p>\n AllCops:\n Include:\n - '**\/Rakefile'\n - '**\/config.ru'\n Exclude:\n - 'db\/**\/*'\n - 'config\/**\/*'\n - 'script\/**\/*'\n - !ruby\/regexp \/old_and_unused\\.rb$\/\n\n# other configuration\n# ...\n<\/code><\/pre>\nFiles and directories are specified relative to the .rubocop.yml<\/code> file.<\/p>\nNote<\/strong>: Patterns that are just a file name, e.g. Rakefile<\/code>, will match that file name in any directory, but this pattern style deprecated. The correct way to match the file in any directory, including the current, is **\/Rakefile<\/code>.<\/p>\nNote<\/strong>: The pattern config\/**<\/code> will match any file recursively under config<\/code>, but this pattern style is deprecated and should be replaced by config\/**\/*<\/code>.<\/p>\nNote<\/strong>: The Include<\/code> and Exclude<\/code> parameters are special. They are valid for the directory tree starting where they are defined. They are not shadowed by the setting of Include<\/code> and Exclude<\/code> in other .rubocop.yml<\/code> files in subdirectories. This is different from all other parameters, who follow RuboCop\u2019s general principle that configuration for an inspected file is taken from the nearest .rubocop.yml<\/code>, searching upwards.<\/p>\nCops can be run only on specific sets of files when that\u2019s needed (for instance you might want to run some Rails model checks only on files whose paths match app\/models\/*.rb<\/code>). All cops support the Include<\/code> param.<\/p>\nRails\/DefaultScope:\n Include:\n - app\/models\/*.rb\n<\/code><\/pre>\nCops can also exclude only specific sets of files when that\u2019s needed (for instance you might want to run some cop only on a specific file). All cops support the Exclude<\/code> param.<\/p>\nRails\/DefaultScope:\n Exclude:\n - app\/models\/problematic.rb\n<\/code><\/pre>\nGeneric configuration parameters<\/h3>\nIn addition to Include<\/code> and Exclude<\/code>, the following parameters are available for every cop.<\/p>\nEnabled<\/h4>\nSpecific cops can be disabled by setting Enabled<\/code> to false<\/code> for that specific cop.<\/p>\nMetrics\/LineLength:\n Enabled: false\n<\/code><\/pre>\nSeverity<\/h4>\nEach cop has a default severity level based on which department it belongs to. The level is warning<\/code> for Lint<\/code> and convention<\/code> for all the others. Cops can customize their severity level. Allowed params are refactor<\/code>, convention<\/code>, warning<\/code>, error<\/code> and fatal<\/code>.<\/p>\nThere is one exception from the general rule above and that is Lint\/Syntax<\/code>, a special cop that checks for syntax errors before the other cops are invoked. It can not be disabled and its severity (fatal<\/code>) can not be changed in configuration.<\/p>\nMetrics\/CyclomaticComplexity:\n Severity: warning\n<\/code><\/pre>\nAutoCorrect<\/h4>\nCops that support the --auto-correct<\/code> option can have that support disabled. For example:<\/p>\nStyle\/PerlBackrefs:\n AutoCorrect: false\n<\/code><\/pre>\nAutomatically Generated Configuration<\/h3>\nIf you have a code base with an overwhelming amount of offenses, it can be a good idea to use rubocop --auto-gen-config<\/code> and add an inherit_from: .rubocop_todo.yml<\/code> in your .rubocop.yml<\/code>. The generated file .rubocop_todo.yml<\/code> contains configuration to disable all cops that currently detect an offense in the code. Then you can start removing the entries in the generated file one by one as you work through all the offenses in the code.<\/p>\nDisabling Cops within Source Code<\/h2>\nOne or more individual cops can be disabled locally in a section of a file by adding a comment such as<\/p>\n # rubocop:disable Metrics\/LineLength, Style\/StringLiterals\n[...]\n# rubocop:enable Metrics\/LineLength, Style\/StringLiterals\n<\/code><\/pre>\nYou can also disable all<\/em> cops with<\/p>\n# rubocop:disable all\n[...]\n# rubocop:enable all\n<\/code><\/pre>\nOne or more cops can be disabled on a single line with an end-of-line comment.<\/p>\n for x in (0..19) # rubocop:disable Style\/AvoidFor\n<\/code><\/pre>\nFormatters<\/h2>\nYou can change the output format of RuboCop by specifying formatters with the -f\/--format<\/code> option. RuboCop ships with several built-in formatters, and also you can create your custom formatter.<\/p>\nAdditionally the output can be redirected to a file instead of $stdout<\/code> with the -o\/--out<\/code> option.<\/p>\nSome of the built-in formatters produce machine-parsable<\/strong> output and they are considered public APIs. The rest of the formatters are for humans, so parsing their outputs is discouraged.<\/p>\nYou can enable multiple formatters at the same time by specifying -f\/--format<\/code> multiple times. The -o\/--out<\/code> option applies to the previously specified -f\/--format<\/code>, or the default progress<\/code> format if no -f\/--format<\/code> is specified before the -o\/--out<\/code> option.<\/p>\n# Simple format to $stdout.\n$ rubocop --format simple\n\n# Progress (default) format to the file result.txt.\n$ rubocop --out result.txt\n\n# Both progress and offense count formats to $stdout.\n# The offense count formatter outputs only the final summary,\n# so you'll mostly see the outputs from the progress formatter,\n# and at the end the offense count summary will be outputted.\n$ rubocop --format progress --format offenses\n\n# Progress format to $stdout, and JSON format to the file rubocop.json.\n$ rubocop --format progress --format json --out rubocop.json\n# ~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~\n# | |_______________|\n# $stdout\n\n# Progress format to result.txt, and simple format to $stdout.\n$ rubocop --output result.txt --format simple\n# ~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~\n# | |\n# default format $stdout\n<\/code><\/pre>\nYou can also load custom formatters.<\/p>\n Progress Formatter (default)<\/h3>\nThe default progress<\/code> formatter outputs a character for each inspected file, and at the end it displays all detected offenses in the clang<\/code> format. A .<\/code> represents a clean file, and each of the capital letters means the severest offense (convention, warning, error or fatal) found in a file.<\/p>\n$ rubocop\nInspecting 26 files\n..W.C....C..CWCW.C...WC.CC\n\nOffenses:\n\nlib\/foo.rb:6:5: C: Missing top-level class documentation comment.\n class Foo\n ^^^^^\n\n...\n\n26 files inspected, 46 offenses detected\n<\/code><\/pre>\nClang Style Formatter<\/h3>\nThe clang<\/code> formatter displays the offenses in a manner similar to clang<\/code>:<\/p>\n$ rubocop test.rb\nInspecting 1 file\nW\n\nOffenses:\n\ntest.rb:1:5: C: Use snake_case for method names.\ndef badName\n ^^^^^^^\ntest.rb:2:3: C: Use a guard clause instead of wrapping the code inside a conditional expression.\n if something\n ^^\ntest.rb:2:3: C: Favor modifier if usage when having a single-line body. Another good alternative is the usage of control flow &&\/||.\n if something\n ^^\ntest.rb:4:5: W: end at 4, 4 is not aligned with if at 2, 2\n end\n ^^^\n\n1 file inspected, 4 offenses detected\n<\/code><\/pre>\nFuubar Style Formatter<\/h3>\nThe fuubar<\/code> style formatter displays a progress bar and shows details of offenses in the clang<\/code> format as soon as they are detected. This is inspired by the Fuubar formatter for RSpec.<\/p>\n$ rubocop --format fuubar\nlib\/foo.rb.rb:1:1: C: Use snake_case for methods and variables.\ndef badName\n ^^^^^^^\nlib\/bar.rb:13:14: W: File.exists? is deprecated in favor of File.exist?.\n File.exists?(path)\n ^^^^^^^\n 22\/53 files |======== 43 ========> | ETA: 00:00:02\n<\/code><\/pre>\nEmacs Style Formatter<\/h3>\nMachine-parsable<\/strong><\/p>\nThe emacs<\/code> formatter displays the offenses in a format suitable for consumption by Emacs<\/code> (and possibly other tools).<\/p>\n$ rubocop --format emacs test.rb\n\/Users\/bozhidar\/projects\/test.rb:1:1: C: Use snake_case for methods and variables.\n\/Users\/bozhidar\/projects\/test.rb:2:3: C: Favor modifier if\/unless usage when you have a single-line body. Another good alternative is the usage of control flow &&\/||.\n\/Users\/bozhidar\/projects\/test.rb:4:5: W: end at 4, 4 is not aligned with if at 2, 2\n<\/code><\/pre>\nSimple Formatter<\/h3>\nThe name of the formatter says it all \ud83d\ude42<\/p>\n $ rubocop --format simple test.rb\n== test.rb ==\nC: 1: 5: Use snake_case for method names.\nC: 2: 3: Use a guard clause instead of wrapping the code inside a conditional expression.\nC: 2: 3: Favor modifier if usage when having a single-line body. Another good alternative is the usage of control flow &&\/||.\nW: 4: 5: end at 4, 4 is not aligned with if at 2, 2\n\n1 file inspected, 4 offenses detected\n<\/code><\/pre>\nFile List Formatter<\/h3>\nMachine-parsable<\/strong><\/p>\nSometimes you might want to just open all files with offenses in your favorite editor. This formatter outputs just the names of the files with offenses in them and makes it possible to do something like:<\/p>\n $ rubocop --format files | xargs vim\n<\/code><\/pre>\nJSON Formatter<\/h3>\nMachine-parsable<\/strong><\/p>\nYou can get RuboCop\u2019s inspection result in JSON format by passing --format json<\/code> option in command line. The JSON structure is like the following example:<\/p>\n{\n \"metadata\": {\n \"rubocop_version\": \"0.9.0\",\n \"ruby_engine\": \"ruby\",\n \"ruby_version\": \"2.0.0\",\n \"ruby_patchlevel\": \"195\",\n \"ruby_platform\": \"x86_64-darwin12.3.0\"\n },\n \"files\": [{\n \"path\": \"lib\/foo.rb\",\n \"offenses\": []\n }, {\n \"path\": \"lib\/bar.rb\",\n \"offenses\": [{\n \"severity\": \"convention\",\n \"message\": \"Line is too long. [81\/80]\",\n \"cop_name\": \"LineLength\",\n \"corrected\": true,\n \"location\": {\n \"line\": 546,\n \"column\": 80,\n \"length\": 4\n }\n }, {\n \"severity\": \"warning\",\n \"message\": \"Unreachable code detected.\",\n \"cop_name\": \"UnreachableCode\",\n \"corrected\": false,\n \"location\": {\n \"line\": 15,\n \"column\": 9,\n \"length\": 10\n }\n }\n ]\n }\n ],\n \"summary\": {\n \"offense_count\": 2,\n \"target_file_count\": 2,\n \"inspected_file_count\": 2\n }\n}\n<\/code><\/pre>\nOffense Count Formatter<\/h3>\nSometimes when first applying RuboCop to a codebase, it\u2019s nice to be able to see where most of your style cleanup is going to be spent.<\/p>\n With this in mind, you can use the offense count formatter to outline the offended cops and the number of offenses found for each by running:<\/p>\n $ rubocop --format offenses\n\n87 Documentation\n12 DotPosition\n8 AvoidGlobalVars\n7 EmptyLines\n6 AssignmentInCondition\n4 Blocks\n4 CommentAnnotation\n3 BlockAlignment\n1 IndentationWidth\n1 AvoidPerlBackrefs\n1 ColonMethodCall\n--\n134 Total\n<\/code><\/pre>\nHTML Formatter<\/h3>\nUseful for CI environments. It will create an HTML report like this.<\/p>\n $ rubocop --format html -o rubocop.html\n<\/code><\/pre>\nCompatibility<\/h2>\nRuboCop supports the following Ruby implementations:<\/p>\n \n- MRI 1.9.3<\/li>\n
- MRI 2.0<\/li>\n
- MRI 2.1<\/li>\n
- MRI 2.2<\/li>\n
- JRuby in 1.9 mode<\/li>\n
- Rubinius 2.0+<\/li>\n<\/ul>\n
Editor integration<\/h2>\n
| | | | | | | | | | | | | | | | | | |
![](\"http:\/\/badge.fury.io\/rb\/rubocop.svg\"){kind=icon}
![](\"http:\/\/gemnasium.com\/bbatsov\/rubocop.svg\")
![](\"http:\/\/travis-ci.org\/bbatsov\/rubocop.svg?branch=master\")
![](\"http:\/\/img.shields.io\/coveralls\/bbatsov\/rubocop\/master.svg\")
![](\"http:\/\/codeclimate.com\/github\/bbatsov\/rubocop\/badges\/gpa.svg\")
![](\"http:\/\/inch-ci.org\/github\/bbatsov\/rubocop.svg\")
![](\"http:\/\/img.shields.io\/gratipay\/bbatsov.svg\")
<\/p>\n![](\"http:\/\/raw.github.com\/bbatsov\/rubocop\/master\/logo\/rubo-logo-horizontal.png\"){kind=logo}
<\/p>\n