Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acarl005 merged 2 commits into from
Aug 24, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
644cdcf
Fix multi-arg option modelling: git branch/switch, code --diff
warp-agent-staging[bot] Aug 23, 2026
9382691
Revert --track to a boolean flag in git branch and git switch
warp-agent-staging[bot] Aug 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 1 addition & 11 deletions command-signatures/json/code-insiders.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,7 @@
"-d",
"--diff"
],
"description": "Compare two files with each other",
"args": [
{
"name": "file",
"template": "filepaths"
},
{
"name": "file",
"template": "filepaths"
}
]
"description": "Compare two files with each other"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

},
{
"name": [
Expand Down
12 changes: 1 addition & 11 deletions command-signatures/json/code.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,7 @@
"-d",
"--diff"
],
"description": "Compare two files with each other",
"args": [
{
"name": "file",
"template": "filepaths"
},
{
"name": "file",
"template": "filepaths"
}
]
"description": "Compare two files with each other"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

},
{
"name": [
Expand Down
103 changes: 20 additions & 83 deletions command-signatures/json/git.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6788,27 +6788,11 @@
"-m",
"--move"
],
"description": "Move/rename a branch and its reflog",
"args": [
{
"generatorName": "local_branches"
},
{
"generatorName": "local_branches"
}
]
"description": "Move/rename a branch and its reflog"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

},
{
"name": "-M",
"description": "Move/rename a branch, even if target exists",
"args": [
{
"generatorName": "local_branches"
},
{
"generatorName": "local_branches"
}
]
"description": "Move/rename a branch, even if target exists"
},
{
"name": [
Expand Down Expand Up @@ -6957,35 +6941,15 @@
"exclusiveOn": [
"--no-track"
],
"description": "When creating a new branch, set up 'upstream' configuration",
"args": [
{
"name": "branch",
"generatorName": "local_branches"
},
{
"name": "start point",
"isOptional": true,
"generatorName": "commits"
}
]
"description": "When creating a new branch, set up 'upstream' configuration"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

},
{
"name": "--no-track",
"exclusiveOn": [
"--track",
"-t"
],
"description": "Do not set up 'upstream' configuration, even if the branch.autoSetupMerge configuration variable is true",
"args": [
{
"generatorName": "local_branches"
},
{
"isOptional": true,
"generatorName": "local_branches"
}
]
"description": "Do not set up 'upstream' configuration, even if the branch.autoSetupMerge configuration variable is true"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>].

},
{
"name": [
Expand Down Expand Up @@ -7049,7 +7013,14 @@
"--color"
]
}
]
],

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the one addition in the PR, and it exists because git branch declared no positionals at all. Removing the option args above would otherwise have left git branch -m ⇥ offering nothing — turning a modelling fix into a completion regression, which is the trap the rest of this audit is trying to avoid.

branch-name is optional in every synopsis form (<branch-name> [<start-point>] when creating, [<old-branch>] <new-branch> with -m/-M/-c/-C, <branch-name>... with -d/-D, [<pattern>...] with --list), so it advertises no invalid bare invocation. It carries the same local_branches generator the removed args used, so what users actually see is unchanged.

"args": {
"name": "branch-name",
"description": "Branch operand(s): <branch-name> [<start-point>] when creating, [<old-branch>] <new-branch> with -m/-M/-c/-C, <branch-name>... with -d/-D, or [<pattern>...] with --list",
"isOptional": true,
"isVariadic": true,
"generatorName": "local_branches"
}
},
{
"name": "checkout",
Expand Down Expand Up @@ -8336,33 +8307,19 @@
"--create"
],
"description": "Create a new branch named <new-branch> starting at <start-point> before switching to the branch",
"args": [
{
"name": "new branch"
},
{
"name": "start point",
"isOptional": true,
"generatorName": "commits"
}
]
"args": {

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git switch -h: -c, --[no-]create <branch> — exactly one value, the new branch name. The start point is an operand of switch, per git switch [<options>] (-c|-C) <new-branch> [<start-point>], and switch already declares it as its own second positional, so unlike git branch nothing needed adding here.

One knock-on worth knowing: that operand position now resolves to switch's first positional (local_branches + refs_remote_branches) rather than the commits generator. Branches are valid start points, so this is a narrower suggestion set, not a broken one; widening switch's first positional to include commits would pollute plain git switch <branch>, where a bare commit is rejected.

"name": "new branch"
}
},
{
"name": [
"-C",
"--force-create"
],
"description": "Similar to --create except that if <new-branch> already exists it will be reset to <start-point>",
"args": [
{
"name": "new branch"
},
{
"name": "start point",
"isOptional": true,
"generatorName": "commits"
}
]
"args": {

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git switch -h: -C, --[no-]force-create <branch> — one value, same synopsis line and same reasoning as -c above.

"name": "new branch"
}
},
{
"name": [
Expand Down Expand Up @@ -8435,35 +8392,15 @@
"exclusiveOn": [
"--no-track"
],
"description": "When creating a new branch, set up 'upstream' configuration",
"args": [
{
"name": "branch",
"generatorName": "local_branches"
},
{
"name": "start point",
"isOptional": true,
"generatorName": "commits"
}
]
"description": "When creating a new branch, set up 'upstream' configuration"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git switch -h: -t, --[no-]track[=(direct|inherit)] — identical to the git branch copy earlier in this file, including the attached-only constraint that is why it stays a bare flag.

},
{
"name": "--no-track",
"exclusiveOn": [
"--track",
"-t"
],
"description": "Do not set up 'upstream' configuration, even if the branch.autoSetupMerge configuration variable is true",
"args": [
{
"generatorName": "local_branches"
},
{
"isOptional": true,
"generatorName": "local_branches"
}
]
"description": "Do not set up 'upstream' configuration, even if the branch.autoSetupMerge configuration variable is true"

@warp-agent-staging warp-agent-staging Bot Aug 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git-switch(1) documents --no-track with no value: "Do not set up 'upstream' configuration, even if the branch.autoSetupMerge configuration variable is true." Its two args duplicated switch's own [branch name, start point] positionals, which still serve those operands.

},
{
"name": "--orphan",
Expand Down
Loading
Loading