Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(config): document the machine-local default-branch override (#3947)
Worktrunk Botaf04e80db0b0
diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.mdindex d5caa9859..b6f95a879 100644--- a/docs/src/content/docs/config.md+++ b/docs/src/content/docs/config.md@@ -1150,6 +1150,19 @@ Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` t`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:@@ -1159,7 +1172,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; `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, and inspection-only either way; `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 334a826a8..356cf4854 100644--- a/docs/src/content/docs/tips-patterns.md+++ b/docs/src/content/docs/tips-patterns.md@@ -244,6 +244,18 @@ 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++When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:++```bash+wt 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 d59539f25..64d523d09 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -1138,6 +1138,19 @@ Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` t`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:@@ -1147,7 +1160,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; `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, and inspection-only either way; `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 9d9d274fc..c4036d65f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md@@ -236,6 +236,18 @@ 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++When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:++```bash+wt 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 d59539f25..64d523d09 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -1138,6 +1138,19 @@ Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` t`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:@@ -1147,7 +1160,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; `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, and inspection-only either way; `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 9d9d274fc..c4036d65f 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -236,6 +236,18 @@ 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++When the branch a team integrates against isn't the one the remote's `HEAD` names, pin it per clone:++```bash+wt 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 28b009592..fe1051c30 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -851,6 +851,19 @@ Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` t`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:@@ -860,7 +873,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; `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, and inspection-only either way; `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 8eeedd65e..6a4fabf95 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@@ -11,6 +11,13 @@ info:CLICOLOR_FORCE: "1"COLUMNS: "500"GIT_ALLOW_PROTOCOL: file+ GIT_CONFIG_COUNT: "2"+ GIT_CONFIG_GLOBAL: /nonexistent/wt/gitconfig+ GIT_CONFIG_KEY_0: user.useConfigOnly+ GIT_CONFIG_KEY_1: rerere.enabled+ GIT_CONFIG_SYSTEM: /nonexistent/wt/gitconfig+ GIT_CONFIG_VALUE_0: "true"+ GIT_CONFIG_VALUE_1: "false"LANG: CLC_ALL: CLLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"@@ -30,6 +37,7 @@ info:WORKTRUNK_TEST_PARENT_SHELL: ""WORKTRUNK_TEST_POWERSHELL_ENV: "0"WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"+ WORKTRUNK_TEST_PROBE_TIMEOUT_MS: "60000"WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"WORKTRUNK_TEST_ZSH_INSTALLED: "0"---@@ -75,6 +83,17 @@ Without a subcommand, runs [2mget[0m. Use [2mset[0m to override, or [2mclea[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:@@ -84,7 +103,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; [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, and inspection-only either way; [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.