Using lintr

In lintr: A 'Linter' for R Code

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette describes how to set up and configure lintr for use with projects or packages.

Running lintr on a project

Checking an R project for lints can be done with three different functions:

• Lint a single file using lint():

  r lint(filename = "R/bad.R")

• Lint a directory using lint_dir():

  r lint_dir(path = "R")

  This will apply lint() to all R source files matching the pattern argument. By default, this means all .R files as well as knitr formats (e.g. .Rmd, .Rnw).

  lint_dir is vectorized over path, so multiple directories can be linted at the same time.

• Lint all relevant directories of an R package using lint_package():

  r lint_package(path = ".")

  This will apply lint_dir() to all subdirectories usually containing R code in packages:

  • R containing the package implementation.
  • tests containing test code.
  • inst containing sample code or vignettes that will be installed along with the package.
  • vignettes containing package vignettes.
  • data-raw containing code to produce data files.

For more information about the assumed package structure, see R Packages.

Note that some linters (e.g. object_usage_linter()) require the package to be installed to function properly. pkgload::load_all() will also suffice. See ?executing_linters for more details.

Configuring linters

The .lintr file

The canonical way to configure R projects and packages for linting is to create a .lintr file in the project root. This is a file in debian control format (?read.dcf), each value of which is evaluated as R code by lintr when reading the settings. A minimal .lintr file can be generated by running use_lintr() in the project directory. Lintr supports per-project configuration of the following fields.

• linters - see ?linters_with_defaults for example of specifying only a few non-default linters and ?linters_with_tags for more fine-grained control.
• exclusions - a list of filenames to exclude from linting. You can use a named item to exclude only certain lines from a file.
• exclude - a regex pattern for lines to exclude from linting. Default is "# nolint"
• exclude_start - a regex pattern to start exclusion range. Default is "# nolint start"
• exclude_end - a regex pattern to end exclusion range. Default is "# nolint end"
• encoding - the encoding used for source files. Default inferred from .Rproj or DESCRIPTION files, fallback to UTF-8

.lintr File Example

Below is an example .lintr file that uses 120 character line lengths, disables commented_code_linter, excludes a couple of files.

linters: linters_with_defaults(
    line_length_linter(120),
    commented_code_linter = NULL
  )
exclusions: list(
    "inst/doc/creating_linters.R" = 1,
    "inst/example/bad.R",
    "tests/testthat/exclusions-test"
  )

Other configuration options

More generally, lintr searches for a settings file according to following prioritized list. The first one found, if any, will be used:

1. If options("lintr.linter_file") is an absolute path, this file will be used. The default for this option is ".lintr" or the value of the environment variable R_LINTR_LINTER_FILE, if set.
2. A project-local linter file; that is, either
   1. a linter file (that is, a file named like lintr.linter_file) in the currently-searched directory, i.e. the directory of the file passed to lint(); or
   2. a linter file in the .github/linters child directory of the currently-searched directory.
3. A project-local linter file in the closest parent directory of the currently-searched directory, starting from the deepest path, moving upwards one level at a time. When run from lint_package(), this directory can differ for each linted file.
4. A linter file in the user's HOME directory.
5. A linter file called config in the user's configuration path (given by tools::R_user_dir("lintr", which = "config")).

If no linter file is found, only default settings take effect (see defaults).

Using options()

Values in options(), if they are not NULL, take precedence over those in the linter file (e.g. .lintr). Note that the key option_name in the linter file translates to an R option lintr.option_name. For example, options(lintr.exclude = "# skip lint") will take precedence over exclude: # nolint in the linter file.

Using arguments to lint()

The settings can also be passed as arguments to linting functions directly. In case of exclusions, these will be combined with the globally parsed settings. Other settings will be overridden.

If only the specified settings should be changed, and the remaining settings should be taken directly from the defaults, the argument parse_settings = FALSE can be added to the function calls. This will suppress reading of the .lintr configuration. This is particularly useful for tests which should not exclude example files containing lints while the package-level .lintr excludes those files because the lints are intentional.

