From 6671f72d1be531cd2fc5786752c2b84ef8e760ae Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Wed, 5 Apr 2023 16:32:26 +0800 Subject: [PATCH] Updated client config docs (#839) * Updated client config docs - Example `config.toml` now includes all the newest options - `settings.rs`, `config.toml`, and `config.md` now have uniform option order * Remove trailing space --- atuin-client/config.toml | 37 +++++--- atuin-client/src/settings.rs | 8 +- docs/docs/config/config.md | 162 +++++++++++++++++++---------------- 3 files changed, 121 insertions(+), 86 deletions(-) diff --git a/atuin-client/config.toml b/atuin-client/config.toml index a3c255b..1208586 100644 --- a/atuin-client/config.toml +++ b/atuin-client/config.toml @@ -10,7 +10,7 @@ # session_path = "~/.key" ## date format used, either "us" or "uk" -# dialect = "uk" +# dialect = "us" ## enable or disable automatic sync # auto_sync = true @@ -18,21 +18,38 @@ ## enable or disable automatic update checks # update_check = true -## how often to sync history. note that this is only triggered when a command -## is ran, so sync intervals may well be longer -## set it to 0 to sync after every command -# sync_frequency = "5m" - ## address of the sync server # sync_address = "https://api.atuin.sh" +## how often to sync history. note that this is only triggered when a command +## is ran, so sync intervals may well be longer +## set it to 0 to sync after every command +# sync_frequency = "1h" + ## which search mode to use -## possible values: prefix, fulltext, fuzzy -# search_mode = "prefix" +## possible values: prefix, fulltext, fuzzy, skim +# search_mode = "fuzzy" + +## which filter mode to use +## possible values: global, host, session, directory +# filter_mode = "global" + +## which filter mode to use when atuin is invoked from a shell up-key binding +## the accepted values are identical to those of "filter_mode" +## leave unspecified to use same mode set in "filter_mode" +# filter_mode_shell_up_keybinding = "global" ## which style to use ## possible values: auto, full, compact -#style = "auto" +# style = "auto" + +## the maximum number of lines the interface should take up +## set it to 0 to always go full screen +# inline_height = 0 + +## enable or disable showing a preview of the selected command +## useful when the command is longer than the terminal width and is cut off +# show_preview = false ## what to do when the escape key is pressed when searching ## possible values: return-original, return-query @@ -55,4 +72,4 @@ # history_filter = [ # "^secret-cmd", # "^innocuous-cmd .*--secret=.+" -# ] \ No newline at end of file +# ] diff --git a/atuin-client/src/settings.rs b/atuin-client/src/settings.rs index 756c496..0a723fb 100644 --- a/atuin-client/src/settings.rs +++ b/atuin-client/src/settings.rs @@ -327,22 +327,22 @@ impl Settings { .set_default("dialect", "us")? .set_default("auto_sync", true)? .set_default("update_check", true)? - .set_default("sync_frequency", "1h")? .set_default("sync_address", "https://api.atuin.sh")? + .set_default("sync_frequency", "1h")? .set_default("search_mode", "fuzzy")? .set_default("filter_mode", "global")? - .set_default("shell_up_key_binding", false)? + .set_default("style", "auto")? .set_default("inline_height", 0)? .set_default("show_preview", false)? .set_default("exit_mode", "return-original")? - .set_default("session_token", "")? - .set_default("style", "auto")? .set_default("word_jump_mode", "emacs")? .set_default( "word_chars", "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", )? .set_default("scroll_context_lines", 1)? + .set_default("shell_up_key_binding", false)? + .set_default("session_token", "")? .add_source( Environment::with_prefix("atuin") .prefix_separator("_") diff --git a/docs/docs/config/config.md b/docs/docs/config/config.md index ba3e2bc..c3729ec 100644 --- a/docs/docs/config/config.md +++ b/docs/docs/config/config.md @@ -21,6 +21,33 @@ is what you care about. See [config.toml](../../../atuin-client/config.toml) for an example +### `db_path` + +The path to the Atuin SQlite database. Defaults to +`~/.local/share/atuin/history.db`. + +``` +db_path = "~/.history.db" +``` + +### `key_path` + +The path to the Atuin encryption key. Defaults to +`~/.local/share/atuin/key`. + +``` +key = "~/.atuin-key" +``` + +### `session_path` + +The path to the Atuin server session file. Defaults to +`~/.local/share/atuin/session`. This is essentially just an API token + +``` +key = "~/.atuin-session" +``` + ### `dialect` This configures how the [stats](../commands/stats.md) command parses dates. It has two @@ -76,69 +103,53 @@ rate limit, which won't cause any issues. sync_frequency = "1h" ``` -### `db_path` - -The path to the Atuin SQlite database. Defaults to -`~/.local/share/atuin/history.db`. - -``` -db_path = "~/.history.db" -``` - -### `key_path` - -The path to the Atuin encryption key. Defaults to -`~/.local/share/atuin/key`. - -``` -key = "~/.atuin-key" -``` - -### `session_path` - -The path to the Atuin server session file. Defaults to -`~/.local/share/atuin/session`. This is essentially just an API token - -``` -key = "~/.atuin-session" -``` - ### `search_mode` -Which search mode to use. Atuin supports "prefix", fulltext and "fuzzy" search -modes. The prefix searches for "query\*", fulltext "\*query\*", and fuzzy applies -the search syntax [described below](#fuzzy-search-syntax). +Which search mode to use. Atuin supports "prefix", "fulltext", "fuzzy", and +"skim" search modes. -Defaults to "fuzzy" +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). -### `style` +Defaults to "fuzzy". -Which style to use. Possible values: `auto`, `full` and `compact`. +#### `fuzzy` search syntax -- `compact`: +The "fuzzy" search syntax is based on the +[fzf search syntax](https://github.com/junegunn/fzf#search-syntax). -![image](https://user-images.githubusercontent.com/1710904/161623659-4fec047f-ea4b-471c-9581-861d2eb701a9.png) +| Token | Match type | Description | +|-----------|----------------------------|--------------------------------------| +| `sbtrkt` | fuzzy-match | Items that match `sbtrkt` | +| `'wild` | exact-match (quoted) | Items that include `wild` | +| `^music` | prefix-exact-match | Items that start with `music` | +| `.mp3$` | suffix-exact-match | Items that end with `.mp3` | +| `!fire` | inverse-exact-match | Items that do not include `fire` | +| `!^music` | inverse-prefix-exact-match | Items that do not start with `music` | +| `!.mp3$` | inverse-suffix-exact-match | Items that do not end with `.mp3` | -- `full`: +A single bar character term acts as an OR operator. For example, the following +query matches entries that start with `core` and end with either `go`, `rb`, +or `py`. -![image](https://user-images.githubusercontent.com/1710904/161623547-42afbfa7-a3ef-4820-bacd-fcaf1e324969.png) - -Defaults to `auto`. +``` +^core go$ | rb$ | py$ +``` ### `filter_mode` The default filter to use when searching -| Column1 | Column2 | -|--------------- | --------------- | -| global (default) | Search history from all hosts, all sessions, all directories | -| host | Search history just from this host | -| session | Search history just from the current session | -| directory | Search history just from the current directory| +| Column1 | Column2 | +|------------------|--------------------------------------------------------------| +| global (default) | Search history from all hosts, all sessions, all directories | +| host | Search history just from this host | +| session | Search history just from the current session | +| directory | Search history just from the current directory | Filter modes can still be toggled via ctrl-r - ``` filter_mode = "host" ``` @@ -155,13 +166,43 @@ filter_mode_shell_up_key_binding = "session" Defaults to the value specified for filter_mode. +### `style` + +Which style to use. Possible values: `auto`, `full` and `compact`. + +- `compact`: + +![compact](https://user-images.githubusercontent.com/1710904/161623659-4fec047f-ea4b-471c-9581-861d2eb701a9.png) + +- `full`: + +![full](https://user-images.githubusercontent.com/1710904/161623547-42afbfa7-a3ef-4820-bacd-fcaf1e324969.png) + +Defaults to `auto`. + +### `inline_height` + +Set the maximum number of lines Atuin's interface should take up. + +![inline_height](../../blog/2023/04-01-release-v14/inline.png) + +If set to `0` (default), Atuin will always take up as many lines as available (full screen). + +### `show_preview` + +Configure whether or not to show a preview of the selected command. + +![show_preview](../../blog/2023/04-01-release-v14/preview.png) + +Useful when the command is longer than the terminal width and is cut off. + ### `exit_mode` What to do when the escape key is pressed when searching -| Value | Behaviour | -|------------------------- | --------------- | -| return-original (default) | Set the command-line to the value it had before starting search | +| Value | Behaviour | +|---------------------------|------------------------------------------------------------------| +| return-original (default) | Set the command-line to the value it had before starting search | | return-query | Set the command-line to the search query you have entered so far | Pressing ctrl+c or ctrl+d will always return the original command-line value. @@ -170,29 +211,6 @@ Pressing ctrl+c or ctrl+d will always return the original command-line value. exit_mode = "return-query" ``` -#### `fuzzy` search syntax - -The "fuzzy" search syntax is based on the -[fzf search syntax](https://github.com/junegunn/fzf#search-syntax). - -| Token | Match type | Description | -| --------- | -------------------------- | ------------------------------------ | -| `sbtrkt` | fuzzy-match | Items that match `sbtrkt` | -| `'wild` | exact-match (quoted) | Items that include `wild` | -| `^music` | prefix-exact-match | Items that start with `music` | -| `.mp3$` | suffix-exact-match | Items that end with `.mp3` | -| `!fire` | inverse-exact-match | Items that do not include `fire` | -| `!^music` | inverse-prefix-exact-match | Items that do not start with `music` | -| `!.mp3$` | inverse-suffix-exact-match | Items that do not end with `.mp3` | - -A single bar character term acts as an OR operator. For example, the following -query matches entries that start with `core` and end with either `go`, `rb`, -or `py`. - -``` -^core go$ | rb$ | py$ -``` - ### 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.