Configuring Jarl

With the command line

Jarl comes with various options available directly from the command line. These can be listed with jarl check --help:

Check a set of files or directories

Usage: jarl check [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          List of files or directories to check or fix lints, for example `jarl check .`.

Options:
  -f, --fix
          Automatically fix issues detected by the linter.

  -u, --unsafe-fixes
          Include fixes that may not retain the original intent of the  code.

      --fix-only
          Apply fixes to resolve lint violations, but don't report on leftover violations. Implies `--fix`.

      --allow-dirty
          Apply fixes even if the Git branch is not clean, meaning that there are uncommitted files.

      --allow-no-vcs
          Apply fixes even if there is no version control system.

  -s, --select-rules <SELECT_RULES>
          Names of rules to include, separated by a comma (no spaces). This also accepts names of groups of rules, such as "PERF".

          [default: ]

  -i, --ignore-rules <IGNORE_RULES>
          Names of rules to exclude, separated by a comma (no spaces). This also accepts names of groups of rules, such as "PERF".

          [default: ]

  -w, --with-timing
          Show the time taken by the function.

  -m, --min-r-version <MIN_R_VERSION>
          The mimimum R version to be used by the linter. Some rules only work starting from a specific version.

      --output-format <OUTPUT_FORMAT>
          Output serialization format for violations.

          Possible values:
          - full:    Print diagnostics with full context using annotated code snippets
          - concise: Print diagnostics in a concise format, one per line
          - github:  Print diagnostics as GitHub format
          - json:    Print diagnostics as JSON

          [default: full]

      --assignment-op <ASSIGNMENT_OP>
          Assignment operator to use, can be either `<-` or `=`.

  -h, --help
          Print help (see a summary with '-h')

You can pass multiple options at once, for instance

jarl check . --fix --select-rules any_is_na,class_equals

With a config file

To avoid typing options every time and to ensure all uses of Jarl in a project are consistent, it is possible to store options in jarl.toml.

This file looks like this:

[lint]
select = []
ignore = []
exclude = []
default-exclude = true
assignment = "<-"

These arguments are described below.

NoteUsing CLI arguments and jarl.toml

Arguments in the command line always have the priority on those specified in jarl.toml. For example, if you have the following file:

[lint]
select = ["PERF", "length_test"]
ignore = []

then calling

jarl check . --ignore-rules PERF

will only apply the rule length_test.

select

Select some rules by default.

This has the same capabilities as --select-rules, so it is possible to pass rule names and names of groups of rules:

[lint]
select = ["PERF", "length_test"]

ignore

Ignore some rules by default.

This has the same capabilities as --ignore-rules, so it is possible to pass rule names and names of groups of rules:

[lint]
ignore = ["PERF", "length_test"]

exclude

Files and/or directories that are not checked.

This takes a list relative paths to ignore:

[lint]
exclude = ["excluded.R", "tests/"]

It also supports glob patterns:

[lint]
exclude = ["excluded-*.R"]

default-exclude

This takes a boolean argument indicating whether the default file exclude patterns are used.

By default, Jarl (just like the Air formatter) excludes a set of files and folders that are probably not worth checking, for instance because they are automatically generated by another program.

The complete list of default exclude patterns is:

  • .git/
  • renv/
  • revdep/
  • cpp11.R
  • RcppExports.R
  • extendr-wrappers.R
  • import-standalone-*.R
[lint]
default-exclude = true

assignment

This takes a single value ("<-" or "=") indicating the preferred assignment operator in the files to check. While "<-" is recommended by several style guides, using "=" is equivalent in most cases and several popular projects use it.

This parameter is only useful if the assignment rule is active. If assignment = "<-" (default), then any use of the "=" operator to assign values will be reported, and vice-versa.

[lint]
assignment = "<-"

fixable

This determines which rule violations will be fixed if --fix is passed. It takes a list of rule names or names or groups of rules, and defaults to all rules if this argument is not specified.

If a rule appears in both fixable and unfixable, unfixable takes precedence (i.e. violations of this rule will not be fixed).

[lint]
# Only fix violations of rules in the "PERF" group.
fixable = ["PERF"]
[lint]
# Do not fix any violation.
fixable = []

unfixable

This determines which rule violations will be not fixed, even if --fix is passed. It takes a list of rule names or names or groups of rules, and defaults no rules if this argument is not specified.

If a rule appears in both fixable and unfixable, unfixable takes precedence (i.e. violations of this rule will not be fixed).

[lint]
# Fix all violations, except those for rules in the "PERF" group.
unfixable = ["PERF"]
[lint]
# Fix all violations.
unfixable = []