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.

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

A Grit configuration might look like this.

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`

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

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.

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.

patterns:
  - name: github.com/getgrit/js#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 JavaScript standard library, you would add the following to your grit.yaml file.

patterns:
  - name: github.com/getgrit/js#*

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.

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.

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

version: 0.0.2

By default, Grit will ignore any files listed in your .gitignore file and any files within hidden directories (those starting with a dot .).

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:

**/*.js

You can also tell Grit to analyze hidden directories by adding them to your .gritignore with a ! prefix:

!.hidden/

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

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.

`console.$method($message)` => `console.info($message)`

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:

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:

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