Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(shell): make config shell help the setup home (#4344)
Maximilian Roosc98f5f502836
diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.mdindex 61b300c8e..11bcb83b7 100644--- a/docs/src/content/docs/config.md+++ b/docs/src/content/docs/config.md@@ -617,15 +617,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u# Shell Integration-Worktrunk needs shell integration to change directories when switching worktrees. Install with:--```console-$ wt config shell install-```--For manual setup, see `wt config shell init --help`.--Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.### First-run prompts@@ -743,6 +735,213 @@ Global Options:# Subcommands+## wt config shell++Shell integration setup.++A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.++### Setup++```console+$ wt config shell install+```++Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.++- `wt config shell install --help` — installation options+- `wt config shell init --help` — manual setup+- `wt config shell uninstall` — remove the integration++### Check the current shell++```console+$ wt config show+```++The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.++In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.++See [worktrunk.dev/shell-integration](/shell-integration/) for warning messages, installed files, and wrapper behavior.++### Command reference++```text wt-command-reference+wt config shell - Shell integration setup++Usage: wt config shell [OPTIONS] <COMMAND>++Commands:+ init Generate shell integration code+ install Write shell integration to config files+ uninstall Remove shell integration from config files+ show-theme Show output theme samples++Options:+ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell init++Generate shell integration code.++Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.++### Manual setup++For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.++Bash (~/.bashrc):+```console+$ eval "$(wt config shell init bash)"+```++Fish (~/.config/fish/config.fish):+```fish+wt config shell init fish | source+```++Zsh (~/.zshrc):+```zsh+eval "$(wt config shell init zsh)"+```++Nushell 0.113+ <span class="badge-experimental"></span> — save to vendor autoload directory:+```console+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)+```++PowerShell ($PROFILE):+```powershell+Invoke-Expression (& wt config shell init powershell | Out-String)+```++### Command reference++```text wt-command-reference+wt config shell init - Generate shell integration code++Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>++Arguments:+ <bash|fish|nu|zsh|powershell>+ Shell to generate code for++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell install++Write shell integration to config files.++Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](/shell-integration/#files-created) for their locations.++### Examples++Install for all detected shells:+```console+$ wt config shell install+```++Install for specific shell only:+```console+$ wt config shell install zsh+```++Shows proposed changes and waits for confirmation before modifying any files.+Use --yes to skip confirmation.++### Command reference++```text wt-command-reference+wt config shell install - Write shell integration to config files++Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to install (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell uninstall++Remove shell integration from config files.++Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.++### Examples++Uninstall from all shells:+```console+$ wt config shell uninstall+```++Uninstall from specific shell only:+```console+$ wt config shell uninstall zsh+```++Skip confirmation prompt:+```console+$ wt config shell uninstall --yes+```++### Version tolerance++Uninstall removes every worktrunk-managed integration it finds, regardless of:+- Binary name it was installed under (`wt`, `git-wt`, …)+- Minor syntax variations between versions++### Command reference++```text wt-command-reference+wt config shell uninstall - Remove shell integration from config files++Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to uninstall (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ -h, --help+ Print help (see a summary with '-h')+```+## wt config showShow configuration files & locations.diff --git a/docs/src/content/docs/shell-integration.md b/docs/src/content/docs/shell-integration.mdindex cd65caf8f..4122952cf 100644--- a/docs/src/content/docs/shell-integration.md+++ b/docs/src/content/docs/shell-integration.md@@ -4,63 +4,35 @@ description: "How Worktrunk's shell wrapper changes the parent shell's directorysidebar:order: 25----Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.+[`wt config shell`](/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.## Why shell integration exists-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.--Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.+The [shell integration overview](/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.## Installation-```bash-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)-wt config shell install--# Or manual installation - add to the shell config:-# bash (~/.bashrc):-eval "$(wt config shell init bash)"--# zsh (~/.zshrc):-eval "$(wt config shell init zsh)"--# fish (~/.config/fish/config.fish):-wt config shell init fish | source--# nushell 0.113+ (experimental) — save to vendor autoload directory:-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)--# PowerShell ($PROFILE):-Invoke-Expression (& wt config shell init powershell | Out-String)-```+See [`wt config shell install`](/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](/config/#wt-config-shell-init) for manual setup in each supported shell.## Files created-`wt config shell install` writes:+[`wt config shell install`](/config/#wt-config-shell-install) uses these locations:-- **Bash**: adds a line to `~/.bashrc`-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)-- **Nushell 0.113+** <span class="badge-experimental"></span>: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): creates both profile files if they don't exist:+- **Bash**: `~/.bashrc`+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)+- **Nushell 0.113+** <span class="badge-experimental"></span>: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)+- **PowerShell** (Windows): both profile files:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.-**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).-**To remove:** `wt config shell uninstall`.+See [`wt config shell uninstall`](/config/#wt-config-shell-uninstall) for removal.## Checking status-```bash-# Show shell integration status-wt config show-```--The RUNTIME section shows whether shell integration is active for the current session.+The [current-shell checks](/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.## Warning messages@@ -74,9 +46,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell integration not installed"-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.-**Fix**: Run `wt config shell install` or add the line manually.+**Fix**: Run `wt config shell install` or follow the [manual setup](/config/#wt-config-shell-init).### "shell integration installed but not active"@@ -193,11 +165,11 @@ grep -n "wt config shell init" ~/.bashrc# zshgrep -n "wt config shell init" ~/.zshrc-# fish+# fish (manual setup)grep -n "wt config shell init" ~/.config/fish/config.fish```-This should show the `eval` line with its line number.+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).### 4. Check whether directive files are set@@ -255,5 +227,5 @@ If you see path issues, make sure you're on a recent Git for Windows version.## See also-- [`wt config`](/config/#shell-integration) — shell integration commands+- [`wt config shell`](/config/#wt-config-shell) — setup and current-shell diagnostics- [FAQ: What files does Worktrunk create?](/faq/#what-files-does-worktrunk-create)diff --git a/docs/tests/built-site.test.mjs b/docs/tests/built-site.test.mjsindex 572bbb8af..b843f10ff 100644--- a/docs/tests/built-site.test.mjs+++ b/docs/tests/built-site.test.mjs@@ -225,7 +225,7 @@ test('build preserves the public route contract', async () => {assert.ok(configToc, 'config page is missing its desktop table of contents');assert.equal([...configToc.matchAll(/<a href="#[^"]+"/g)].length,- 32,+ 36,'config table of contents should expose overview and structural section headings only',);for (const [id, title] of [@@ -234,6 +234,10 @@ test('build preserves the public route contract', async () => {['shell-integration', 'Shell Integration'],['other', 'Other'],['subcommands', 'Subcommands'],+ ['wt-config-shell', 'wt config shell'],+ ['wt-config-shell-init', 'wt config shell init'],+ ['wt-config-shell-install', 'wt config shell install'],+ ['wt-config-shell-uninstall', 'wt config shell uninstall'],]) {assert.match(configToc,diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.mdindex 9ba21ecb6..a7aff2f5c 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -609,15 +609,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u# Shell Integration-Worktrunk needs shell integration to change directories when switching worktrees. Install with:--```console-$ wt config shell install-```--For manual setup, see `wt config shell init --help`.--Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.### First-run prompts@@ -735,6 +727,213 @@ Global Options:# Subcommands+## wt config shell++Shell integration setup.++A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.++### Setup++```console+$ wt config shell install+```++Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.++- `wt config shell install --help` — installation options+- `wt config shell init --help` — manual setup+- `wt config shell uninstall` — remove the integration++### Check the current shell++```console+$ wt config show+```++The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.++In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.++See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/) for warning messages, installed files, and wrapper behavior.++### Command reference++```+wt config shell - Shell integration setup++Usage: wt config shell [OPTIONS] <COMMAND>++Commands:+ init Generate shell integration code+ install Write shell integration to config files+ uninstall Remove shell integration from config files+ show-theme Show output theme samples++Options:+ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell init++Generate shell integration code.++Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.++### Manual setup++For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.++Bash (~/.bashrc):+```console+$ eval "$(wt config shell init bash)"+```++Fish (~/.config/fish/config.fish):+```fish+wt config shell init fish | source+```++Zsh (~/.zshrc):+```zsh+eval "$(wt config shell init zsh)"+```++Nushell 0.113+ [experimental] — save to vendor autoload directory:+```console+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)+```++PowerShell ($PROFILE):+```powershell+Invoke-Expression (& wt config shell init powershell | Out-String)+```++### Command reference++```+wt config shell init - Generate shell integration code++Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>++Arguments:+ <bash|fish|nu|zsh|powershell>+ Shell to generate code for++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell install++Write shell integration to config files.++Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/#files-created) for their locations.++### Examples++Install for all detected shells:+```console+$ wt config shell install+```++Install for specific shell only:+```console+$ wt config shell install zsh+```++Shows proposed changes and waits for confirmation before modifying any files.+Use --yes to skip confirmation.++### Command reference++```+wt config shell install - Write shell integration to config files++Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to install (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell uninstall++Remove shell integration from config files.++Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.++### Examples++Uninstall from all shells:+```console+$ wt config shell uninstall+```++Uninstall from specific shell only:+```console+$ wt config shell uninstall zsh+```++Skip confirmation prompt:+```console+$ wt config shell uninstall --yes+```++### Version tolerance++Uninstall removes every worktrunk-managed integration it finds, regardless of:+- Binary name it was installed under (`wt`, `git-wt`, …)+- Minor syntax variations between versions++### Command reference++```+wt config shell uninstall - Remove shell integration from config files++Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to uninstall (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ -h, --help+ Print help (see a summary with '-h')+```+## wt config showShow configuration files & locations.diff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.mdindex f259d49e8..5b0d33b33 100644--- a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md+++ b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md@@ -1,62 +1,34 @@# Shell integration-Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.+[`wt config shell`](https://worktrunk.dev/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.## Why shell integration exists-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.--Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.+The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.## Installation-```bash-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)-wt config shell install--# Or manual installation - add to the shell config:-# bash (~/.bashrc):-eval "$(wt config shell init bash)"--# zsh (~/.zshrc):-eval "$(wt config shell init zsh)"--# fish (~/.config/fish/config.fish):-wt config shell init fish | source--# nushell 0.113+ (experimental) — save to vendor autoload directory:-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)--# PowerShell ($PROFILE):-Invoke-Expression (& wt config shell init powershell | Out-String)-```+See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](https://worktrunk.dev/config/#wt-config-shell-init) for manual setup in each supported shell.## Files created-`wt config shell install` writes:+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:-- **Bash**: adds a line to `~/.bashrc`-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)-- **Nushell 0.113+** [experimental]: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): creates both profile files if they don't exist:+- **Bash**: `~/.bashrc`+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)+- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)+- **PowerShell** (Windows): both profile files:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.-**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).-**To remove:** `wt config shell uninstall`.+See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-uninstall) for removal.## Checking status-```bash-# Show shell integration status-wt config show-```--The RUNTIME section shows whether shell integration is active for the current session.+The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.## Warning messages@@ -70,9 +42,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell integration not installed"-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.-**Fix**: Run `wt config shell install` or add the line manually.+**Fix**: Run `wt config shell install` or follow the [manual setup](https://worktrunk.dev/config/#wt-config-shell-init).### "shell integration installed but not active"@@ -189,11 +161,11 @@ grep -n "wt config shell init" ~/.bashrc# zshgrep -n "wt config shell init" ~/.zshrc-# fish+# fish (manual setup)grep -n "wt config shell init" ~/.config/fish/config.fish```-This should show the `eval` line with its line number.+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).### 4. Check whether directive files are setdiff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 9ba21ecb6..a7aff2f5c 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -609,15 +609,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u# Shell Integration-Worktrunk needs shell integration to change directories when switching worktrees. Install with:--```console-$ wt config shell install-```--For manual setup, see `wt config shell init --help`.--Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.### First-run prompts@@ -735,6 +727,213 @@ Global Options:# Subcommands+## wt config shell++Shell integration setup.++A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.++### Setup++```console+$ wt config shell install+```++Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.++- `wt config shell install --help` — installation options+- `wt config shell init --help` — manual setup+- `wt config shell uninstall` — remove the integration++### Check the current shell++```console+$ wt config show+```++The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.++In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.++See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/) for warning messages, installed files, and wrapper behavior.++### Command reference++```+wt config shell - Shell integration setup++Usage: wt config shell [OPTIONS] <COMMAND>++Commands:+ init Generate shell integration code+ install Write shell integration to config files+ uninstall Remove shell integration from config files+ show-theme Show output theme samples++Options:+ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell init++Generate shell integration code.++Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.++### Manual setup++For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.++Bash (~/.bashrc):+```console+$ eval "$(wt config shell init bash)"+```++Fish (~/.config/fish/config.fish):+```fish+wt config shell init fish | source+```++Zsh (~/.zshrc):+```zsh+eval "$(wt config shell init zsh)"+```++Nushell 0.113+ [experimental] — save to vendor autoload directory:+```console+$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)+```++PowerShell ($PROFILE):+```powershell+Invoke-Expression (& wt config shell init powershell | Out-String)+```++### Command reference++```+wt config shell init - Generate shell integration code++Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>++Arguments:+ <bash|fish|nu|zsh|powershell>+ Shell to generate code for++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell install++Write shell integration to config files.++Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/#files-created) for their locations.++### Examples++Install for all detected shells:+```console+$ wt config shell install+```++Install for specific shell only:+```console+$ wt config shell install zsh+```++Shows proposed changes and waits for confirmation before modifying any files.+Use --yes to skip confirmation.++### Command reference++```+wt config shell install - Write shell integration to config files++Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to install (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ --cmd <CMD>+ Command name for shell integration (defaults to binary name)++ Use this to create shell integration for an alternate command name. For example,+ --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt+ conflicts with Windows Terminal.++ -h, --help+ Print help (see a summary with '-h')+```++## wt config shell uninstall++Remove shell integration from config files.++Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.++### Examples++Uninstall from all shells:+```console+$ wt config shell uninstall+```++Uninstall from specific shell only:+```console+$ wt config shell uninstall zsh+```++Skip confirmation prompt:+```console+$ wt config shell uninstall --yes+```++### Version tolerance++Uninstall removes every worktrunk-managed integration it finds, regardless of:+- Binary name it was installed under (`wt`, `git-wt`, …)+- Minor syntax variations between versions++### Command reference++```+wt config shell uninstall - Remove shell integration from config files++Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]++Arguments:+ [bash|fish|nu|zsh|powershell]+ Shell to uninstall (default: all)++ [possible values: bash, fish, nu, zsh, powershell]++Options:+ --dry-run+ Show what would be changed++ -h, --help+ Print help (see a summary with '-h')+```+## wt config showShow configuration files & locations.diff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.mdindex f259d49e8..5b0d33b33 100644--- a/skills/worktrunk/reference/shell-integration.md+++ b/skills/worktrunk/reference/shell-integration.md@@ -1,62 +1,34 @@# Shell integration-Shell integration is what lets `wt switch` change your shell's directory. This page covers how it works, what it installs, and how to fix it when it doesn't.+[`wt config shell`](https://worktrunk.dev/config/#wt-config-shell) covers setup, activation, and current-shell diagnostics. This guide covers installed files, warning messages, and wrapper behavior.## Why shell integration exists-A subprocess cannot change its parent shell's directory. When `wt switch feature` runs, the `wt` binary is a child process and cannot `cd` the terminal.--Worktrunk solves this with a file directive: the shell wrapper creates one temp file, `wt` writes the target directory to it, and the wrapper changes directory after `wt` exits. `--execute` runs directly inside `wt`. See [How the shell wrapper works](#how-the-shell-wrapper-works) for the steps and a simplified implementation.+The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.## Installation-```bash-# Auto-install for all shells (bash, zsh, fish, nushell (experimental), PowerShell)-wt config shell install--# Or manual installation - add to the shell config:-# bash (~/.bashrc):-eval "$(wt config shell init bash)"--# zsh (~/.zshrc):-eval "$(wt config shell init zsh)"--# fish (~/.config/fish/config.fish):-wt config shell init fish | source--# nushell 0.113+ (experimental) — save to vendor autoload directory:-wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)--# PowerShell ($PROFILE):-Invoke-Expression (& wt config shell init powershell | Out-String)-```+See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) for automatic installation and [`wt config shell init`](https://worktrunk.dev/config/#wt-config-shell-init) for manual setup in each supported shell.## Files created-`wt config shell install` writes:+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:-- **Bash**: adds a line to `~/.bashrc`-- **Zsh**: adds a line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)-- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)-- **Nushell 0.113+** [experimental]: creates `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): creates both profile files if they don't exist:+- **Bash**: `~/.bashrc`+- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)+- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)+- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)+- **PowerShell** (Windows): both profile files:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)-Fish and Nushell wrappers live at a path named after the command, so install writes that file whole, replacing an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu`. Bash, zsh, and PowerShell rc files hold the rest of a shell's setup, so install only appends a line to those.-**PowerShell detection on Windows:** When running from cmd.exe or PowerShell, both PowerShell profile files are created automatically. When running from Git Bash or MSYS2, PowerShell is skipped (use `wt config shell install powershell` to create the profiles explicitly).-**To remove:** `wt config shell uninstall`.+See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-uninstall) for removal.## Checking status-```bash-# Show shell integration status-wt config show-```--The RUNTIME section shows whether shell integration is active for the current session.+The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.## Warning messages@@ -70,9 +42,9 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell integration not installed"-**Meaning**: The current shell's config file doesn't have the `eval "$(wt config shell init ...)"` line. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.+**Meaning**: The current shell has no installed Worktrunk initialization line or wrapper file. The current shell is detected from the process tree (falling back to `$SHELL`), so this refers to the shell `wt` was actually invoked from, not necessarily the login shell.-**Fix**: Run `wt config shell install` or add the line manually.+**Fix**: Run `wt config shell install` or follow the [manual setup](https://worktrunk.dev/config/#wt-config-shell-init).### "shell integration installed but not active"@@ -189,11 +161,11 @@ grep -n "wt config shell init" ~/.bashrc# zshgrep -n "wt config shell init" ~/.zshrc-# fish+# fish (manual setup)grep -n "wt config shell init" ~/.config/fish/config.fish```-This should show the `eval` line with its line number.+These commands show the initialization line and its line number. `wt config shell install` writes fish and Nushell wrapper files instead; check those at the locations listed under [Files created](#files-created).### 4. Check whether directive files are setdiff --git a/src/cli/config.rs b/src/cli/config.rsindex 05c7f8c4b..09634b451 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -33,7 +33,7 @@ pub enum ConfigShellCommand {## Manual setup-Add one line to the shell config:+For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.Bash (~/.bashrc):```console@@ -53,6 +53,11 @@ eval "$(wt config shell init zsh)"Nushell 0.113+ [experimental] — save to vendor autoload directory:```console$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)+```++PowerShell ($PROFILE):+```powershell+Invoke-Expression (& wt config shell init powershell | Out-String)```"#)]Init {@@ -71,7 +76,7 @@ $ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join/// Write shell integration to config files#[command(- after_long_help = r#"Detects existing shell config files and adds the integration line.+ after_long_help = r#"Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](/shell-integration/#files-created) for their locations.## Examples@@ -108,7 +113,7 @@ Use --yes to skip confirmation."#/// Remove shell integration from config files#[command(- after_long_help = r#"Removes shell integration lines from config files.+ after_long_help = r#"Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.## Examples@@ -626,6 +631,36 @@ $ wt config alias dry-run deploy -- --env=staging#[derive(Subcommand)]pub enum ConfigCommand {/// Shell integration setup+ #[command(+ after_long_help = r#"A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.++## Setup++```console+$ wt config shell install+```++Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.++- `wt config shell install --help` — installation options+- `wt config shell init --help` — manual setup+- `wt config shell uninstall` — remove the integration++## Check the current shell++```console+$ wt config show+```++The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.++In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.++See [worktrunk.dev/shell-integration](/shell-integration/) for warning messages, installed files, and wrapper behavior.+<!-- subdoc: init -->+<!-- subdoc: install -->+<!-- subdoc: uninstall -->"#+ )]Shell {#[command(subcommand)]action: ConfigShellCommand,diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex e0907554e..303a6f6ad 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -2584,15 +2584,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the [u# Shell Integration-Worktrunk needs shell integration to change directories when switching worktrees. Install with:--```console-$ wt config shell install-```--For manual setup, see `wt config shell init --help`.--Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.+See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.### First-run prompts@@ -2665,6 +2657,7 @@ $ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratc```Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.+<!-- subdoc: shell --><!-- subdoc: show --><!-- subdoc: update --><!-- subdoc: approvals -->diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex cd6c5ef7d..d0c672e66 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -598,13 +598,7 @@ Aliases defined here are shared with teammates. For personal aliases, use the us[32mSHELL INTEGRATION[0m-Worktrunk needs shell integration to change directories when switching worktrees. Install with:--[107m [0m [2m[0m[2m[34mwt[0m[2m config shell install[0m--For manual setup, see [2mwt config shell init --help[0m.--Without shell integration, [2mwt switch[0m prints the target directory but cannot [2mcd[0m into it.+See [2mwt config shell[0m for setup, activation, and current-shell diagnostics.[32mFirst-run prompts[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell.snapindex f1871a972..d65d75610 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap@@ -54,13 +54,45 @@ Usage: [1m[36mwt config shell[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[36mshow-theme[0m Show output theme samples[1m[32mOptions:[0m- [1m[36m-h[0m, [1m[36m--help[0m Print help+ [1m[36m-h[0m, [1m[36m--help[0m+ Print help (see a summary with '-h')[1m[32mGlobal Options:[0m- [1m[36m-C[0m[36m [0m[36m<path>[0m Working directory for this command- [1m[36m--config[0m[36m [0m[36m<path>[0m User config file path- [1m[36m--config-set[0m[36m [0m[36m<toml>[0m Override config with inline TOML, e.g. --config-set list.full=true (repeatable)- [1m[36m-v[0m, [1m[36m--verbose[0m[36m...[0m Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach- [1m[36m-y[0m, [1m[36m--yes[0m Skip approval prompts+ [1m[36m-C[0m[36m [0m[36m<path>[0m+ Working directory for this command++ [1m[36m--config[0m[36m [0m[36m<path>[0m+ User config file path++ [1m[36m--config-set[0m[36m [0m[36m<toml>[0m+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)++ [1m[36m-v[0m, [1m[36m--verbose[0m[36m...[0m+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach++ [1m[36m-y[0m, [1m[36m--yes[0m+ Skip approval prompts++A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.++[1m[32mSetup[0m++[107m [0m [2m[0m[2m[34mwt[0m[2m config shell install[0m++Start a new shell after installation to load the wrapper. Invoke [2mwt[0m by name. Running a binary path or [2mgit wt[0m bypasses the wrapper, so the shell's directory stays unchanged.++- [2mwt config shell install --help[0m — installation options+- [2mwt config shell init --help[0m — manual setup+- [2mwt config shell uninstall[0m — remove the integration++[1m[32mCheck the current shell[0m++[107m [0m [2m[0m[2m[34mwt[0m[2m config show[0m++The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.++In bash, zsh, or fish, [2mtype wt[0m checks that [2mwt[0m resolves to a function. In PowerShell, [2mGet-Command wt -All[0m lists the Function and Application definitions.++See worktrunk.dev/shell-integration for warning messages, installed files, and wrapper behavior.----- stderr -----