Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(config): shorten default-branch override guidance (#3948)
Maximilian Roosec7db8313627
diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.mdindex b6f95a879..9d8791d11 100644--- a/docs/src/content/docs/config.md+++ b/docs/src/content/docs/config.md@@ -1146,23 +1146,10 @@ $ git rebase $(wt config state default-branch)In a hook or alias template, prefer the `{{ default_branch }}` [template variable](/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.-Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.+Without a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### Overriding without a config file--`set` writes `worktrunk.default-branch` to the repository's local git config, which git never commits or pushes — so the override stays on one machine. There is no config-file key for the default branch, so this is the only way to override detection:--```console-$ wt config state default-branch set integration-✓ Set default branch to integration-```--That covers a repo whose remote `HEAD` names a branch other than the one to integrate against, without adding a Worktrunk file to a repository owned by someone else. Local git config lives in the common git dir, so one `set` applies to every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override, then skips the comparisons against the default branch.-### DetectionWorktrunk detects the default branch automatically:@@ -1172,7 +1159,7 @@ Worktrunk detects the default branch automatically:3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override, and inspection-only either way; `set` adopts the new branch and `clear` re-detects.+Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.diff --git a/docs/src/content/docs/tips-patterns.md b/docs/src/content/docs/tips-patterns.mdindex 356cf4854..d7b17b3a6 100644--- a/docs/src/content/docs/tips-patterns.md+++ b/docs/src/content/docs/tips-patterns.md@@ -244,18 +244,14 @@ git rebase $(wt config state default-branch)In hooks and aliases, the same value is the `{{ default_branch }}` [template variable](/hook/#template-variables); reserve this command for plain shell scripts.-## Override `default-branch` without a config file+## Override `default-branch` for one clone-When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:+When the integration branch differs from the remote's `HEAD`, set a [clone-local override](/config/#wt-config-state-default-branch):```bashwt config state default-branch set integration```-The value is stored as `worktrunk.default-branch` in the repository's local git config, which git never commits or pushes — so nothing is added to a repository owned by a client or an upstream project. There is no config-file key for the default branch, so this is the only way to override detection, and because local git config lives in the common git dir, one `set` covers every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override. `wt config state` reports the difference from the remote's `HEAD` as drift, which is expected for a deliberate override; `wt config state default-branch clear` drops it and [re-detects](/config/#wt-config-state-default-branch).-## Task runners in hooksReference Taskfile/Justfile/Makefile in hooks:diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.mdindex 64d523d09..954084c17 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -1134,23 +1134,10 @@ $ git rebase $(wt config state default-branch)In a hook or alias template, prefer the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.-Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.+Without a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### Overriding without a config file--`set` writes `worktrunk.default-branch` to the repository's local git config, which git never commits or pushes — so the override stays on one machine. There is no config-file key for the default branch, so this is the only way to override detection:--```console-$ wt config state default-branch set integration-✓ Set default branch to integration-```--That covers a repo whose remote `HEAD` names a branch other than the one to integrate against, without adding a Worktrunk file to a repository owned by someone else. Local git config lives in the common git dir, so one `set` applies to every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override, then skips the comparisons against the default branch.-### DetectionWorktrunk detects the default branch automatically:@@ -1160,7 +1147,7 @@ Worktrunk detects the default branch automatically:3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override, and inspection-only either way; `set` adopts the new branch and `clear` re-detects.+Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.diff --git a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.mdindex c4036d65f..96385f28a 100644--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md@@ -236,18 +236,14 @@ git rebase $(wt config state default-branch)In hooks and aliases, the same value is the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); reserve this command for plain shell scripts.-## Override `default-branch` without a config file+## Override `default-branch` for one clone-When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:+When the integration branch differs from the remote's `HEAD`, set a [clone-local override](https://worktrunk.dev/config/#wt-config-state-default-branch):```bashwt config state default-branch set integration```-The value is stored as `worktrunk.default-branch` in the repository's local git config, which git never commits or pushes — so nothing is added to a repository owned by a client or an upstream project. There is no config-file key for the default branch, so this is the only way to override detection, and because local git config lives in the common git dir, one `set` covers every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override. `wt config state` reports the difference from the remote's `HEAD` as drift, which is expected for a deliberate override; `wt config state default-branch clear` drops it and [re-detects](https://worktrunk.dev/config/#wt-config-state-default-branch).-## Task runners in hooksReference Taskfile/Justfile/Makefile in hooks:diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 64d523d09..954084c17 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -1134,23 +1134,10 @@ $ git rebase $(wt config state default-branch)In a hook or alias template, prefer the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.-Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.+Without a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### Overriding without a config file--`set` writes `worktrunk.default-branch` to the repository's local git config, which git never commits or pushes — so the override stays on one machine. There is no config-file key for the default branch, so this is the only way to override detection:--```console-$ wt config state default-branch set integration-✓ Set default branch to integration-```--That covers a repo whose remote `HEAD` names a branch other than the one to integrate against, without adding a Worktrunk file to a repository owned by someone else. Local git config lives in the common git dir, so one `set` applies to every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override, then skips the comparisons against the default branch.-### DetectionWorktrunk detects the default branch automatically:@@ -1160,7 +1147,7 @@ Worktrunk detects the default branch automatically:3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override, and inspection-only either way; `set` adopts the new branch and `clear` re-detects.+Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex c4036d65f..96385f28a 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -236,18 +236,14 @@ git rebase $(wt config state default-branch)In hooks and aliases, the same value is the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); reserve this command for plain shell scripts.-## Override `default-branch` without a config file+## Override `default-branch` for one clone-When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:+When the integration branch differs from the remote's `HEAD`, set a [clone-local override](https://worktrunk.dev/config/#wt-config-state-default-branch):```bashwt config state default-branch set integration```-The value is stored as `worktrunk.default-branch` in the repository's local git config, which git never commits or pushes — so nothing is added to a repository owned by a client or an upstream project. There is no config-file key for the default branch, so this is the only way to override detection, and because local git config lives in the common git dir, one `set` covers every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override. `wt config state` reports the difference from the remote's `HEAD` as drift, which is expected for a deliberate override; `wt config state default-branch clear` drops it and [re-detects](https://worktrunk.dev/config/#wt-config-state-default-branch).-## Task runners in hooksReference Taskfile/Justfile/Makefile in hooks:diff --git a/src/cli/config.rs b/src/cli/config.rsindex fe1051c30..f3ac8a47b 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -847,23 +847,10 @@ $ git rebase $(wt config state default-branch)In a hook or alias template, prefer the `{{ default_branch }}` [template variable](/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.-Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.+Without a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-## Overriding without a config file--`set` writes `worktrunk.default-branch` to the repository's local git config, which git never commits or pushes — so the override stays on one machine. There is no config-file key for the default branch, so this is the only way to override detection:--```console-$ wt config state default-branch set integration-✓ Set default branch to integration-```--That covers a repo whose remote `HEAD` names a branch other than the one to integrate against, without adding a Worktrunk file to a repository owned by someone else. Local git config lives in the common git dir, so one `set` applies to every linked worktree of that clone.--Check the branch out locally first. With only `origin/integration` fetched, `set` warns that the branch doesn't exist locally, and every `wt list` repeats that warning with a hint to clear the override, then skips the comparisons against the default branch.-## DetectionWorktrunk detects the default branch automatically:@@ -873,7 +860,7 @@ Worktrunk detects the default branch automatically:3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override, and inspection-only either way; `set` adopts the new branch and `clear` re-detects.+Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snapindex 6a4fabf95..99eb5448e 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap@@ -79,21 +79,10 @@ Useful in scripts to avoid hardcoding [2mmain[0m or [2mmaster[0m:In a hook or alias template, prefer the [2m{{ default_branch }}[0m template variable; [2m$(wt config state default-branch)[0m is for plain shell scripts.-Without a subcommand, runs [2mget[0m. Use [2mset[0m to override, or [2mclear[0m then [2mget[0m to re-detect.+Without a subcommand, runs [2mget[0m. [2mset[0m stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. [2mclear[0m then [2mget[0m re-detects. The branch must exist locally for [2mwt list[0m comparisons.[2mdefault-branch get[0m resolves the value and caches it on a miss; the aggregate [2mwt config state get[0m only reports the cache (read-only), so it can show [2m(none)[0m until something populates it.-[1m[32mOverriding without a config file[0m--[2mset[0m writes [2mworktrunk.default-branch[0m to the repository's local git config, which git never commits or pushes — so the override stays on one machine. There is no config-file key for the default branch, so this is the only way to override detection:--[107m [0m [2m[0m[2m[34mwt[0m[2m config state default-branch set integration[0m-[107m [0m [2m[0m[2m[34m✓[0m[2m Set default branch to integration[0m--That covers a repo whose remote [2mHEAD[0m names a branch other than the one to integrate against, without adding a Worktrunk file to a repository owned by someone else. Local git config lives in the common git dir, so one [2mset[0m applies to every linked worktree of that clone.--Check the branch out locally first. With only [2morigin/integration[0m fetched, [2mset[0m warns that the branch doesn't exist locally, and every [2mwt list[0m repeats that warning with a hint to clear the override, then skips the comparisons against the default branch.-[1m[32mDetection[0mWorktrunk detects the default branch automatically:@@ -103,7 +92,7 @@ Worktrunk detects the default branch automatically:3. [1mRemote query[0m — If not cached, queries [2mgit ls-remote[0m — typically 100ms–2s, abandoned after 10s4. [1mLocal inference[0m — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in [2mworktrunk.default-branch[0m for fast access. The cache isn't re-validated on every command, so a later change to [2morigin/HEAD[0m — a renamed default branch followed by [2mgit remote set-head origin -a[0m — isn't picked up automatically. [2mwt config state[0m flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override, and inspection-only either way; [2mset[0m adopts the new branch and [2mclear[0m re-detects.+Once detected, the result is cached in [2mworktrunk.default-branch[0m for fast access. The cache isn't re-validated on every command, so a later change to [2morigin/HEAD[0m — a renamed default branch followed by [2mgit remote set-head origin -a[0m — isn't picked up automatically. [2mwt config state[0m flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; [2mset[0m adopts the new branch and [2mclear[0m re-detects.An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.