Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Reorder FAQ by frequency/importance (#679)

Maximilian Roos2309c07ae1c9
diff --git a/.claude-plugin/skills/worktrunk/reference/faq.md b/.claude-plugin/skills/worktrunk/reference/faq.md
index 80aca53fe..e366ae5f0 100644
--- a/.claude-plugin/skills/worktrunk/reference/faq.md
+++ b/.claude-plugin/skills/worktrunk/reference/faq.md
@@ -1,32 +1,5 @@
# FAQ
-## What commands does Worktrunk execute?
-
-Worktrunk executes commands in four contexts:
-
-1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
-2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
-4. **--execute flag** — Explicitly provided commands
-
-User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
-
-### Example approval prompt
-
-```
-▲ repo needs approval to execute 3 commands:
-
-○ post-create install:
- echo 'Installing dependencies...'
-○ post-create build:
- echo 'Building project...'
-○ post-create test:
- echo 'Running tests...'
-❯ Allow and remember? [y/N]
-```
-
-Use `--yes` to bypass prompts (useful for CI/automation).
-
## How does Worktrunk compare to alternatives?
### vs. branch switching
@@ -78,32 +51,6 @@ These tools can be used together—run git-machete or git-town inside individual
Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.
-## How does Worktrunk determine the default branch?
-
-Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.
-
-If the remote's default branch has changed (e.g., renamed from master to main), clear the cache with `wt config state default-branch clear`.
-
-For full details on the detection mechanism, see `wt config state default-branch --help`.
-
-## Does Worktrunk work on Windows?
-
-Yes. Core commands, shell integration, and tab completion work in both Git Bash and PowerShell. See [installation](https://worktrunk.dev/worktrunk/#install) for setup details, including avoiding the Windows Terminal `wt` conflict.
-
-**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.
-
-**`wt select` unavailable** — Uses [skim](https://github.com/skim-rs/skim), which doesn't support Windows. Use `wt list` and `wt switch <branch>` instead.
-
-## Installation fails with C compilation errors
-
-Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:
-
-```bash
-$ cargo install worktrunk --no-default-features
-```
-
-This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
-
## There's an issue with my shell setup
If shell integration isn't working (auto-cd not happening, completions missing, `wt` not found as a function), the fastest path to a fix is using Claude Code with the Worktrunk plugin:
@@ -153,7 +100,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
| Location | Purpose | Created by |
|----------|---------|------------|
| `.git/config` keys under `worktrunk.*` | Cached default branch, switch history, branch markers | Various commands |
-| `.git/wt-cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` CLI is installed |
+| `.git/wt-cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` or `glab` CLI is installed |
| `.git/wt-logs/*.log` | Background command output | Hooks, background `wt remove` |
None of this is tracked by git or pushed to remotes.
@@ -198,6 +145,59 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
See [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.
+## What commands does Worktrunk execute?
+
+Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `glab` (GitLab) for CI status. Beyond that, user-defined commands execute in four contexts:
+
+1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
+2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
+4. **--execute flag** — Explicitly provided commands
+
+User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
+
+### Example approval prompt
+
+```
+▲ repo needs approval to execute 3 commands:
+
+○ post-create install:
+ echo 'Installing dependencies...'
+○ post-create build:
+ echo 'Building project...'
+○ post-create test:
+ echo 'Running tests...'
+❯ Allow and remember? [y/N]
+```
+
+Use `--yes` to bypass prompts (useful for CI/automation).
+
+## Does Worktrunk work on Windows?
+
+Yes. Core commands, shell integration, and tab completion work in both Git Bash and PowerShell. See [installation](https://worktrunk.dev/worktrunk/#install) for setup details, including avoiding the Windows Terminal `wt` conflict.
+
+**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.
+
+**`wt select` unavailable** — Uses [skim](https://github.com/skim-rs/skim), which doesn't support Windows. Use `wt list` and `wt switch <branch>` instead.
+
+## How does Worktrunk determine the default branch?
+
+Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.
+
+If the remote's default branch has changed (e.g., renamed from master to main), clear the cache with `wt config state default-branch clear`.
+
+For full details on the detection mechanism, see `wt config state default-branch --help`.
+
+## Installation fails with C compilation errors
+
+Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:
+
+```bash
+$ cargo install worktrunk --no-default-features
+```
+
+This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
+
## Running tests (for contributors)
### Quick tests
diff --git a/docs/content/faq.md b/docs/content/faq.md
index e2eac25d6..9e645fa0b 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -6,37 +6,6 @@ weight = 25
group = "Reference"
+++
-## What commands does Worktrunk execute?
-
-Worktrunk executes commands in four contexts:
-
-1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
-2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
-4. **--execute flag** — Explicitly provided commands
-
-User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
-
-### Example approval prompt
-
-<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->
-
-```
-▲ repo needs approval to execute 3 commands:
-
-○ post-create install:
- echo 'Installing dependencies...'
-○ post-create build:
- echo 'Building project...'
-○ post-create test:
- echo 'Running tests...'
-❯ Allow and remember? [y/N]
-```
-
-<!-- END AUTO-GENERATED -->
-
-Use `--yes` to bypass prompts (useful for CI/automation).
-
## How does Worktrunk compare to alternatives?
### vs. branch switching
@@ -88,32 +57,6 @@ These tools can be used together—run git-machete or git-town inside individual
Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.
-## How does Worktrunk determine the default branch?
-
-Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.
-
-If the remote's default branch has changed (e.g., renamed from master to main), clear the cache with `wt config state default-branch clear`.
-
-For full details on the detection mechanism, see `wt config state default-branch --help`.
-
-## Does Worktrunk work on Windows?
-
-Yes. Core commands, shell integration, and tab completion work in both Git Bash and PowerShell. See [installation](@/worktrunk.md#install) for setup details, including avoiding the Windows Terminal `wt` conflict.
-
-**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.
-
-**`wt select` unavailable** — Uses [skim](https://github.com/skim-rs/skim), which doesn't support Windows. Use `wt list` and `wt switch <branch>` instead.
-
-## Installation fails with C compilation errors
-
-Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:
-
-```bash
-$ cargo install worktrunk --no-default-features
-```
-
-This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
-
## There's an issue with my shell setup
If shell integration isn't working (auto-cd not happening, completions missing, `wt` not found as a function), the fastest path to a fix is using Claude Code with the Worktrunk plugin:
@@ -163,7 +106,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
| Location | Purpose | Created by |
|----------|---------|------------|
| `.git/config` keys under `worktrunk.*` | Cached default branch, switch history, branch markers | Various commands |
-| `.git/wt-cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` CLI is installed |
+| `.git/wt-cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` or `glab` CLI is installed |
| `.git/wt-logs/*.log` | Background command output | Hooks, background `wt remove` |
None of this is tracked by git or pushed to remotes.
@@ -208,6 +151,63 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
See [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.
+## What commands does Worktrunk execute?
+
+Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `glab` (GitLab) for CI status. Beyond that, user-defined commands execute in four contexts:
+
+1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
+2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
+4. **--execute flag** — Explicitly provided commands
+
+User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
+
+### Example approval prompt
+
+<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->
+
+```
+▲ repo needs approval to execute 3 commands:
+
+○ post-create install:
+ echo 'Installing dependencies...'
+○ post-create build:
+ echo 'Building project...'
+○ post-create test:
+ echo 'Running tests...'
+❯ Allow and remember? [y/N]
+```
+
+<!-- END AUTO-GENERATED -->
+
+Use `--yes` to bypass prompts (useful for CI/automation).
+
+## Does Worktrunk work on Windows?
+
+Yes. Core commands, shell integration, and tab completion work in both Git Bash and PowerShell. See [installation](@/worktrunk.md#install) for setup details, including avoiding the Windows Terminal `wt` conflict.
+
+**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.
+
+**`wt select` unavailable** — Uses [skim](https://github.com/skim-rs/skim), which doesn't support Windows. Use `wt list` and `wt switch <branch>` instead.
+
+## How does Worktrunk determine the default branch?
+
+Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.
+
+If the remote's default branch has changed (e.g., renamed from master to main), clear the cache with `wt config state default-branch clear`.
+
+For full details on the detection mechanism, see `wt config state default-branch --help`.
+
+## Installation fails with C compilation errors
+
+Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:
+
+```bash
+$ cargo install worktrunk --no-default-features
+```
+
+This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
+
## Running tests (for contributors)
### Quick tests