diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/docs/configuration/advanced-key-binding.md | 3 | ||||
| -rw-r--r-- | docs/docs/configuration/config.md | 15 | ||||
| -rw-r--r-- | docs/docs/configuration/key-binding.md | 21 | ||||
| -rw-r--r-- | docs/docs/guide/advanced-usage.md | 49 | ||||
| -rw-r--r-- | docs/docs/guide/basic-usage.md | 2 | ||||
| -rw-r--r-- | docs/mkdocs.yml | 1 |
6 files changed, 74 insertions, 17 deletions
diff --git a/docs/docs/configuration/advanced-key-binding.md b/docs/docs/configuration/advanced-key-binding.md index 1fe9c1e4..7f73b5d6 100644 --- a/docs/docs/configuration/advanced-key-binding.md +++ b/docs/docs/configuration/advanced-key-binding.md @@ -206,6 +206,8 @@ Note: `select-next` and `select-previous` respect the `invert` setting. When `in | `cycle-filter-mode` | Cycle through filter modes (global, host, session, directory) | | `cycle-search-mode` | Cycle through search modes (fuzzy, prefix, fulltext, skim) | | `toggle-tab` | Toggle between the search tab and inspector tab | +| `switch-context` | Switch to the [context](../guide/advanced-usage.md#context-switch) of the currently selected command | +| `clear-context` | Return to the initial [context](../guide/advanced-usage.md#context-switch) | The difference between `accept` and `return-selection`: `accept` runs the command immediately when the TUI closes, while `return-selection` places it on your command line for further editing before you press enter. The `enter_accept` setting controls which of these the default `enter` key uses. @@ -251,6 +253,7 @@ Conditions let a single key do different things depending on the current state. | `list-at-end` | The selection is at the last entry | | `no-results` | The search returned zero results | | `has-results` | The search returned at least one result | +| `has-context` | The context comes from a previously selected command (`switch-context`) | ### Boolean expressions diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md index 49e29a79..31980ed1 100644 --- a/docs/docs/configuration/config.md +++ b/docs/docs/configuration/config.md @@ -139,13 +139,14 @@ 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 | -| directory | Search history just from the current directory (global) | -| workspace | Search history just from the current git repository (>17.0) | +| Mode | Description | +|------------------|--------------------------------------------------------------------------------------| +| global (default) | Search from the full history | +| host | Search history from this host | +| session | Search history from the current session | +| directory | Search history from the current directory | +| workspace | Search history from the current git repository | +| session-preload | Search from the current session and the global history from before the session start | Filter modes can still be toggled via ctrl-r diff --git a/docs/docs/configuration/key-binding.md b/docs/docs/configuration/key-binding.md index f292999f..942a2400 100644 --- a/docs/docs/configuration/key-binding.md +++ b/docs/docs/configuration/key-binding.md @@ -202,31 +202,32 @@ $env.config = ( ## Atuin UI shortcuts | Shortcut | Action | -| ----------------------------------------- | ----------------------------------------------------------------------------- | -| enter | Execute selected item | +|-------------------------------------------|-------------------------------------------------------------------------------| +| enter | Execute selected item | | tab | Select item and edit | | ctrl + r | Cycle through filter modes | | ctrl + s | Cycle through search modes | | alt + 1 to alt + 9 | Select item by the number located near it | | ctrl + c / ctrl + d / ctrl + g / esc | Return original | | ctrl + y | Copy selected item to clipboard | -| ctrl + ← / alt + b | Move the cursor to the previous word | -| ctrl + → / alt + f | Move the cursor to the next word | -| ctrl + b / ← | Move the cursor to the left | -| ctrl + f / → | Move the cursor to the right | +| ctrl + ← / alt + b | Move the cursor to the previous word | +| ctrl + → / alt + f | Move the cursor to the next word | +| ctrl + b / ← | Move the cursor to the left | +| ctrl + f / → | Move the cursor to the right | | ctrl + a / home | Move the cursor to the start of the line | | ctrl + e / end | Move the cursor to the end of the line | | ctrl + backspace / ctrl + alt + backspace | Remove the previous word / remove the word just before the cursor | | ctrl + delete / ctrl + alt + delete | Remove the next word or the word just after the cursor | | ctrl + w | Remove the word before the cursor even if it spans across the word boundaries | | ctrl + u | Clear the current line | -| ctrl + n / ctrl + j / ↑ | Select the next item on the list | -| ctrl + p / ctrl + k / ↓ | Select the previous item on the list | +| ctrl + n / ctrl + j / ↑ | Select the next item on the list | +| ctrl + p / ctrl + k / ↓ | Select the previous item on the list | | ctrl + o | Open the [inspector](#inspector) | | page down | Scroll search results one page down | | page up | Scroll search results one page up | -| ↓ (with no entry selected) | Return original or return query depending on [settings](config.md#exit_mode) | -| ↓ | Select the next item on the list | +| ↓ (with no entry selected) | Return original or return query depending on [settings](config.md#exit_mode) | +| ↓ | Select the next item on the list | +| ctrl + a, c | Switch to the context of the currently selected command / return to default | ### Vim mode diff --git a/docs/docs/guide/advanced-usage.md b/docs/docs/guide/advanced-usage.md new file mode 100644 index 00000000..0d5a1359 --- /dev/null +++ b/docs/docs/guide/advanced-usage.md @@ -0,0 +1,49 @@ +# Advanced Usage + +Atuin offers you several options to help navigate through the results. + +## Filter mode + +The command history can be filtered in different ways, letting you narrow the search scope. + +You can cycle through the different modes by pressing **ctrl-r**. + +The available modes are: + +| Mode | Description | +|------------------|--------------------------------------------------------------------------------------| +| global (default) | Search from the full history | +| host | Search history from this host | +| session | Search history from the current session | +| directory | Search history from the current directory | +| workspace | Search history from the current git repository | +| session-preload | Search from the current session and the global history from before the session start | + +See the [`filter_mode` config reference](../configuration/config.md#filter_mode) for more details. + +## Search mode + +Atuin offers different modes to interpret your search query. + +You can cycle through the different modes by pressing **ctrl-s**. + +The available modes are: + +| Mode | Description | +|-----------------|----------------------------------------------------------------------------------------------------------------| +| fuzzy (default) | Search for commands in a fuzzy way, similar to the [fzf syntax](https://github.com/junegunn/fzf#search-syntax) | +| prefix | Commands that start with your query | +| fulltext | Commands that contain your query as a substring | +| skim | Search for commands using the [skim syntax](https://github.com/lotabout/skim#search-syntax) | + +See the [`search_mode` config reference](../configuration/config.md#search_mode) for more details. + +## Context switch + +Atuin uses the current context (host, session, directory) to filter the history when you use a filter mode other than *global*. + +You can switch this context to the one of the currently selected command by pressing **ctrl-a** then **c**. + +This will set the filter mode to *session* and clear the search query, which will show you all the commands executed in the same shell session. + +Pressing this key combination again will return to the initial context. You can customize this behavior by setting [custom key bindings](../configuration/advanced-key-binding.md) to the `switch-context` and `clear-context` commands. `switch-context` can be called several times to navigate through multiple command contexts, while `clear-context` will always return to the initial context. diff --git a/docs/docs/guide/basic-usage.md b/docs/docs/guide/basic-usage.md index 0b40a0aa..f6df1c94 100644 --- a/docs/docs/guide/basic-usage.md +++ b/docs/docs/guide/basic-usage.md @@ -26,6 +26,8 @@ While searching in the TUI, you can adjust the "filter mode" by repeatedly press 3. The current directory only 4. The current shell session only +See the [advanced usage](advanced-usage.md) page for more options. + ## Common config adjustment For a full set of config values, please see the [config reference page](../configuration/config.md). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1cbbf30d..4ca51c60 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -63,6 +63,7 @@ nav: - Setting up sync: guide/sync.md - Import existing history: guide/import.md - Basic usage: guide/basic-usage.md + - Advanced usage: guide/advanced-usage.md - Deleting history: guide/delete-history.md - Syncing dotfiles: guide/dotfiles.md - Theming: guide/theming.md |