Grit Configuration

Grit does not require any configuration to use patterns from the standard library.

If you need to customize Grit's behavior further, add a .grit/grit.yaml file in your repository.

SHELL
/repo
├── .grit
│ └── grit.yaml
├── foobar
| └── baz
├── src
└── etc

A Grit configuration might look like this.

grit.yaml
version: 0.0.1
patterns:
  - name: avoid_only
    tags: ['style', 'debugging']
    level: error
    body: |
      `$testlike.only` => `$testlike` where {
        `$testlike` <: or {
          `describe`
          `it`
          `test`
        }
      }
    description: |
      .only is usually a mistake left over from local debugging. Pushing it to
      main risks false negatives on CI.
  - name: disabled_pattern
    level: none # This pattern is disabled
    body: |
      `something` => `somewhere`

Configuration Reference

Grit can be configured using a .grit/grit.yaml file. The file is in YAML format.

Patterns

The patterns field is a list of patterns which are applicable to your codebase.

Each pattern can specify the following fields:

  • name: (Required, string) The name of the pattern. Conventionally in snake case.
  • body: (Optional, string) The body of the pattern. This is useful for short, inline patterns. If not provided, the pattern should either be imported from a remote Grit module, or defined in a separate file within the .grit directory.
  • level: (Optional, one of none, info, warn, error) The enforcement level of the pattern for running diagnostics via grit check. Defaults to info.
  • title: (Optional, string) A short, human-readable title for the pattern. Defaults to the name if not set.
  • description: (Optional, string) A longer description of the pattern.
  • tags: (Optional, string[]) A list of tags which can be used to filter patterns.

Note: You do not need to list patterns which are defined in Markdown or .grit files, they are automatically merged in.

Imported Patterns

The patterns listed in the patterns field don't need be local to your module. If you want to enable a pattern from another module, you just need to name it in your list, prefixed with the module name and a #.

For example, to enable the no_console_log pattern from the JavaScript standard library, you would add the following to your grit.yaml file.

grit.yaml
patterns:
  - name: github.com/getgrit/stdlib#no_console_log

If you want to enable all patterns from another module, just use a * for the pattern name.

For example, to enable all patterns from the standard library, you would add the following to your grit.yaml file.

grit.yaml
patterns:
  - name: github.com/getgrit/stdlib#*

By default, all patterns from the standard library are automatically imported. If you define custom patterns, make sure their names don't conflict with the standard library.

Grit modules are simply referenced by their git URL. This means that you can import configurations from any git repository, including private repositories.

To download remote patterns, run the grit init command through the Grit CLI. Grit searches up the directory tree from your current working directory to find the nearest grit.yaml config. For each remote gritmodule specified in the config, Grit clones a sparse, shallow copy of the repository's root .grit directory into your local .gritmodules directory. Because the remote module's pattern can itself be a reference to another module's pattern, Grit recursively traverses the dependency graph and downloads all modules referenced by grit.yaml files (but only the patterns specified in your grit.yaml will be enforced).

Since gritmodules' patterns are identified by their root .grit/grit.yaml file, you must ensure that any patterns you wish to export from a repository you are using as a remote gritmodule are exposed in the root grit.yaml.

Note: The result of the pattern module downloading process is flat. Defining two patterns with the same name in different modules will cause an error. Grit considers all pattern names that are referenced within modules in the dependency graph, so you may get a pattern naming conflict even if you don't directly reference the conflicting pattern in your grit.yaml file.

Version

The version field specifies the version of this configuration file. We follow semantic versioning. The current version is 0.0.2.

grit.yaml
version: 0.0.2

GitHub

The GitHub field contains GitHub-specific configuration.

Reviewers

The reviewers field is a list of GitHub users and teams which will be requested to review pull requests opened by Grit. Teams should be prefixed with an @ symbol and use the full team name, including the organization.

grit.yaml
version: 0.0.2
patterns: []
github:
  reviewers:
    - gritbot
    - "@getgrit/core"

.gritignore files

By default, Grit will ignore any files listed in your .gitignore file and any files in a .grit directory.

You can tell Grit to ignore additional files and directories by creating .gritignore files. A .gritignore file is a plain text file where each line is a glob pattern indicating which paths should be omitted from Grit's analysis. For example, the following omits all JavaScript files:

.gritignore
**/*.js

.gritignore files are cascading, so you can define them at multiple levels of the directory hierarchy. The exact semantics are detailed here.

Pattern suppression

Named GritQL patterns can be suppressed for a particular line by adding a comment with the grit-ignore directive alongside or above the line to be disabled.

PATTERN
`console.$method($message)` => `console.info($message)`
INPUTOUTPUT
console.log('Hello, world!');
// grit-ignore
console.error('Can you hear me?');
console.info('Hello, world!');
console.error('Can you hear me?');

To suppress only a particular set of rules, include their comma-separated names after the grit-ignore directive:

index.js
console.log('This will be rewritten!')
// grit-ignore no_console_log, replace_console_log
console.log('This won't!')

Then when the patterns no_console_log or replace_console_log are invoked by name, such as by running grit apply no_console_log, the second console.log statement will not be rewritten.

Additional context can be added after the rule names, separated by a colon:

index.py
print('Hello world!') # grit-ignore print_to_log: We want to keep this

User configuration

In addition to the repository-level configuration described above, Grit also supports user-level configuration under a user .grit/patterns directory. By default, this is located in your home directory at ~/.grit/patterns. You can override its location by setting the GRIT_USER_CONFIG environment variable to point at a .grit directory of your choice.

Repository patterns always take precedence over user patterns. If a pattern is defined in both the repository and user configuration, the repository pattern will be used. User patterns cannot be imported by repository configurations, but can be applied through grit apply invocations on the CLI.