Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: add FAQ entry for files Worktrunk creates (#429)
Maximilian Roosdce131be094f
diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 3361d24d8..8f2630481 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -141,6 +141,58 @@ $ cargo install worktrunk --no-default-featuresThis 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.+## What files does Worktrunk create?++Worktrunk creates files in four categories.++### 1. Worktree directories++Created by `wt switch <branch>` (or `wt select`) when switching to a branch that doesn't have a worktree. Use `wt switch --create <branch>` to create a new branch. Default location is `../<repo>.<branch>` (sibling to main repo), configurable via `worktree-path` in user config.++**To remove:** `wt remove <branch>` removes the worktree directory and deletes the branch.++### 2. Config files++| File | Created by | Purpose |+|------|------------|---------|+| `~/.config/worktrunk/config.toml` | `wt config create`, or approving project commands | User preferences, approved commands |+| `.config/wt.toml` | `wt config create --project` | Project hooks (checked into repo) |++User config location: `$XDG_CONFIG_HOME/worktrunk/` (or `~/.config/worktrunk/`) on Linux/macOS, `%APPDATA%\worktrunk\` on Windows.++**To remove:** Delete directly. User config: `rm ~/.config/worktrunk/config.toml`. Project config: `rm .config/wt.toml` (and commit).++### 3. Shell integration++Created by `wt config shell install`:++- **Bash**: adds line to `~/.bashrc`+- **Zsh**: adds line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)+- **Fish**: creates `~/.config/fish/conf.d/wt.fish` and `~/.config/fish/completions/wt.fish`++**To remove:** `wt config shell uninstall`.++### 4. Metadata in `.git/` (automatic)++Worktrunk stores small amounts of cache and log data in your repository's `.git/` directory:++| 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-logs/*.log` | Background command output | Hooks, background `wt remove` |++None of this is tracked by git or pushed to remotes.++**To remove:** `wt config state clear` removes all worktrunk keys from `.git/config`, deletes CI cache, and clears logs.++### What Worktrunk does NOT create++- No files outside `.git/`, config directories, or worktree directories+- No global git hooks+- No modifications to `~/.gitconfig`+- No background processes or daemons+## Running tests (for contributors)### Quick testsdiff --git a/src/commands/hook_filter.rs b/src/commands/hook_filter.rsindex 1cceed8be..cf3fadd08 100644--- a/src/commands/hook_filter.rs+++ b/src/commands/hook_filter.rs@@ -13,7 +13,7 @@pub enum HookSource {/// User hooks from ~/.config/worktrunk/config.toml (no approval required)User,- /// Project hooks from .worktrunk.toml (approval handled at gate)+ /// Project hooks from .config/wt.toml (approval handled at gate)Project,}diff --git a/src/commands/list/ci_status.rs b/src/commands/list/ci_status.rsindex f12a4460f..6a35317f2 100644--- a/src/commands/list/ci_status.rs+++ b/src/commands/list/ci_status.rs@@ -1080,7 +1080,7 @@ impl PrStatus {/// Returns None if no CI found or CLI tools unavailable////// # Caching- /// Results (including None) are cached in git config (`worktrunk.state.<branch>.ci-status`)+ /// Results (including None) are cached in `.git/wt-cache/ci-status/<branch>.json`/// for 30-60 seconds to avoid hitting GitHub API rate limits. TTL uses deterministic jitter/// based on repo path to spread cache expirations across concurrent statuslines. Invalidated/// when HEAD changes.