Defaults {#defaults}

The default settings of lintr are intended to conform to the tidyverse style guide. However, the behavior can be customized using different methods.

Apart from lintr.linter_file, which defaults to ".lintr", there are the following settings:

default_settings <- lintr::default_settings
default_settings$linters <- "`lintr::default_linters`"
default_settings$comment_token <- "(lintr-bot comment token for automatic GitHub comments)"
default_settings$exclusions <- "(empty)"

make_string <- function(x) {
  if (inherits(x, "regex")) {
    paste0("regex: `", x, "`")
  } else {
    as.character(x)
  }
}

defaults_table <- data.frame(
  default = vapply(default_settings, make_string, character(1L)),
  stringsAsFactors = FALSE
)

# avoid conflict when loading lintr in echo=TRUE cell below
rm(default_settings)

knitr::kable(defaults_table)

Note that the default encoding setting depends on the file to be linted. If an Encoding is found in a .Rproj file or a DESCRIPTION file, that encoding overrides the default of UTF-8.

Customizing active linters

If you only want to customize some linters, you can use the helper function linters_with_defaults(), which will keep all unnamed linters with the default settings. Disable a linter by passing NULL.

For example, to set the line length limit to 120 characters and globally disable the whitespace_linter(), you can put this into your .lintr:

linters: linters_with_defaults(
    line_length_linter = line_length_linter(120L),
    whitespace_linter = NULL
  )

By default, the following linters are enabled. Where applicable, the default settings are also shown.

library(lintr) # needed here for formalArgs

default_linters <- lintr::default_linters
linters_with_args <- lapply(
  setNames(nm = intersect(names(default_linters), lintr::available_linters(tags = "configurable")$linter)),
  formalArgs
)

make_setting_string <- function(linter_name) {
  args <- linters_with_args[[linter_name]]
  if (is.null(args)) {
    return("")
  }

  arglist <- vapply(args, function(arg) {
    env <- environment(default_linters[[linter_name]])
    deparse(env[[arg]])
  }, character(1L))

  paste0(args, " = ", arglist, collapse = ", ")
}

defaults_table <- data.frame(
  row.names = names(default_linters),
  settings = vapply(names(default_linters), make_setting_string, character(1L)),
  stringsAsFactors = FALSE
)

knitr::kable(defaults_table)

Another way to customize linters is by specifying tags in linters_with_tags(). The available tags are listed below:

lintr::available_tags(packages = "lintr")

You can select tags of interest to see which linters are included:

linters <- lintr::linters_with_tags(tags = c("package_development", "readability"))
names(linters)

You can include tag-based linters in the configuration file, and customize them further:

linters: linters_with_tags(
    tags = c("package_development", "readability"),
    yoda_test_linter = NULL
  )

Using all available linters

The default lintr configuration includes only linters relevant to the tidyverse style guide, but there are many other linters available in {lintr}. You can see a list of all available linters using

names(lintr::all_linters())

If you want to use all available linters, you can include this in your .lintr file:

linters: all_linters()

If you want to use all available linters except a few, you can exclude them using NULL:

linters: all_linters(
    commented_code_linter = NULL,
    implicit_integer_linter = NULL
  )

Advanced: programmatic retrieval of linters

For some use cases, it may be useful to specify linters by string instead of by name, i.e. "assignment_linter" instead of writing out assignment_linter().

Beware that in such cases, a simple get() is not enough:

library(lintr)
linter_name <- "assignment_linter"

show_lint <- function(l) {
  lint_df <- as.data.frame(l)
  print(lint_df[, c("line_number", "message", "linter")])
}
hline <- function() cat(strrep("-", getOption("width") - 5L), "\n", sep = "")

withr::with_tempfile("tmp", {
  writeLines("a = 1", tmp)

  # linter column is just 'get'
  show_lint(lint(tmp, linters = get(linter_name)()))
  hline()

  this_linter <- get(linter_name)()
  attr(this_linter, "name") <- linter_name
  # linter column is 'assignment_linter'
  show_lint(lint(tmp, linters = this_linter))
  hline()

  # more concise alternative for this case: use eval(call(.))
  show_lint(lint(tmp, linters = eval(call(linter_name))))
})

Exclusions

Sometimes, linters should not be globally disabled. Instead, one might want to exclude some code from linting altogether or selectively disable some linters on some part of the code.

Note that the preferred way of excluding lints from source code is to use the narrowest possible scope and specify exactly which linters should not throw a lint on a marked line. This prevents accidental suppression of justified lints that happen to be on the same line as a lint that needs to be suppressed.

Excluding lines of code

Within source files, special comments can be used to exclude single lines of code from linting. All lints produced on the marked line are excluded from the results.

By default, this special comment is # nolint:

file.R

X = 42L # -------------- this comment overflows the default 80 chars line length.

> lint("file.R")

lint("X = 42L # -------------- this comment overflows the default 80 chars line length.\n",
  parse_settings = FALSE
)

file2.R

X = 42L # nolint ------ this comment overflows the default 80 chars line length.

> lint("file2.R")

lint("X = 42L # nolint ------ this comment overflows the default 80 chars line length.\n",
  parse_settings = FALSE
)

Observe how all lints were suppressed and no output is shown. Sometimes, only a specific linter needs to be excluded. In this case, the name of the linter can be appended to the # nolint comment preceded by a colon and terminated by a dot.

Excluding only some linters

file3.R

X = 42L # nolint: object_name_linter. this comment overflows the default 80 chars line length.

> lint("file3.R")

lint("X = 42L # nolint: object_name_linter. this comment overflows the default 80 chars line length.\n",
  parse_settings = FALSE
)

Observe how only the object_name_linter was suppressed. This is preferable to blanket # nolint statements because blanket exclusions may accidentally silence a linter that was not intentionally suppressed.

Multiple linters can be specified by listing them with a comma as a separator:

file4.R

X = 42L # nolint: object_name_linter, line_length_linter. this comment overflows the default 80 chars line length.

> lint("file4.R")

lint(
  paste(
    "X = 42L",
    "# nolint: object_name_linter, line_length_linter. this comment overflows the default 80 chars line length.\n"
  ),
  parse_settings = FALSE
)

You can also specify the linter names by a unique prefix instead of their full name:

file5.R

X = 42L # nolint: object_name, line_len. this comment still overflows the default 80 chars line length.

> lint("file5.R")

lint(
  paste(
    "X = 42L",
    "# nolint: object_name, line_len. this comment still overflows the default 80 chars line length.\n"
  ),
  parse_settings = FALSE
)

Excluding multiple lines of codes

If any or all linters should be disabled for a contiguous block of code, the exclude_start and exclude_end patterns can be used. They default to # nolint start and # nolint end respectively.

# nolint start accepts the same syntax as # nolint to disable specific linters in the following lines until a # nolint end is encountered.

# x <- 42L
# print(x)

lint("# x <- 42L\n# print(x)\n", parse_settings = FALSE)

# nolint start: commented_code_linter.
# x <- 42L
# print(x)
# nolint end

lint("# nolint start: commented_code_linter.\n# x <- 42L\n# print(x)\n# nolint end\n",
  parse_settings = FALSE
)

(No lints)

Excluding lines via the config file

Individual lines can also be excluded via the config file by setting the key exclusions to a list with elements corresponding to different files. To exclude all lints for line 1 of file R/bad.R and line_length_linter for lines 4 to 6 of the same file, one can set

exclusions: list(
    "R/bad.R" = list(
      1, # global exclusions are unnamed
      line_length_linter = 4:6
    )
  )

All paths are interpreted relative to the location of the .lintr file.

Excluding files completely

The linter configuration can also be used to exclude a file entirely, or a linter for a file entirely. Use the sentinel line number Inf to mark all lines as excluded within a file. If a file is only given as a character vector, full exclusion is implied.

exclusions: list(
    # excluded from all lints:
    "R/excluded1.R",
    "R/excluded2.R" = Inf,
    "R/excluded3.R" = list(Inf),
    # excluded from line_length_linter:
    "R/no-line-length.R" = list(
      line_length_linter = Inf
    )
  )

Excluding directories completely

Entire directories are also recognized when supplied as strings in the exclusions key. For example, to exclude the renv folder from linting in a R project using renv, set

exclusions: list(
    "renv"
  )

This is particularly useful for projects which include external code in subdirectories.

lintr documentation built on Nov. 7, 2023, 5:07 p.m.