Skip to content

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.md
index 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.
+
### Detection
Worktrunk 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 10s
4. **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.md
index 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 hooks
Reference Taskfile/Justfile/Makefile in hooks:
diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.md
index 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.
+
### Detection
Worktrunk 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 10s
4. **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.md
index 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 hooks
Reference Taskfile/Justfile/Makefile in hooks:
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 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.
+
### Detection
Worktrunk 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 10s
4. **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.md
index 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 hooks
Reference Taskfile/Justfile/Makefile in hooks:
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 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.
+
## Detection
Worktrunk 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 10s
4. **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.snap
index 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: C
LC_ALL: C
LLVM_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 get. Use set to override, or clea
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:
+
+  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.
+
Detection
Worktrunk detects the default branch automatically:
@@ -84,7 +103,7 @@ Worktrunk detects the default branch automatically:
3. Remote query — If not cached, queries git ls-remote — typically 100ms–2s, abandoned after 10s
4. 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.