scss-lint is a tool to help keep your SCSS files clean and readable. You can run it manually from the command-line, or integrate it into your SCM hooks. It uses rules established by the team at Causes.com.

• Requirements
• Installation
• Usage
• Configuration
• Formatters
• Exit Status Codes
• Linters
• Editor Integration
• Git Integration
• Documentation
• Contributing
• Changelog
• License

• Ruby 1.9.3+
• Sass 3.4+ (scss-lint 0.27.0 was the last version to support Sass 3.3)
• Files you wish to lint must be written in SCSS (not Sass) syntax

gem install scss-lint

Run scss-lint from the command-line by passing in a directory (or multiple directories) to recursively scan:

scss-lint app/assets/stylesheets/

You can also specify a list of files explicitly:

scss-lint app/assets/stylesheets/**/*.css.scss

scss-lint will output any problems with your SCSS, including the offending filename and line number (if available).

scss-lint will automatically recognize and load any file with the name .scss-lint.yml as a configuration file. It loads the configuration based on the location of the file being linted, starting from that file's directory and ascending until a configuration file is found. Any configuration loaded is automatically merged with the default configuration (see config/default.yml).

Here's an example configuration file:

inherit_from: '../../inherited-config.yml'

scss_files: 'app/assets/stylesheets/**/*.css.scss'

exclude: 'app/assets/stylesheets/plugins/**'

linters:
  BorderZero:
    enabled: false

  Indentation:
    exclude:
      - 'path/to/file.scss'
      - 'path/to/directory/**'
    severity: warning
    width: 2

All linters have an enabled option which can be true or false, which controls whether the linter is run, along with linter-specific options. The defaults are defined in config/default.yml.

The severity option allows you to specify whether the lint should be treated as a warning or an error. Warnings cause scss-lint to exit with a different error code than errors (unless both warnings and errors are present, in which case the error exit code is returned). This is useful when integrating scss-lint with build systems or other executables, as you can rely on its exit status code to indicate whether a lint actually requires attention.

The inherit_from directive allows a configuration file to inherit settings from another configuration file. The file specified by inherit_from is loaded and then merged with the settings in the current file (settings in the current file overrule those in the inherited file).

The exclude directive allows you to specify a glob pattern of files that should not be linted by scss-lint. Paths are relative to the location of the config file itself if they are not absolute paths. If an inherited file specifies the exclude directive, the two exclusion lists are combined. Any additional exclusions specified via the --exclude flag are also combined. If you need to exclude files for a single linter you can specify the list of files using the linter's exclude configuration option.

You can also configure scss-lint by specifying a file via the --config flag, but note that this will override any configuration files that scss-lint would normally find on its own (this can be useful for testing a particular configuration setting, however). Configurations loaded this way will still be merged with the default configuration specified by config/default.yml.

To start using scss-lint you can use the Config Formatter, which will generate an .scss-lint.yml configuration file with all linters which caused a lint disabled. Starting with this as your configuration you can slowly enable each linter and fix any lints one by one.

The default formatter is intended to be easy to consume by both humans and external tools.

scss-lint [scss-files...]

test.scss:2 [W] StringQuotes: Prefer single quoted strings
test.scss:2 [W] Indentation: Line should be indented 0 spaces, but was indented 1 space
test.scss:5 [W] StringQuotes: Prefer single quoted strings
test.scss:6 [W] UrlQuotes: URLs should be enclosed in quotes

The default formatter tries to colorize the output using Rainbow, which will silently fail on Windows systems if the gems windows-pr and win32console are not installed. Read more about adding Windows support.

Returns a valid .scss-lint.yml configuration where all linters which caused a lint are disabled. Starting with this as your configuration, you can slowly enable each linter and fix any lints one by one.

scss-lint --format=Config [scss-files...]

linters:
  Indentation:
    enabled: false
  StringQuotes:
    enabled: false
  UrlQuotes:
    enabled: false

Useful when you just want to open all offending files in an editor. This will just output the names of the files so that you can execute the following to open them all:

scss-lint --format=Files [scss-files...] | xargs vim

Outputs JSON with filenames and an array of issue objects.

{
  "test.css": [
    {"line": 2, "severity": "warning", "reason": "Prefer single quoted strings"},
    {"line": 2, "severity": "warning", "reason": "Line should be indented 0 spaces, but was indented 1 spaces"},
    {"line": 5, "severity": "warning", "reason": "Prefer single quoted strings"},
    {"line": 6, "severity": "warning", "reason": "URLs should be enclosed in quotes"}
  ]
}

Outputs XML with <lint>, <file>, and <issue> tags. Suitable for consumption by tools like Jenkins.

scss-lint --format=XML [scss-files...]

<?xml version="1.0" encoding="utf-8"?>
<lint>
  <file name="test.css">
    <issue line="2" severity="warning" reason="Prefer single quoted strings" />
    <issue line="2" severity="warning" reason="Line should be indented 0 spaces, but was indented 1 spaces" />
    <issue line="5" severity="warning" reason="Prefer single quoted strings" />
    <issue line="6" severity="warning" reason="URLs should be enclosed in quotes" />
  </file>
</lint>

scss-lint tries to use semantic exit statuses wherever possible, but the full list of codes and the conditions under which they are returned is listed here for completeness.

scss-lint is a customizable tool with opinionated defaults that helps you enforce a consistent style in your SCSS. For these opinionated defaults, we've had to make calls about what we think are the "best" style conventions, even when there are often reasonable arguments for more than one possible style.

Should you want to customize the checks run against your code, you can do so by editing your configuration file to match your preferred style.

###» Linters Documentation

You can have scss-lint automatically run against your SCSS files after saving by using the Syntastic plugin. If you already have the plugin, just add let g:syntastic_scss_checkers = ['scss_lint'] to your .vimrc.

Install the Sublime scss-lint plugin.

Install the Atom scss-lint plugin. It is a part of the atomlinter project, so if you are already using other linter plugins, you can keep them in one place.

Install and enable both scss-mode and flycheck-mode. You can enable automatic linting for scss-mode buffers with (add-hook 'scss-mode-hook 'flycheck-mode) in your init.el.

If you'd like to integrate scss-lint into your Git workflow, check out our Git hook manager, overcommit.

Code documentation is generated with YARD and hosted by RubyDoc.info.

We love getting feedback with or without pull requests. If you do add a new feature, please add tests so that we can avoid breaking it in the future.

Speaking of tests, we use rspec, which can be run like so:

bundle exec rspec

If you're interested in seeing the changes and bug fixes between each version of scss-lint, read the SCSS-Lint Changelog.

This project is released under the MIT license.