Skip to content

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.md
index 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.
-
### Detection
Worktrunk 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 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 — 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.md
index 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):
```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 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.
-
### Detection
Worktrunk 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 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 — 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.md
index 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):
```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 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.
-
### Detection
Worktrunk 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 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 — 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.md
index 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):
```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 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.
-
## Detection
Worktrunk 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 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 — 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.snap
index 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 main or master:
In a hook or alias template, prefer the {{ default_branch }} template variable; $(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:
-
-  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:
@@ -103,7 +92,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 — 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.