cli: worktree add takes the branch positionally with create-vs-checkout magic - git's own signature is -b; align or pin the divergence #171

New issue

Closed

opened 2026-07-16 21:51:16 +00:00 by hexajon · 2 comments

hexajon commented

2026-07-16 21:51:16 +00:00

(Migrated from codeberg.org)

madtea worktree add <path> [branch] takes the branch as a positional, and AddWorktree (internal/service/git/worktree.go) decides what it means: branch exists, check it out; branch missing, create it (git worktree add -b). Raw git's vocabulary is different - the positional after the path is a commit-ish to check out, and creating a new branch is the explicit -b <branch>. madtea's worktree add has no -b (only -f).

No ADR guards this today: ADR 0005 (explicit canonical parameter names) is MCP-side, and ADR 0016 pins flag names to gh/tea, not flag-vs-positional shape - and for git-mirrored commands the vocabulary anchor is git itself. The anchor is real: the README shipped worktree add -b feat/... as fiction until 2026-07-16 because -b is the muscle-memory signature. ADR 0005 makes exactly this training-data-anchor argument for the MCP surface.

Decide one:

Adopt git's signature. -b <branch> creates; the positional stays a plain commit-ish checkout with no silent create. Breaking change to the current positional-create behavior; #169's cobra-subcommand conversion is the natural vehicle.
Pin the smart positional as deliberate. One argument, does the right thing, no flag to remember - defensible, but then it needs a naming-conventions divergence entry and a line in the ADR record so the next person (or README author) doesn't assume -b.

Either way the MCP surface is unaffected: madt_worktrees action=add already takes an explicit branch= parameter.

Related: #169, #170.

`madtea worktree add <path> [branch]` takes the branch as a positional, and `AddWorktree` (internal/service/git/worktree.go) decides what it means: branch exists, check it out; branch missing, create it (`git worktree add -b`). Raw git's vocabulary is different - the positional after the path is a commit-ish to *check out*, and creating a new branch is the explicit `-b <branch>`. madtea's worktree add has no `-b` (only `-f`). No ADR guards this today: ADR 0005 (explicit canonical parameter names) is MCP-side, and ADR 0016 pins flag *names* to gh/tea, not flag-vs-positional shape - and for git-mirrored commands the vocabulary anchor is git itself. The anchor is real: the README shipped `worktree add -b feat/...` as fiction until 2026-07-16 because `-b` is the muscle-memory signature. ADR 0005 makes exactly this training-data-anchor argument for the MCP surface. Decide one: - **Adopt git's signature.** `-b <branch>` creates; the positional stays a plain commit-ish checkout with no silent create. Breaking change to the current positional-create behavior; #169's cobra-subcommand conversion is the natural vehicle. - **Pin the smart positional as deliberate.** One argument, does the right thing, no flag to remember - defensible, but then it needs a naming-conventions divergence entry and a line in the ADR record so the next person (or README author) doesn't assume `-b`. Either way the MCP surface is unaffected: `madt_worktrees action=add` already takes an explicit `branch=` parameter. Related: #169, #170.

hexajon commented

2026-07-17 14:36:57 +00:00

(Migrated from codeberg.org)

We follow git for this, positional is not explicit. Probably need to record ADR.

hexajon commented

2026-07-17 16:39:38 +00:00

(Migrated from codeberg.org)

Design pinned for implementation (decision above: follow git):

madtea worktree add <path> [<commit-ish>] - the positional after path is a plain checkout of an existing ref, exactly git's meaning; it never silently creates.
-b <branch> is the explicit create form (git worktree add -b). Asking for a positional branch that does not exist is an error naming -b as the create path.
MCP surface unchanged (madt_worktrees action=add branch= already explicit; its create-or-checkout convenience stays because the param name carries the intent).
Recorded as a short ADR (next free number): git-mirrored CLI commands anchor their argument SHAPE (flag vs positional) to git's own signature, not just their flag names - the general rule this instance instantiates, so the next git-mirrored command doesn't relitigate it. Naming-conventions doc gets the pointer.
Breaking change to the current positional-create behavior; lands in the next minor per the 0.x tiering.

Design pinned for implementation (decision above: follow git): - `madtea worktree add <path> [<commit-ish>]` - the positional after path is a plain checkout of an existing ref, exactly git's meaning; it never silently creates. - `-b <branch>` is the explicit create form (git worktree add -b). Asking for a positional branch that does not exist is an error naming -b as the create path. - MCP surface unchanged (madt_worktrees action=add branch= already explicit; its create-or-checkout convenience stays because the param name carries the intent). - Recorded as a short ADR (next free number): git-mirrored CLI commands anchor their argument SHAPE (flag vs positional) to git's own signature, not just their flag names - the general rule this instance instantiates, so the next git-mirrored command doesn't relitigate it. Naming-conventions doc gets the pointer. - Breaking change to the current positional-create behavior; lands in the next minor per the 0.x tiering.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#171

No description provided.

Rows
Columns