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>
          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.

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

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:

look for jarl.toml in the current working directory;
if not present, go to the parent folder until a jarl.toml is found;
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.
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.

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"]

`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. 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 = []