From c277f2c6a5834eb66fc39b05d0ceebc6697ada1e Mon Sep 17 00:00:00 2001 From: Davis Vaughan Date: Fri, 17 Jan 2025 10:33:33 -0500 Subject: [PATCH] Document current stance on `air.toml`s (#158) * Document current stance on `air.toml`s * Mention configuration synchronization * Revert "Mention configuration synchronization" This reverts commit 1d3187f27db5ce7d43317ebf2b31579f176c2eb6. * Add synchronization section * Fix a typo and tweak placement * Add line back --------- Co-authored-by: Lionel Henry --- docs/configuration.qmd | 49 +++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/docs/configuration.qmd b/docs/configuration.qmd index 14c4f8e6..bc4f9712 100644 --- a/docs/configuration.qmd +++ b/docs/configuration.qmd @@ -8,7 +8,6 @@ editor: Air can be configured using a TOML file named `air.toml`. Air is purposefully minimally configurable, with the main configuration points being related to line width and indent style. -Our hope is that most projects never need an `air.toml` file! ## Example configuration @@ -19,17 +18,38 @@ Below is a complete `air.toml` file showing all available options set to their d line-width = 80 indent-width = 2 indent-style = "space" -line-ending = "auto" +line-ending = "auto" ignore-magic-line-break = false ``` +## Configuration recommendations + +For collaborative projects, we recommend creating an `air.toml` and placing it at your project root even if you plan to use the default Air settings. +This has a number of benefits: + +- It stops Air from using user level editor settings. + When an `air.toml` is not present, Air respects some user level editor settings, such as `editor.tabWidth` in VS Code or Positron. + The presence of an `air.toml` (even an empty one) disables this, instead pulling all settings from the configuration file. + This ensures that settings are the same across team members, code editors, and in CI. + +- It stops [configuration discovery] from extending outside your project. + Without an `air.toml` at the project root, Air might discover your local `~/packages/air.toml` as the configuration file to use for the `~/packages/dplyr` project. + By adding `~/packages/dplyr/air.toml`, you prevent configuration discovery from looking "above" `~/packages/dplyr`, again ensuring consistent settings across team members. + +- It serves as a signal to others that your project is using Air. + +If you do plan to just use the defaults, the `air.toml` can be completely empty. +The important thing is that it exists. + +If you're happy with Air's defaults (or your IDE settings, see section on synchronization) and don't plan for your project to ever leave your computer, you likely don't need an `air.toml`. + ## Configuration discovery The ideal place to put an `air.toml` file is at your project root. For example, note the placement of `air.toml` in this minimal dplyr project: ``` bash -~/files/dplyr +~/packages/dplyr ├── air.toml ├── DESCRIPTION ├── NAMESPACE @@ -39,10 +59,23 @@ For example, note the placement of `air.toml` in this minimal dplyr project: └── vignettes ``` -If you run `air format` with a working directory of `~/files/dplyr` or open your IDE in the dplyr project, then Air will find and use that TOML file. +If you run `air format` with a working directory of `~/packages/dplyr` or open your IDE in the dplyr project, then Air will find and use that TOML file. Air also supports walking up the directory tree from the project root. -For example, if you ran `air format` from within `~/files/dplyr/R`, then Air would look "up" one directory and would find and use `~/files/dplyr/air.toml`. +For example, if you ran `air format` from within `~/packages/dplyr/R`, then Air would look "up" one directory and would find and use `~/packages/dplyr/air.toml`. + +## Settings synchronization + +In IDEs that support synchronization (VS Code and Positron currently), Air does its best to ensure that the formatter and the IDE are in agreement. +This is supported by two mechanisms: + +- In projects that don't have an `air.toml` file, IDE settings are sent to Air. + This ensures that Air will use the same indentation style and width that is configured in the IDE. + +- In projects that do have an `air.toml` file, the Air settings are sent to the IDE. + This ensures that the IDE will use the same indentation style and width that Air uses. + +The goal of this synchronization mechanism is for the IDE to work in lockstep with the Air formatter. ## Dotfiles @@ -122,9 +155,9 @@ Similarly, this function signature could also be flattened, but is not, due to t ``` r case_when <- function( - ..., - .default = NULL, - .ptype = NULL, + ..., + .default = NULL, + .ptype = NULL, .size = NULL ) { body