Defame1297
ddf85518c7
The dispatch row "Create tracking a remote branch" prescribed `git worktree add <path> <remote>/<branch>`. Per git-worktree(1) the tracking DWIM fires only when <commit-ish> is a bare branch name that is NOT found locally, no -b/-B/--detach is given, and exactly one remote has a matching name; only then is it equivalent to `git worktree add --track -b <branch> <path> <remote>/<branch>`. An explicit <remote>/<branch> is found, so that precondition fails and no branch is created: the result is a detached HEAD with no upstream. Commits made in it become unreachable once the worktree is removed or HEAD moves, and push needs an explicit refspec. Only the -d row was flagged detached. The table now names --track -b as the always-correct form, keeps the bare name shortcut with its precondition stated, and adds a Never row for the <remote>/<branch> spelling. The single-remote and checkout.defaultRemote preconditions move into the body, since a reader who trusts the table never follows the reference pointer. Also corrects `git worktree repair`: the no-argument form is the only cwd-dependent one, and `repair <path>...` runs from any worktree. The claim that running it from the wrong directory "reports nothing and fixes nothing" has no basis in the manual and is removed. Found by an independent review of this branch. Refs #99
68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
---
|
|
name: git-worktrees
|
|
|
|
description: >
|
|
Use when working on several branches at once without stashing —
|
|
manages the full lifecycle of a git worktree.
|
|
Not ordinary branch switching or checkout -> `git-branches`.
|
|
Not interactive multi-step git guidance -> `git-workflow`.
|
|
|
|
metadata:
|
|
category: git
|
|
source_keys:
|
|
- git-scm-worktree-docs
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **A branch can be checked out in only one worktree at a time.** `git worktree add` on an already-checked-out branch fails; `--force` is the only override, so use it only deliberately.
|
|
- **Never `rm -rf` a worktree directory.** That strands metadata in `$GIT_DIR/worktrees/`. Use `git worktree remove`, or `git worktree prune` afterwards.
|
|
- **Submodules break worktree support.** A worktree containing submodules cannot be moved at all, and needs `--force` to remove.
|
|
- **`extensions.worktreeConfig = true` is a one-way door.** It costs compatibility with older Git and forces `core.bare`/`core.worktree` into `config.worktree`. Leave it off unless per-worktree config is needed.
|
|
|
|
## Step 1 — Dispatch
|
|
|
|
| Operation | Run |
|
|
|---|---|
|
|
| Create on a branch that already exists locally | `git worktree add <path> <branch>` |
|
|
| Create on a new branch | `git worktree add -b <branch> <path>` |
|
|
| Create on the branch named after the path basename | `git worktree add <path>` — checks that branch out if it exists, else creates it from HEAD |
|
|
| Create and reset an existing branch to HEAD — discards its commits | `git worktree add -B <branch> <path>` |
|
|
| Create a local branch tracking a remote one | `git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** when `<branch>` has no local copy (gate below) |
|
|
| Throwaway experiment, no branch | `git worktree add -d <path>` — detached HEAD |
|
|
| **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above |
|
|
| List | `git worktree list -v`, or `--porcelain -z` to parse |
|
|
| Lock or unlock | `git worktree lock [--reason <str>] <path>` / `git worktree unlock <path>` |
|
|
| Move | `git worktree move <from> <to>` |
|
|
| Remove | `git worktree remove <path>` |
|
|
| Prune stale metadata | `git worktree prune --dry-run`, then without the flag |
|
|
| Repair after a manual move | `git worktree repair` — in the main worktree if *it* moved, or inside a linked worktree that moved. `git worktree repair <path>...` — from any worktree, naming each moved linked worktree's new path |
|
|
|
|
If the operation needs anything the table does not carry — the full `add` flag
|
|
table, orphan branches, sparse-checkout, locking for removable media, remote
|
|
disambiguation across several remotes, worktree config keys, or the worked
|
|
emergency-fix and PR-review patterns — read `references/worktrees.md`.
|
|
|
|
Gates:
|
|
|
|
- **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates.
|
|
- **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state.
|
|
- **`lock`, `move`, `remove`, `repair` — identify a worktree by full path, unique basename, or unique partial path.** An ambiguous name errors rather than picking; `git worktree list` shows the usable identifiers.
|
|
- **`add` — the bare-name tracking shortcut needs exactly one remote.** `git worktree add <path> <branch>` sets up tracking only when `<branch>` is absent locally, no `-b`/`-B`/`-d` is given, and exactly one remote carries the name. With several, it fires only if `checkout.defaultRemote` names one. When the remote is ambiguous or unknown, use `--track -b`.
|
|
- **`add` — lock at creation, not after.** `git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
|
|
|
|
## Step 2 — Report
|
|
|
|
```yaml
|
|
worktrees:
|
|
- path: <directory-path>
|
|
branch: <branch-name>
|
|
commit: <short-hash>
|
|
locked: <true/false>
|
|
lock_reason: <reason or empty>
|
|
```
|
|
|
|
Derive those fields from `git worktree list --porcelain -z`. For a single
|
|
operation, report its outcome instead — `created: true`, `moved: true`,
|
|
`removed: true`.
|