From d79318eeb5fff8d0aaee18dce9dad958f4cc10a3 Mon Sep 17 00:00:00 2001 From: Matheus Martins Date: Mon, 24 Jun 2024 06:16:55 -0300 Subject: [PATCH] chore: update configuration file formatting and standardization (#61) Few updates and improvements to the configuration file focused in page formatting: - Adjust the general formatting of the configuration page to improve readability and consistency. - Set a standard for the "Default" value of each option in the file to ensure uniformity. - Applied `toml` syntax highlighting to code blocks that were previously missing it, making the code examples clearer and easier to read. --------- Co-authored-by: Ellie Huxtable --- .gitignore | 5 +- src/content/docs/configuration/config.mdx | 184 ++++++++++++---------- 2 files changed, 105 insertions(+), 84 deletions(-) diff --git a/.gitignore b/.gitignore index 6240da8..3ba866d 100644 --- a/.gitignore +++ b/.gitignore @@ -12,10 +12,13 @@ yarn-debug.log* yarn-error.log* pnpm-debug.log* - # environment variables .env .env.production # macOS-specific files .DS_Store + +# swap vim files +*.swp +*.swo diff --git a/src/content/docs/configuration/config.mdx b/src/content/docs/configuration/config.mdx index d67ff5e..6f145c4 100644 --- a/src/content/docs/configuration/config.mdx +++ b/src/content/docs/configuration/config.mdx @@ -10,88 +10,91 @@ The full path to the config file would be `~/.config/atuin/config.toml` The config location can be overridden with ATUIN_CONFIG_DIR ### `db_path` +Default: `~/.local/share/atuin/history.db` -The path to the Atuin SQlite database. Defaults to -`~/.local/share/atuin/history.db`. +The path to the Atuin SQLite database. -``` +```toml db_path = "~/.history.db" ``` ### `key_path` +Default: `~/.local/share/atuin/key` -The path to the Atuin encryption key. Defaults to -`~/.local/share/atuin/key`. +The path to the Atuin encryption key. -``` +```toml key_path = "~/.atuin-key" ``` ### `session_path` +Default: `~/.local/share/atuin/session` -The path to the Atuin server session file. Defaults to -`~/.local/share/atuin/session`. This is essentially just an API token +The path to the Atuin server session file. +This is essentially just an API token -``` +```toml session_path = "~/.atuin-session" ``` ### `dialect` +Default: `us` This configures how the [stats](/reference/stats/) command parses dates. It has two possible values -``` +```toml dialect = "uk" ``` or -``` +```toml dialect = "us" ``` -and defaults to "us". - ### `auto_sync` +Default: `true` -Configures whether or not to automatically sync, when logged in. Defaults to -true +Configures whether or not to automatically sync, when logged in. -``` +```toml auto_sync = true/false ``` ### `update_check` +Default: `true` -Configures whether or not to automatically check for updates. Defaults to -true. +Configures whether or not to automatically check for updates. -``` +```toml update_check = true/false ``` ### `sync_address` +Default: `https://api.atuin.sh` -The address of the server to sync with! Defaults to `https://api.atuin.sh`. +The address of the server to sync with! -``` +```toml sync_address = "https://api.atuin.sh" ``` ### `sync_frequency` +Default: `1h` How often to automatically sync with the server. This can be given in a -"human-readable" format. For example, `10s`, `20m`, `1h`, etc. Defaults to `1h`. +"human-readable" format. For example, `10s`, `20m`, `1h`, etc. If set to `0`, Atuin will sync after every command. Some servers may potentially rate limit, which won't cause any issues. -``` +```toml sync_frequency = "1h" ``` ### `search_mode` +Default: `fuzzy` Which search mode to use. Atuin supports "prefix", "fulltext", "fuzzy", and "skim" search modes. @@ -100,10 +103,8 @@ Prefix mode searches for "query\*"; fulltext mode searches for "\*query\*"; "fuzzy" applies the [fuzzy search syntax](#fuzzy-search-syntax); "skim" applies the [skim search syntax](https://github.com/lotabout/skim#search-syntax). -Defaults to "fuzzy". #### `fuzzy` search syntax - The "fuzzy" search syntax is based on the [fzf search syntax](https://github.com/junegunn/fzf#search-syntax). @@ -126,6 +127,7 @@ or `py`. ``` ### `filter_mode` +Default: `global` The default filter to use when searching @@ -138,40 +140,45 @@ The default filter to use when searching Filter modes can still be toggled via ctrl-r -``` +```toml filter_mode = "host" ``` ### `search_mode_shell_up_key_binding` Atuin version: >= 17.0 +Default: `fuzzy` + The default searchmode to use when searching and being invoked from a shell up-key binding. Accepts exactly the same options as `search_mode` above -``` +```toml search_mode_shell_up_key_binding = "fuzzy" ``` -Defaults to the value specified for search_mode. +Defaults to the value specified for `search_mode`. ### `filter_mode_shell_up_key_binding` +Default: `global` The default filter to use when searching and being invoked from a shell up-key binding. Accepts exactly the same options as `filter_mode` above -``` +```toml filter_mode_shell_up_key_binding = "session" ``` -Defaults to the value specified for filter_mode. +Defaults to the value specified for `filter_mode`. ### `workspaces` Atuin version: >= 17.0 +Default: `false` + This flag enables a pseudo filter-mode named "workspace": the filter is automatically -activated when you are in a git repository. Defaults to false. +activated when you are in a git repository. With workspace filtering enabled, Atuin will filter for commands executed in any directory within a git repository tree. @@ -179,6 +186,7 @@ within a git repository tree. Filter modes can still be toggled via ctrl-r. ### `style` +Default: `auto` Which style to use. Possible values: `auto`, `full` and `compact`. @@ -190,26 +198,30 @@ Which style to use. Possible values: `auto`, `full` and `compact`. ![full](https://user-images.githubusercontent.com/1710904/161623547-42afbfa7-a3ef-4820-bacd-fcaf1e324969.png) -Defaults to `auto`. This means that Atuin will automatically switch to `compact` mode when the terminal window is too short for `full` to display properly. +This means that Atuin will automatically switch to `compact` mode when the terminal window is too short for `full` to display properly. ### `invert` Atuin version: >= 17.0 -Invert the UI - put the search bar at the top , Default to `false` +Default: `false` -``` +Invert the UI - put the search bar at the top. + +```toml invert = true/false ``` ### `inline_height` +Default: `0` Set the maximum number of lines Atuin's interface should take up. ![inline_height](../../../assets/inline.png) -If set to `0` (default), Atuin will always take up as many lines as available (full screen). +If set to `0`, Atuin will always take up as many lines as available (full screen). ### `show_preview` +Default: `true` Configure whether or not to show a preview of the selected command. @@ -220,27 +232,28 @@ Useful when the command is longer than the terminal width and is cut off. ### `max_preview_height` Atuin version: >= 17.0 +Default: `4` + Configure the maximum height of the preview to show. Useful when you have long scripts in your history that you want to distinguish by more than the first few lines. -Defaults to `4`. - ### `show_help` Atuin version: >= 17.0 -Configure whether or not to show the help row, which includes the current Atuin version (and whether an update is available), a keymap hint, and the total amount of commands in your history. +Default: `true` -Defaults to `true`. +Configure whether or not to show the help row, which includes the current Atuin version (and whether an update is available), a keymap hint, and the total amount of commands in your history. ### `show_tabs` Atuin version: >= 18.0 -Configure whether or not to show tabs for search and inspect. +Default: `true` -Defaults to `true`. +Configure whether or not to show tabs for search and inspect. ### `exit_mode` +Default: `return-original` What to do when the escape key is pressed when searching @@ -251,11 +264,12 @@ What to do when the escape key is pressed when searching Pressing ctrl+c or ctrl+d will always return the original command-line value. -``` +```toml exit_mode = "return-query" ``` ### `history_format` +Default to `history list` The history format allows you to configure the default `history list` format - which can also be specified with the --format arg. @@ -264,12 +278,11 @@ The specified --format arg will prioritize the config when both are present More on [history list](https://docs.atuin.sh/reference/list/) ### `history_filter` - The history filter allows you to exclude commands from history tracking - maybe you want to keep ALL of your `curl` commands totally out of your shell history, or maybe just some matching a pattern. This supports regular expressions, so you can hide pretty much whatever you want! -``` +```toml ## Note that these regular expressions are unanchored, i.e. if they don't start ## with ^ or end with $, they'll match anywhere in the command. history_filter = [ @@ -279,12 +292,11 @@ history_filter = [ ``` ### `cwd_filter` - The cwd filter allows you to exclude directories from history tracking. This supports regular expressions, so you can hide pretty much whatever you want! -``` +```toml ## Note that these regular expressions are unanchored, i.e. if they don't start ## with ^ or end with $, they'll match anywhere in the command. # cwd_filter = [ @@ -297,20 +309,23 @@ After updating that parameter, you can run [the prune command](/reference/prune/ ### `store_failed` Atuin version: >= 18.3.0 -``` +Default: `true` + +```toml store_failed = true ``` -Defaults to true. Configures whether to store commands that failed (those with non-zero exit status) or not. +Configures whether to store commands that failed (those with non-zero exit status) or not. ### `secrets_filter` Atuin version: >= 17.0 -``` +Defatults: `true` + +```toml secrets_filter = true ``` - -Defaults to true. This matches history against a set of default regex, and will not save it if we get a match. Defaults include +This matches history against a set of default regex, and will not save it if we get a match. Defaults include 1. AWS key id 2. Github pat (old and new) @@ -321,10 +336,11 @@ Defaults to true. This matches history against a set of default regex, and will 7. Cloud environment variable patterns (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AZURE_STORAGE_CLASS_KEY`, `GOOGLE_SERVICE_ACCOUNT_KEY`) ### macOS Ctrl-n key shortcuts +Default: `true` macOS does not have an Alt key, although terminal emulators can often be configured to map the Option key to be used as Alt. *However*, remapping Option this way may prevent typing some characters, such as using Option-3 to type `#` on the British English layout. For such a scenario, set the `ctrl_n_shortcuts` option to `true` in your config file to replace Alt-0 to Alt-9 shortcuts with Ctrl-0 to Ctrl-9 instead: -``` +```toml # Use Ctrl-0 .. Ctrl-9 instead of Alt-0 .. Alt-9 UI shortcuts ctrl_n_shortcuts = true ``` @@ -332,7 +348,7 @@ ctrl_n_shortcuts = true ### `network_timeout` Atuin version: >= 18.0 -Default: 30 +Default: `30` The max amount of time (in seconds) to wait for a network request. If any operations with a sync server take longer than this, the code will fail - @@ -341,7 +357,7 @@ rather than wait indefinitely. ### `network_connect_timeout` Atuin version: >= 18.0 -Default: 5 +Default: `5` The max time (in seconds) we wait for a connection to become established with a remote sync server. Any longer than this and the request will fail. @@ -349,14 +365,14 @@ remote sync server. Any longer than this and the request will fail. ### `local_timeout` Atuin version: >= 18.0 -Default: 5 +Default: `5` Timeout (in seconds) for acquiring a local database connection (sqlite). ### `enter_accept` Atuin version: >= 17.0 -Default: false +Default: `false` Not supported by NuShell presently @@ -371,7 +387,7 @@ change to be the default for everyone in a later release. ### `keymap_mode` Atuin version: >= 18.0 -Default: "emacs" +Default: `emacs` The initial keymap mode of the interactive Atuin search (e.g. started by the keybindings in the shells). There are four supported values: `"emacs"`, @@ -389,7 +405,7 @@ keymap mode `"emacs"`. ### `keymap_cursor` Atuin version: >= 18.0 -Default: (empty dictionary) +Default: `(empty dictionary)` The terminal's cursor style associated with each keymap mode in the Atuin search. This is specified by a dictionary whose keys and values being the @@ -411,7 +427,7 @@ termination of the Atuin search. ### `prefers_reduced_motion` Atuin version: >= 18.0 -Default: false +Default: `false` Enable this, and Atuin will reduce motion in the TUI as much as possible. Users with motion sensitivity can find the live-updating timestamps distracting. @@ -421,17 +437,16 @@ Alternatively, set env var NO_MOTION ## Stats This section of client config is specifically for configuring Atuin stats calculations -```toml +``` [stats] common_subcommands = [...] common_prefix = [...] ``` ### `common_subcommands` +Default: -Default - -``` +```toml common_subcommands = [ "apt", "cargo", @@ -454,15 +469,13 @@ common_subcommands = [ "yarn", ] ``` - Configures commands where we should consider the subcommand as part of the statistics. For example, consider `kubectl get` rather than just `kubectl`. ### `common_prefix` Atuin version: >= 17.1 -Default - -``` +Default: +```toml common_prefix = [ "sudo", ] @@ -477,7 +490,7 @@ Presently, it is the default for fresh installs but not for existing users. This To enable sync v2, add the following to your config -``` +```toml [sync] records = true ``` @@ -485,13 +498,13 @@ records = true ## `dotfiles` Atuin version: >= 18.1 -Default: false +Default: `false` To enable sync of shell aliases between hosts. Requires `sync` enabled. Add the new section to the bottom of your config file, for every machine you use Atuin with -``` +```toml [dotfiles] enabled = true ``` @@ -516,7 +529,7 @@ After setting an alias, you will either need to restart your shell or source the ## keys This section of the client config is specifically for configuring key-related settings. -```toml +``` [keys] scroll_exits = [...] prefix = 'a' @@ -525,14 +538,14 @@ prefix = 'a' ### `scroll_exits` Atuin version: >= 18.1 -Default: true +Default: `true` Configures whether the TUI exits, when scrolled past the last or first entry. ### `prefix` Atuin version: > 18.3 -Default: 'a' +Default: `a` Which key to use as the prefix @@ -540,7 +553,7 @@ Which key to use as the prefix This section of the client config is specifically for configuring preview-related settings. (In the future the other 2 preview settings will be moved here.) -```toml +``` [preview] strategy = [...] ``` @@ -548,6 +561,8 @@ strategy = [...] ### `strategy` Atuin version: >= 18.3 +Default: `auto` + Which preview strategy is used to calculate the preview height. It respects `max_preview_height`. | Value | Preview height is calculated from the length of the | @@ -560,45 +575,48 @@ By using `auto` a preview is shown, iff the command is longer than the width of ## Daemon Atuin version: >= 18.3 -Default: false +Default: `false` Enable the background daemon Add the new section to the bottom of your config file -``` +```toml [daemon] enabled = true ``` ### sync_frequency +Default: `300` How often the daemon should sync, in seconds -``` +```toml sync_frequency = 300 ``` ### socket_path - -Where to bind a unix socket for client -> daemon communication - -``` +Default: +```toml socket_path = "~/.local/share/atuin/atuin.sock" ``` +Where to bind a unix socket for client -> daemon communication ### systemd_socket +Default `false` + Use a socket passed via systemd socket activation protocol instead of the path -``` +```toml systemd_socket = false ``` ### tcp_port +Default: `8889` The port to use for client -> daemon communication. Only used on non-unix systems. -``` +```toml tcp_port = 8889 ```