From 8f8d4051be962fd667ab001178f599038636116f Mon Sep 17 00:00:00 2001 From: Ellie Huxtable Date: Tue, 7 Jan 2025 01:17:16 +0000 Subject: [PATCH] note xdg_runtime_dir usage --- src/content/docs/configuration/config.mdx | 126 ++++++++++++++++------ src/content/docs/sync-v2.mdx | 26 +++++ 2 files changed, 117 insertions(+), 35 deletions(-) create mode 100644 src/content/docs/sync-v2.mdx diff --git a/src/content/docs/configuration/config.mdx b/src/content/docs/configuration/config.mdx index 0bdb41a..5408f73 100644 --- a/src/content/docs/configuration/config.mdx +++ b/src/content/docs/configuration/config.mdx @@ -10,15 +10,17 @@ 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. +Default: `~/.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. @@ -28,9 +30,10 @@ key_path = "~/.atuin-key" ``` ### `session_path` + Default: `~/.local/share/atuin/session` -The path to the Atuin server session file. +The path to the Atuin server session file. This is essentially just an API token ```toml @@ -38,7 +41,8 @@ session_path = "~/.atuin-session" ``` ### `dialect` -Default: `us` + +Default: `us` This configures how the [stats](/reference/stats/) command parses dates. It has two possible values @@ -54,37 +58,41 @@ dialect = "us" ``` ### `auto_sync` -Default: `true` -Configures whether or not to automatically sync, when logged in. +Default: `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. +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! +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. +"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. @@ -94,6 +102,7 @@ sync_frequency = "1h" ``` ### `search_mode` + Default: `fuzzy` Which search mode to use. Atuin supports "prefix", "fulltext", "fuzzy", and @@ -103,13 +112,13 @@ 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). - #### `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` | @@ -127,12 +136,13 @@ or `py`. ``` ### `filter_mode` + Default: `global` The default filter to use when searching | Mode | Description | -|------------------|--------------------------------------------------------------| +| ---------------- | ------------------------------------------------------------ | | 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 | @@ -145,6 +155,7 @@ filter_mode = "host" ``` ### `search_mode_shell_up_key_binding` + Atuin version: >= 17.0 Default: `fuzzy` @@ -160,6 +171,7 @@ search_mode_shell_up_key_binding = "fuzzy" 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. @@ -173,12 +185,13 @@ filter_mode_shell_up_key_binding = "session" 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. +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. @@ -186,6 +199,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`. @@ -201,17 +215,19 @@ Which style to use. Possible values: `auto`, `full` and `compact`. 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 Default: `false` -Invert the UI - put the search bar at the top. +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. @@ -221,6 +237,7 @@ Set the maximum number of lines Atuin's interface should take up. 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. @@ -230,6 +247,7 @@ Configure whether or not to show a preview of the selected command. Useful when the command is longer than the terminal width and is cut off. ### `max_preview_height` + Atuin version: >= 17.0 Default: `4` @@ -239,6 +257,7 @@ 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. ### `show_help` + Atuin version: >= 17.0 Default: `true` @@ -246,6 +265,7 @@ Default: `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 Default: `true` @@ -253,12 +273,13 @@ Default: `true` Configure whether or not to show tabs for search and inspect. ### `exit_mode` -Default: `return-original` + +Default: `return-original` 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 | | return-query | Set the command-line to the search query you have entered so far | @@ -269,6 +290,7 @@ 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. @@ -278,6 +300,7 @@ 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! @@ -292,6 +315,7 @@ 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! @@ -307,6 +331,7 @@ This supports regular expressions, so you can hide pretty much whatever you want After updating that parameter, you can run [the prune command](/reference/prune/) to remove old history entries that match the new filters. ### `store_failed` + Atuin version: >= 18.3.0 Default: `true` @@ -318,6 +343,7 @@ store_failed = true Configures whether to store commands that failed (those with non-zero exit status) or not. ### `secrets_filter` + Atuin version: >= 17.0 Defatults: `true` @@ -325,6 +351,7 @@ Defatults: `true` ```toml secrets_filter = true ``` + 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 @@ -339,9 +366,10 @@ This matches history against a set of default regex, and will not save it if we 10. Pulumi pat ### 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: +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 @@ -349,6 +377,7 @@ ctrl_n_shortcuts = true ``` ### `network_timeout` + Atuin version: >= 18.0 Default: `30` @@ -358,6 +387,7 @@ operations with a sync server take longer than this, the code will fail - rather than wait indefinitely. ### `network_connect_timeout` + Atuin version: >= 18.0 Default: `5` @@ -366,6 +396,7 @@ 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. ### `local_timeout` + Atuin version: >= 18.0 Default: `5` @@ -373,6 +404,7 @@ Default: `5` Timeout (in seconds) for acquiring a local database connection (sqlite). ### `enter_accept` + Atuin version: >= 17.0 Default: `false` @@ -388,33 +420,36 @@ have set `enter_accept = true` in the default config file. This is likely to change to be the default for everyone in a later release. ### `keymap_mode` + Atuin version: >= 18.0 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"`, -`"vim-normal"`, `"vim-insert"`, and `"auto"`. The keymap mode `"emacs"` is the -most basic one. In the keymap mode `"vim-normal"`, you may use k +keybindings in the shells). There are four supported values: `"emacs"`, +`"vim-normal"`, `"vim-insert"`, and `"auto"`. The keymap mode `"emacs"` is the +most basic one. In the keymap mode `"vim-normal"`, you may use k and j to navigate the history list as in Vim, whilst pressing -i changes the keymap mode to `"vim-insert"`. In the keymap mode -`"vim-insert"`, you can search for a string as in the keymap mode `"emacs"`, -while pressing Esc switches the keymap mode to `"vim-normal"`. When -set to `"auto"`, the initial keymap mode is automatically determined based on -the shell's keymap that triggered the Atuin search. `"auto"` is not supported -by NuShell at present, where it will always trigger the Atuin search with the -keymap mode `"emacs"`. + +i changes the keymap mode to `"vim-insert"`. In the keymap mode `"vim-insert"`, +you can search for a string as in the keymap mode `"emacs"`, while pressing + Esc + switches the keymap mode to `"vim-normal"`. When set to `"auto"`, the initial +keymap mode is automatically determined based on the shell's keymap that triggered +the Atuin search. `"auto"` is not supported by NuShell at present, where it will +always trigger the Atuin search with the keymap mode `"emacs"`. ### `keymap_cursor` + Atuin version: >= 18.0 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 -keymap names and the cursor styles, respectively. A key specifies one of the -keymaps from `emacs`, `vim_insert`, and `vim_normal`. A value is one of the -cursor styles, `default` or `{blink,steady}-{block,underline,bar}`. The +search. This is specified by a dictionary whose keys and values being the +keymap names and the cursor styles, respectively. A key specifies one of the +keymaps from `emacs`, `vim_insert`, and `vim_normal`. A value is one of the +cursor styles, `default` or `{blink,steady}-{block,underline,bar}`. The following is an example. ```toml @@ -423,11 +458,12 @@ keymap_cursor = { emacs = "blink-block", vim_insert = "blink-block", vim_normal If the cursor style is specified, the terminal's cursor style is changed to the specified one when the Atuin search starts with or switches to the -corresponding keymap mode. Also, the terminal's cursor style is reset to the +corresponding keymap mode. Also, the terminal's cursor style is reset to the one associated with the keymap mode corresponding to the shell's keymap on the termination of the Atuin search. ### `prefers_reduced_motion` + Atuin version: >= 18.0 Default: `false` @@ -438,6 +474,7 @@ with motion sensitivity can find the live-updating timestamps distracting. Alternatively, set env var NO_MOTION ## Stats + This section of client config is specifically for configuring Atuin stats calculations ``` @@ -447,7 +484,8 @@ common_prefix = [...] ``` ### `common_subcommands` -Default: + +Default: ```toml common_subcommands = [ @@ -472,12 +510,15 @@ 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: + ```toml common_prefix = [ "sudo", @@ -487,6 +528,7 @@ common_prefix = [ Configures commands that should be totally stripped from stats calculations. For example, 'sudo' should be ignored. ## sync + We have developed a new version of sync, that is both faster and more efficient than the original version. Presently, it is the default for fresh installs but not for existing users. This will change in a later release. @@ -499,6 +541,7 @@ records = true ``` ## `dotfiles` + Atuin version: >= 18.1 Default: `false` @@ -530,6 +573,7 @@ atuin dotfiles alias delete k After setting an alias, you will either need to restart your shell or source the init file for the change to take affect ## keys + This section of the client config is specifically for configuring key-related settings. ``` @@ -539,6 +583,7 @@ prefix = 'a' ``` ### `scroll_exits` + Atuin version: >= 18.1 Default: `true` @@ -546,6 +591,7 @@ Default: `true` Configures whether the TUI exits, when scrolled past the last or first entry. ### `prefix` + Atuin version: > 18.3 Default: `a` @@ -553,6 +599,7 @@ Default: `a` Which key to use as the prefix ## preview + 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.) @@ -562,6 +609,7 @@ strategy = [...] ``` ### `strategy` + Atuin version: >= 18.3 Default: `auto` @@ -569,7 +617,7 @@ 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 | -|----------------|-----------------------------------------------------| +| -------------- | --------------------------------------------------- | | auto (default) | selected command | | static | longest command in the current result set | | fixed | use `max_preview_height` as fixed value | @@ -577,6 +625,7 @@ Which preview strategy is used to calculate the preview height. It respects `max By using `auto` a preview is shown, iff the command is longer than the width of the terminal. ## Daemon + Atuin version: >= 18.3 Default: `false` @@ -591,6 +640,7 @@ enabled = true ``` ### sync_frequency + Default: `300` How often the daemon should sync, in seconds @@ -600,12 +650,17 @@ sync_frequency = 300 ``` ### socket_path -Default: + +Default: + ```toml socket_path = "~/.local/share/atuin/atuin.sock" ``` + Where to bind a unix socket for client -> daemon communication +If XDG_RUNTIME_DIR is available, then we use this directory instead. + ### systemd_socket Default `false` @@ -617,6 +672,7 @@ systemd_socket = false ``` ### tcp_port + Default: `8889` The port to use for client -> daemon communication. Only used on non-unix systems. diff --git a/src/content/docs/sync-v2.mdx b/src/content/docs/sync-v2.mdx new file mode 100644 index 0000000..0f82027 --- /dev/null +++ b/src/content/docs/sync-v2.mdx @@ -0,0 +1,26 @@ +--- +title: Sync v2 +--- + +Just installed Atuin? Don't worry about this page, everything should be setup +for you. + +If you've been using Atuin for a while, you might not be using the best sync. A +long time ago, we shipped sync v1. It was "good enough", but never intended for +the wide use it ended up getting. + +After evaluating issues and feedback from users, we developed sync v2. It +includes a whole bunch of changes that I'll save writing about for a future +blog post or deep dive, but suffice to say it's + +1. Faster +2. More reliable +3. Uses less bandwidth +4. Supports many more features +5. Recovers from issues more effectively + +There's really no reason to not use it. + +You can opt in with the following configuration + +