Spec multi-arg audit: git and the editor diff options

[warp-agent-staging]

Audit of the options in this group that declare two or more args, part of the corpus-wide pass following the ln fix in #341. Group: git and the editor diff options.

The completer resolves the last declared arg of a multi-arg option regardless of which value is being typed, so a mis-modelled option actively breaks completion. Every verdict below was checked against the tool's own ground truth before anything was edited.

Ground truth used

• git 2.43.0, installed and run in this environment: git branch -h, git switch -h, git config -h. No git man pages were installed, so the synopses were cross-checked against https://git-scm.com/docs/git-branch and https://git-scm.com/docs/git-switch.
• VS Code: code is not installable here, so the official parser definition was used — src/vs/platform/environment/node/argv.ts in microsoft/vscode.

Why git appears twice

The scan found the git options in two files because two specs describe git:

• command-signatures/json/git.json — the maintained spec, using Rust generatorName references.
• command-signatures/json/hub.json — a stale Fig-derived copy of the same spec (its internal "name" is literally "git", and it carries no hub-specific subcommands). Lookup in assets.rs is by filename, so this file is what ships for the hub command, which proxies git. Both are real and both are fixed here.

One difference matters: every arg in hub.json carries inline Fig JavaScript generators, a field the Rust Arg struct in completion-metadata/src/fig_types.rs does not deserialize. Those args therefore produce no suggestions at all today. No generatorName was introduced in hub.json, because hub has no registered generator set in generators/mod.rs — a name there would pass all_referenced_generators_exist (which pools names across all commands) but resolve to nothing at runtime.

Options changed

Option	File	Category	Evidence
git branch -m / --move	git.json, hub.json	1 — operands written into the option	git branch -h: -m, --[no-]move move/rename a branch and its reflog, listed under "Specific git-branch actions" with no value placeholder. Usage line: git branch [<options>] (-m | -M) [<old-branch>] <new-branch> — the two names are operands of git branch.
git branch -M	git.json, hub.json	1	git branch -h: -M move/rename a branch, even if target exists — no value placeholder; same usage line.
git branch --no-track	git.json, hub.json	1	git branch -h: -t, --[no-]track[=(direct|inherit)] — the negated form takes no value. Its two local_branches args were the <branch-name> [<start-point>] operands from git branch [--track[=(direct|inherit)] | --no-track] [-f] [--recurse-submodules] <branch-name> [<start-point>].
git branch -t / --track	git.json, hub.json	3 — value set enumerated as args	git branch -h: -t, --[no-]track[=(direct|inherit)]. The declared [branch, start point] was wrong on both counts: the value set is direct|inherit, and those two names are the command's operands. The args are removed and the option left boolean — see "The --track value is unmodellable today" below for why it does not become a one-argument option.
git switch -c / --create	git.json, hub.json	1	git switch -h: -c, --[no-]create <branch> — exactly one value. Synopsis: git switch [<options>] (-c|-C) <new-branch> [<start-point>] — the start-point is an operand of switch.
git switch -C / --force-create	git.json, hub.json	1	git switch -h: -C, --[no-]force-create <branch> — exactly one value; same synopsis line.
git switch -t / --track	git.json, hub.json	3	git switch -h: -t, --[no-]track[=(direct|inherit)]. Same treatment as the git branch copy: args removed, option left boolean.
git switch --no-track	git.json, hub.json	1	git-switch(1) documents --no-track with no value: "Do not set up 'upstream' configuration…". Its args were duplicates of switch's own positionals.
code -d / --diff	code.json	1	microsoft/vscode, src/vs/platform/environment/node/argv.ts:104: 'diff': { type: 'boolean', cat: 'o', alias: 'd', args: ['file', 'file'], … }. type is 'boolean', so diff goes into booleanOptions and is passed to minimist(args, { boolean: booleanOptions, … }) (argv.ts:328); the two paths land in argv._. The args field is read only by formatUsage (argv.ts:400-408) to render the help line. --merge in the same table is also type: 'boolean' with four "args", which confirms the field is help-text metadata rather than option values.
code-insiders -d / --diff	code-insiders.json	1	Same file, same option definition; code-insiders is the Insiders build of the same CLI.

