diff options
| -rw-r--r-- | docs/docs/faq.md | 23 | ||||
| -rw-r--r-- | docs/docs/guide/shell-integration.md | 260 | ||||
| -rw-r--r-- | docs/docs/integrations.md | 8 | ||||
| -rw-r--r-- | docs/mkdocs.yml | 1 |
4 files changed, 292 insertions, 0 deletions
diff --git a/docs/docs/faq.md b/docs/docs/faq.md index c4f51c6f..f5e867e7 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -1,5 +1,28 @@ # FAQ +## Why isn't Atuin recording commands in my IDE's terminal? + +IDEs like PyCharm, VS Code, and others often start non-interactive shells that don't source your shell configuration. This means Atuin's hooks never get installed. + +To fix this, configure your IDE to start an interactive shell (e.g., `/bin/bash -i` instead of `/bin/bash`). + +See [Shell Integration and Interoperability](guide/shell-integration.md) for detailed instructions. + +## How do I exclude certain commands from my history? + +Use the `history_filter` option in `~/.config/atuin/config.toml`: + +```toml +history_filter = [ + "^secret-cmd", + "^ls$", +] +``` + +You can also exclude commands by directory with `cwd_filter`, or prefix individual commands with a space. + +See [Shell Integration and Interoperability](guide/shell-integration.md#excluding-commands-from-history) for more options. + ## How do I remove the default up arrow binding? Open your shell config file, find the line containing `atuin init`. diff --git a/docs/docs/guide/shell-integration.md b/docs/docs/guide/shell-integration.md new file mode 100644 index 00000000..6881bf71 --- /dev/null +++ b/docs/docs/guide/shell-integration.md @@ -0,0 +1,260 @@ +# Shell Integration and Interoperability + +Atuin uses shell hooks to capture your command history. This page explains how the integration works, why Atuin might not record commands in certain environments, and how to control what gets recorded. + +## How Atuin's Shell Integration Works + +When you add `eval "$(atuin init <shell>)"` to your shell configuration, Atuin installs hooks that run at specific points in your shell's command lifecycle: + +1. **Preexec hook**: Runs *before* each command executes. Atuin records the command text, timestamp, and working directory. +2. **Precmd hook**: Runs *after* each command completes. Atuin records the exit code and duration. + +These hooks only activate under specific conditions: + +- The shell must be **interactive** (started with `-i` or inherently interactive) +- Your shell configuration file must be **sourced** (`.bashrc`, `.zshrc`, etc.) +- The `atuin init` command must run during shell startup + +If any of these conditions aren't met, Atuin's hooks won't be installed, and commands won't be recorded. + +### Environment Variables + +When Atuin initializes, it sets several environment variables: + +| Variable | Purpose | +|----------|---------| +| `ATUIN_SESSION` | Unique identifier for this shell session | +| `ATUIN_SHLVL` | Tracks shell nesting level | +| `ATUIN_HISTORY_ID` | Temporary ID for the currently executing command | + +These variables are used internally to track command execution and associate commands with sessions. + +## Embedded Terminals and IDE Integrations + +Many development tools include embedded terminals: + +- **IDEs**: PyCharm, IntelliJ, VS Code, Cursor, Zed +- **AI coding assistants**: Claude Code, GitHub Copilot CLI, Aider +- **Container environments**: Docker, Podman, devcontainers + +These tools often spawn shells differently than your regular terminal, which can prevent Atuin from working. + +### Why Atuin Might Not Work + +Embedded terminals commonly: + +1. **Start non-interactive shells**: Many tools run commands via `bash -c "command"` or similar, which doesn't trigger shell configuration +2. **Skip shell configuration**: Some tools explicitly avoid sourcing `.bashrc`/`.zshrc` for performance or isolation +3. **Use different shell paths**: The embedded terminal might use a different shell than your default + +You can verify whether Atuin is active by running: + +```shell +atuin doctor +``` + +Look for the `shell.preexec` field in the output. If it shows `none`, Atuin's hooks aren't installed in that shell session. + +### Enabling Atuin in Embedded Terminals + +If you want Atuin to record commands from an embedded terminal, you'll need to ensure it starts an interactive shell that sources your configuration. + +#### IDE Terminal Settings + +Most IDEs let you customize the shell command used for their integrated terminal: + +**PyCharm / IntelliJ:** + +1. Go to Settings → Tools → Terminal +2. Change "Shell path" to include the `-i` flag: + - Linux/macOS: `/bin/bash -i` or `/bin/zsh -i` + - Or create a wrapper script (see below) + +**VS Code:** + +Add to your `settings.json` (substitute the shells for whatever you use): + +```json +{ + "terminal.integrated.profiles.linux": { + "bash": { + "path": "/bin/bash", + "args": ["-i"] + } + }, + "terminal.integrated.profiles.osx": { + "zsh": { + "path": "/bin/zsh", + "args": ["-i"] + } + } +} +``` + +#### Wrapper Script Approach + +For tools that don't easily support shell arguments, create a wrapper script: + +```shell +#!/bin/bash +# Save as ~/bin/interactive-bash.sh and chmod +x +exec /bin/bash -i "$@" +``` + +Then configure your IDE to use `~/bin/interactive-bash.sh` as the shell path. + +#### Verifying the Fix + +After configuring, open a new terminal in your IDE and run: + +```shell +atuin doctor | grep preexec +``` + +You should see `built-in`, `bash-preexec`, `blesh`, or similar—not `none`. + +## Excluding Commands from History + +Sometimes you *don't* want certain commands in your history. This is common when: + +- AI coding tools run many automated commands (git status, file listings, etc.) +- You're running sensitive commands you don't want synced +- Build tools or scripts generate repetitive command noise + +### Using history_filter + +The `history_filter` option in `~/.config/atuin/config.toml` lets you exclude commands matching specific patterns: + +```toml +history_filter = [ + "^ls$", # Exclude bare 'ls' commands + "^cd ", # Exclude cd commands + "^cat ", # Exclude cat commands +] +``` + +Patterns are regular expressions. They're unanchored by default, so `secret` matches anywhere in a command. Use `^` and `$` for exact matching. + +### Using cwd_filter + +To exclude all commands run from specific directories: + +```toml +cwd_filter = [ + "^/tmp", # Exclude commands run from /tmp + "/node_modules/", # Exclude commands from any node_modules + "^/home/user/scratch", # Exclude a scratch directory +] +``` + +### Prefix with Space (ignorespace) + +Most shells support "ignorespace"—commands prefixed with a space aren't saved to history. Atuin honors this convention: + +```shell + echo "this won't be saved" # Note the leading space +``` + +!!! warning "Bash with bash-preexec" + When using bash-preexec (not ble.sh), there's a known issue where ignorespace isn't fully honored. The command won't appear in Atuin, but may still appear in your bash history. See [installation](installation.md) for details. + +### Disabling Atuin for Specific Tools + +If a tool spawns interactive shells but you don't want its commands recorded, you have several options: + +#### Option 1: Environment Variable Check + +Modify your shell configuration to skip Atuin initialization based on an environment variable: + +```shell +# In .bashrc or .zshrc +if [[ -z "${MY_TOOL_SESSION}" ]]; then + eval "$(atuin init bash)" +fi +``` + +Then configure your tool to set `MY_TOOL_SESSION=1` when spawning shells. + +#### Option 2: Use history_filter for Tool-Specific Patterns + +If the tool runs predictable commands, filter them: + +```toml +history_filter = [ + "^git status$", + "^git diff", + "^ls -la$", +] +``` + +#### Option 3: Filter by Directory + +If the tool operates in specific directories: + +```toml +cwd_filter = [ + "^/path/to/tool/workspace", +] +``` + +### Cleaning Up Existing History + +After adding filters, you can remove matching entries from your existing history: + +```shell +atuin history prune +``` + +This removes entries that match your current `history_filter` or `cwd_filter` patterns. + +## Shell-Specific Notes + +### Bash + +Atuin supports two preexec backends for Bash: + +- **ble.sh** (recommended): Full-featured line editor with accurate timing and proper ignorespace support +- **bash-preexec**: Simpler but has some limitations with subshells and ignorespace + +The shell integration explicitly checks for interactive mode: + +```bash +if [[ $- != *i* ]]; then + # Not interactive, skip initialization + return +fi +``` + +### Zsh + +Zsh has native hook support via `add-zsh-hook`. The integration is straightforward and works reliably in interactive sessions. + +### Fish + +Fish uses its event system (`fish_preexec` and `fish_postexec` events). It also respects Fish's private mode—commands run with `fish --private` aren't recorded. + +## Troubleshooting + +### Commands aren't being recorded + +1. Run `atuin doctor` and check the output +2. Verify `shell.preexec` is not `none` +3. Ensure your shell is interactive (`echo $-` should contain `i`) +4. Check that `atuin init` is in your shell config and being sourced + +### Commands from a specific tool aren't recorded + +1. Check if the tool starts an interactive shell +2. Try configuring the tool to use `bash -i` or `zsh -i` +3. Use a wrapper script if the tool doesn't support shell arguments + +### Too many commands are being recorded + +1. Add patterns to `history_filter` in your config +2. Use `cwd_filter` for directory-based exclusion +3. Prefix sensitive commands with a space +4. Run `atuin history prune` to clean existing entries + +### Atuin works in terminal but not in IDE + +This is the most common issue. The IDE's embedded terminal likely isn't starting an interactive shell. See [Enabling Atuin in Embedded Terminals](#enabling-atuin-in-embedded-terminals) above. diff --git a/docs/docs/integrations.md b/docs/docs/integrations.md index 8c031601..6a78b52d 100644 --- a/docs/docs/integrations.md +++ b/docs/docs/integrations.md @@ -1,5 +1,7 @@ # Integrations +This page covers integrations with shell plugins and tools. For information about how Atuin's shell hooks work and troubleshooting embedded terminals (IDEs, AI coding assistants, etc.), see [Shell Integration and Interoperability](guide/shell-integration.md). + ## zsh-autosuggestions Atuin automatically adds itself as an [autosuggest strategy](https://github.com/zsh-users/zsh-autosuggestions#suggestion-strategy). @@ -31,3 +33,9 @@ If you would not like Atuin's auto-complete source, please add the following set ble/util/import/eval-after-load core-complete ' ble/array#remove _ble_complete_auto_source atuin-history' ``` + +## Embedded Terminals and IDEs + +Atuin may not work out of the box in embedded terminals found in IDEs (PyCharm, VS Code, etc.) or AI coding assistants (Claude Code, etc.). This is because these tools often start non-interactive shells that don't source your shell configuration. + +For solutions and workarounds, see [Shell Integration and Interoperability](guide/shell-integration.md). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4ca51c60..26bf0bee 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -64,6 +64,7 @@ nav: - Import existing history: guide/import.md - Basic usage: guide/basic-usage.md - Advanced usage: guide/advanced-usage.md + - Shell Integration: guide/shell-integration.md - Deleting history: guide/delete-history.md - Syncing dotfiles: guide/dotfiles.md - Theming: guide/theming.md |