Skip to content

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.md
index 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 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 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.rs
index 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,