One structural addition

git branch had no top-level args in either spec, so removing the option args alone would have dropped branch-name completion outright — git branch -m ⇥ would have offered nothing. The documented operand was therefore added to the branch subcommand as an optional variadic branch-name, per the synopsis forms in git-branch(1). In git.json it carries generatorName: local_branches (the same generator the removed option args used, so today's suggestions are preserved); in hub.json it carries no generator, for the reason above.

The --track value is unmodellable today — please do not "fix" this back

--track does accept direct or inherit, so it is tempting to model it as a single optional argument carrying those two suggestions. That would be wrong, and the omission here is deliberate.

git's parse-options marks --track as OPTION_OPTARG, so the value is legal only when attached. Both forms were run to confirm:

• git branch --track=direct attached start — succeeds.
• git branch --track direct spaced start — prints usage and fails.

A normal optional argument in this schema models the space-separated form, so suggesting direct/inherit there would confidently complete a command git rejects. The schema cannot express the attached-only form either:

• CommandOption.requires_equals exists in completion-metadata/src/fig_types.rs (deserialized from requiresEquals), but From<CommandOption> for Opt (fig_types.rs:485-499) copies only name, description, args, is_required and priority — requires_equals is silently dropped.
• Opt itself (completion-metadata/src/signature.rs:169-176) has no such field, so the information cannot reach the completer at all.

Until requiresEquals is plumbed through to Opt, suggesting nothing beats suggesting an invalid command. --track therefore stays boolean in all four places.

Options verified as correct and left alone

Option	Category	Evidence
git config --get-urlmatch [name, url]	4 — genuinely multi-valued	git config -h: --[no-]get-urlmatch get value specific for the URL: section[.var] URL — two values.
git config --get-color [name, default]	4	git config -h: --[no-]get-color find the color configured: slot [default] — two values, the second optional. Matches the spec's [name, default (isOptional)] exactly.

Other residuals

Nothing in this group was left unresolved for lack of ground truth. Two further things a reviewer should know:

1. git switch -c <name> ⇥ loses the commits generator. Before the fix, the second declared arg (start point, generatorName: commits) was what the completer resolved — meaning you got git log --oneline hashes while typing the new branch name, which is the bug. After the fix, the start-point operand falls through to switch's own first positional, which offers local_branches + refs_remote_branches rather than commits. Branches are valid start points, so this is a narrower suggestion set at that position, not a broken one. Widening switch's first positional to include commits would pollute plain git switch <branch>, where a bare commit is not accepted, so it was left alone.
2. git branch -m was not user-visibly broken before, because both of its declared args were the identical local_branches generator, so the last-arg bug produced the right answer by coincidence. The modelling was still wrong, and the fix keeps the same suggestions via the new top-level positional.

Noticed outside this group, not touched

• code / code-insiders -a/--add and -g/--goto are the same class of error but declare a single arg, so they fell below the scan's two-or-more threshold. argv.ts:106,108 declares both type: 'boolean' with help-only args; their operands belong to the command, which already has a variadic filepaths+folders positional.
• git.json sets "requiresSeparator": true on git log --diff-filter, but requiresSeparator is not a field on CommandOption in completion-metadata/src/fig_types.rs, so it is silently dropped at deserialization. Renaming it to requiresEquals would not help, for the reason given above.

Validation

• cargo test -p warp-command-signatures — 176 passed, 0 failed. This covers all_command_specs_succeed_deserialization and all_referenced_generators_exist.
• npx prettier --check on all four edited files — clean.

Computer-use video recordings (1)

View video recording - GUI validation of this PR: typing git branch , git branch -m , git branch -m fea and git branch --track , showing branch names offered from the newly added positional in every form, with no duplicated pair.

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.

  

[warp-for-oss]

@acarl005

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-agent-staging]

Per-hunk reasoning, inline below, so the evidence sits next to the change instead of only in the description.

