Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Document default branch detection mechanism
Maximilian Roos9e5b8820f2f8
diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 82672de79..0565d70a6 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -88,6 +88,14 @@ These tools can be used together—run git-machete or git-town inside individualGit 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 your remote's default branch has changed (e.g., renamed from master to main), refresh with `wt config cache refresh`.++For full details on the detection mechanism, see `wt config cache --help`.+## How does wt switch resolve branch names?Arguments resolve by checking the filesystem before git branches:diff --git a/src/cli.rs b/src/cli.rsindex 9b48e8d2c..bde14b723 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -313,6 +313,25 @@ commit messages."#},/// Manage caches (CI status, default branch)+ #[command(after_long_help = r#"## Default branch detection++Worktrunk determines the default branch using:++1. **Local cache** — Check `refs/remotes/origin/HEAD`, a symbolic ref that git+ uses to track the remote's default branch. This is created by `git clone`+ or `git remote set-head`. Instant, no network required.++2. **Remote query** — If the local cache doesn't exist, query the remote with+ `git ls-remote --symref origin HEAD` to see what branch HEAD points to.+ This requires network access (100ms–2s). The result is cached locally via+ `git remote set-head origin <branch>`.++3. **Local inference** — If no remote is configured: check git's+ `init.defaultBranch` config, then look for branches named `main`, `master`,+ `develop`, or `trunk`.++Use `wt config cache refresh` when the remote's default branch has changed+(e.g., renamed from `master` to `main`)."#)]Cache {#[command(subcommand)]action: CacheCommand,