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 <SELECT>
          Names of rules to include, separated by a comma (no spaces). This also accepts names of groups of rules, such as "PERF".

          [default: ]

  -e, --extend-select <EXTEND_SELECT>
          Like `--select` but adds additional rules in addition to those already specified.

          [default: ]

  -i, --ignore <IGNORE>
          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 <ASSIGNMENT>
          [DEPRECATED: use `[lint.assignment]` in jarl.toml] Assignment operator to use, can be either `<-` or `=`.

      --no-default-exclude
          Do not apply the default set of file patterns that should be excluded.

      --statistics
          Show counts for every rule with at least one violation.

      --add-jarl-ignore[=<REASON>]
          Automatically insert a `# jarl-ignore` comment to suppress all violations.
          The default reason can be customized with `--add-jarl-ignore="my_reason"`.

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

Global options:
      --log-level <LOG_LEVEL>
          The log level. One of: `error`, `warn`, `info`, `debug`, or `trace`. Defaults to `warn`

You can pass multiple options at once, for instance

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

With a config file

Introduction

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 could look like this:

[lint]
# Only report violations about performance or correctness.
select = ["PERF", "CORR"]
# If "--fix" is used, only apply automatic fixes to performance-related
# violations.
fixable = ["PERF"]
# Exclude one or several specific files.
exclude = ["R/my_custom_autogenerated_file.R"]
# Use the default set of excluded files (mostly files that are automatically
# generated by other tools).
default-exclude = true
# Set the default assignment operator to report cases where "=" is used.
assignment = "<-"

These arguments (among others) are described below.

Interaction between CLI arguments and config file

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 PERF

will only apply the rule length_test.

Config file detection

Like Ruff, Jarl follows a hierarchical strategy to detect the closest config file relative to the current working directory.

Jarl follows these steps:

  1. look for jarl.toml in the current working directory;
  2. if not present, go to the parent folder until a jarl.toml is found;
  3. if none of the parent directories contain the config file, Jarl checks if one exists in the home config directory. For Unix users, it looks for ~/.config/jarl/jarl.toml. For Windows users, it looks for ~/AppData/Roaming/jarl/jarl.toml.
  4. if the config file is not present there, then it stops looking for one.

Storing a default jarl.toml in the home config directory may be useful to apply some arguments by default on all R files. For example, if you use = as assignment operator, you can set assignment = "=" in ~/<config_dir>/jarl.toml and all R files that don’t belong to a project subject to another jarl.toml will use this argument.

Note that Jarl cannot handle multiple config files, it will use the first one it finds.

Top-level arguments

select

Select some rules by default.

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

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

extend-select

Select some rules in addition to select.

This is useful when you want to use the default set of rules and some additional opt-in rules. In this scenario, you only need to add extend-select = ["OPT_IN_RULE"] instead of writing all default rule names.

This has the same constraints as select.

# Select all default rules and all `TESTTHAT` rules, which are disabled by
# default.
[lint]
extend-select = ["TESTTHAT"]

ignore

Ignore some rules by default.

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

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

include

Files and/or directories that are checked. By default, Jarl checks all files with a .R, .qmd, .Rmd, or .rmd extension.

When both include and exclude are specified, a file is checked only if it matches at least one include pattern and does not match any exclude pattern.

This takes a list relative paths to ignore:

[lint]
include = ["foo.R", "tests/"]

It also supports glob patterns:

[lint]
# Check only Rmd and qmd files
include = ["**/*{.Rmd,qmd}"]

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 argument is deprecated. Use the rule-specific argument [lint.assignment] instead (see below).

fixable

This determines which rule violations will be fixed if --fix is passed. This can be useful if you only trust Jarl’s automatic fixes for some rules and want to avoid automatic fixes for other rules. 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. This can be useful if you only trust Jarl’s automatic fixes for some rules and want to avoid automatic fixes for other rules. 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 = []

Rule-specific arguments

assignment

This takes a single value ("<-" or "=") indicating the preferred assignment operator in the files to check. If assignment = "<-" and if the "assignment" rule is enabled, then any use of the "=" operator to assign values will be reported, and vice-versa.

This option doesn’t have a default value.

[lint]
...

[lint.assignment]
operator = "<-" # or "="

duplicated-arguments

Use skipped-functions to fully replace the default list of functions that are allowed to have duplicated arguments. Use extend-skipped-functions to add to the default list. Specifying both is an error.

Function names in skipped-functions or extend-skipped-functions also match namespaced calls, e.g. skipped-functions = ["list2"] will ignore list2() and rlang::list2().

Default: skipped-functions = ["c", "mutate", "summarize", "transmute"]

[lint]
...

[lint.duplicated-arguments]
# Ignore duplicated arguments in `list()` only.
skipped-functions = ["list"]

unreachable-code

Use stopping-functions to fully replace the default list of functions that are considered to stop execution (never return). Use extend-stopping-functions to add to the default list. Specifying both is an error.

Function names in stopping-functions or extend-stopping-functions also match namespaced calls, e.g. stopping-functions = ["abort"] will consider abort() and rlang::abort() as stopping functions.

Default: stopping-functions = ["stop", ".Defunct", "abort", "cli_abort", "q", "quit"].

[lint]
...

[lint.unreachable-code]
# Add a custom function to the list of stopping functions
extend-stopping-functions = ["my_custom_stop"]

Environment variables

This section lists all environment variables that can be used in Jarl:

  • NO_COLOR: set this to any value to remove colors from the output.
    • Example: NO_COLOR=1
  • JARL_N_VIOLATIONS_HINT_STAT: Jarl prints a hint to use --statistics if the number of violations is higher than a certain threshold. By default, this threshold is 15. This environment variable overrides this value.
    • Example: JARL_N_VIOLATIONS_HINT_STAT=25