Ground truth was git 2.43.0's own -h output, run in this environment — no git man pages were installed, so the synopses were cross-checked against git-scm.com. For VS Code, code could not be installed here, so the authority is the option table in src/vs/platform/environment/node/argv.ts in microsoft/vscode.

Two options in scope are deliberately absent from the diff. Both were checked and are genuinely two-valued, per git config -h:

• --get-urlmatch [name, url] — --[no-]get-urlmatch get value specific for the URL: section[.var] URL
• --get-color [name, default] — --[no-]get-color find the color configured: slot [default], the second value optional, matching the spec's isOptional exactly.

They sit roughly 6,000 lines from the nearest hunk in git.json, and GitHub only accepts inline comments on lines inside the diff, so that note is here rather than anchored.

Responding as wilson: Open session · View in factory

[warp-agent-staging]

VS Code's parser treats --diff as a mode flag, so the two paths are never consumed by the option. argv.ts:104: 'diff': { type: 'boolean', cat: 'o', alias: 'd', args: ['file', 'file'], … } — type: 'boolean' puts diff into booleanOptions, which is handed to minimist(args, { boolean: booleanOptions, … }) at argv.ts:328, so both paths land in argv._.

The args field is read only by formatUsage (argv.ts:400-408) to render the help line; --merge on the next line is also type: 'boolean' with four "args", which settles that it is help metadata rather than option values. code's top-level variadic filepaths+folders positional already serves the operands, so nothing is lost.

[warp-agent-staging]

Same option, same source: code-insiders is the Insiders build of the same CLI and shares argv.ts. Reasoning is on the code.json hunk.

[warp-agent-staging]

Both are listed by git branch -h with no value placeholder — -m, --[no-]move move/rename a branch and its reflog and -M move/rename a branch, even if target exists — so neither consumes a value. The two branch names are operands of the command, per the usage line git branch [<options>] (-m | -M) [<old-branch>] <new-branch>; they keep their local_branches completions through the subcommand positional added further down this file.

[warp-agent-staging]

git branch -h: -t, --[no-]track[=(direct|inherit)]. The value set is direct|inherit — never a branch and a start point, which is what the removed args claimed.

It stays a bare flag rather than becoming a one-value option because git accepts the value only when attached: git branch --track=direct attached start succeeds, git branch --track direct spaced start prints usage (parse-options marks it OPTION_OPTARG). We cannot express attachment today — requires_equals is dropped by From<CommandOption> for Opt (fig_types.rs:485-499) and Opt (signature.rs:169-176) has no such field — so offering direct/inherit at a space-separated position would confidently complete a command git rejects.

[warp-agent-staging]

The negated half of -t, --[no-]track[=(direct|inherit)] takes no value at all. The two local_branches args it carried were the command's own operands, from git branch [--track[=(direct|inherit)] | --no-track] [-f] [--recurse-submodules] <branch-name> [<start-point>].

[warp-agent-staging]

Mirrors the git branch positional added in git.json, with one deliberate difference: no generatorName. hub has no registered generator set in generators/mod.rs, so a name here would satisfy all_referenced_generators_exist — that test pools generator names across all commands — while resolving to nothing at runtime.

[warp-agent-staging]

Mirrors git switch -c in git.json.

[warp-agent-staging]

Mirrors git switch -C in git.json.

[warp-agent-staging]

Mirrors git switch --track in git.json.

[warp-agent-staging]

Mirrors git switch --no-track in git.json.

[warp-for-oss]

Overview

This PR updates static command signature metadata for VS Code diff flags and git branch/switch options by removing option-level args that represent command operands or help-only metadata, and by adding a branch positional operand so branch-name completion is not dropped.

Concerns

• No blocking correctness concerns found in the annotated diff.
• Security pass found no issues: the changes are static JSON metadata only, with no new executable code, dependencies, auth paths, input handling, or secrets.
• Spec alignment was not applicable because spec_context.md contains no approved or repository spec context.
• Comment/test audit: no code comments or tests were added or changed in the diff.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz