fix(git): scope git-workflow's trigger to ambiguity rather than to its domains
git-workflow's description enumerated the six domains it exists to route away from, so it competed for selection with the very skills it should be handing off to. It now triggers on the case it actually serves: an interactive request whose domain is not yet clear. Also clears frontmatter drift across the plugin and removes duplicated guidance in pc-run that had diverged from its reference.
This commit is contained in:
@@ -28,7 +28,7 @@ metadata:
|
||||
| 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) |
|
||||
| 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** under the conditions in `references/worktrees.md` |
|
||||
| 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 |
|
||||
@@ -40,15 +40,14 @@ metadata:
|
||||
|
||||
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`.
|
||||
disambiguation across several remotes, how to name a worktree unambiguously,
|
||||
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
|
||||
|
||||
@@ -4,6 +4,8 @@ source_keys:
|
||||
- git-scm-worktree-docs
|
||||
---
|
||||
|
||||
# Git worktrees
|
||||
|
||||
## Shared vs. per-worktree state
|
||||
|
||||
All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps
|
||||
@@ -12,6 +14,12 @@ its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `re
|
||||
worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed
|
||||
or moved. Every other worktree is a **linked worktree** created by `git worktree add`.
|
||||
|
||||
## Identifying a worktree
|
||||
|
||||
`lock`, `move`, `remove` and `repair` accept a full path, a unique basename, or a unique partial
|
||||
path. An ambiguous name errors rather than picking one; `git worktree list` shows the identifiers
|
||||
that are usable.
|
||||
|
||||
## `add` forms
|
||||
|
||||
```bash
|
||||
@@ -85,10 +93,11 @@ git worktree unlock <path> # when reconnected
|
||||
git worktree add --track -b <branch> <path> <remote>/<branch> # explicit: no guessing at all
|
||||
git worktree add <path> <branch> # shortcut: needs one clear remote
|
||||
```
|
||||
The shortcut fires only when `<branch>` is not found locally, none of `-b`/`-B`/`--detach` were
|
||||
given, and a tracking branch of that name exists in exactly one remote. When several remotes carry
|
||||
the name, `checkout.defaultRemote` picks one for disambiguation purposes; with no such setting the
|
||||
shortcut has no single remote to resolve against and does not apply.
|
||||
**The bare-name shortcut needs exactly one remote.** It fires only when `<branch>` is not found
|
||||
locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in
|
||||
exactly one remote. When several remotes carry the name, `checkout.defaultRemote` picks one for
|
||||
disambiguation purposes; with no such setting the shortcut has no single remote to resolve against
|
||||
and does not apply. When the remote is ambiguous or unknown, use the explicit `--track -b` form.
|
||||
|
||||
`--guess-remote` covers the *other* spelling — `git worktree add <path>` with no `<commit-ish>` at
|
||||
all. It bases the new branch on the remote-tracking branch matching `$(basename <path>)` when
|
||||
|
||||
Reference in New Issue
Block a user