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`
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 ofnone
,info
,warn
,error
) The enforcement level of the pattern for running diagnostics viagrit check
. Defaults toinfo
.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.
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.
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
.
version: 0.0.2
.gritignore
files
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.
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.
`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