Review Arguments Dsl

Review Arguments DSL

Verify that a command class's arguments do ... end definition accurately maps Ruby call arguments to git CLI arguments, in the correct order, with the correct DSL methods and modifiers.

Contents

• Contents
• Related skills
• Input
  • Command source code
  • Command test code
  • Git documentation for the git command
  • Policy authorities
• Reference
  • Architecture Context (Base Pattern)
  • DSL to CLI Mapping
• Workflow
• Output

Related skills

• Command Implementation — class structure, phased rollout gates, and internal compatibility contracts
• Command Test Conventions — unit/integration test conventions for command classes
• Command YARD Documentation — documentation completeness for command classes

Input

What the agent requires to run this skill and where to get it.

Command source code

Read the command class from lib/git/commands/{command}.rb or, for subcommands, lib/git/commands/{command}/{subcommand}.rb. For subcommands, also read the namespace module at lib/git/commands/{command}.rb which should list all sibling subcommands and provide the module-level documentation.

Command test code

Read unit tests matching spec/unit/git/commands/{command}/**/*_spec.rb. Use these as supplemental evidence when tracing the verification chain (Ruby call → bound argument → expected git CLI). Coverage completeness is assessed by the Command Test Conventions skill.

Git documentation for the git command

• Latest-version online command documentation

  Read the entire official git documentation online man page for the command for the latest version of git. This version will be used as the primary authority for DSL completeness, including the options to include in the DSL, argument names, aliases, ordering, etc. Fetch this version from the URL https://git-scm.com/docs/git-{command} (this URL always serves the latest release).

• Minimum-version online command documentation

  Read the entire official git documentation online man page for the command for the Git::MINIMUM_GIT_VERSION version of git. This serves two purposes: command-introduction and requires_git_version decisions, and option-surface reconciliation. Diff these docs against the latest-version docs; an option they describe that the latest-version docs no longer describe belongs in the DSL with a version-split comment (the review flags are in Option surface spans the supported git range), and before accepting that comment's when-and-how claims, confirm them against the versioned docs at intermediate releases, the git release notes, or the upstream source. What the endpoint diff can and cannot establish is defined in Options completeness. Fetch this version from URL https://git-scm.com/docs/git-{command}/{version}.

Do not scaffold from local git <command> -h output alone — the installed Git version is unknown and may differ from the latest supported version. Local help should NOT be used even as a supplemental check.

Policy authorities

Read Project Context — Validation Boundaries, including its exception criteria for constraint declarations, and Options completeness — consult the latest-version docs first. The review flags in CHECKLIST.md reference these policies by link; load both authorities now so the flags are applied with the criteria in context, not from memory.

Reference

Architecture Context (Base Pattern)

Command classes follow this structure:

• class < Git::Commands::Base
• class-level arguments do ... end
• optional class-level macros such as allow_exit_status <range> and requires_git_version <version>
• YARD documentation with @overload blocks containing @param, @option, @return, and @raise tags, in one of two forms:
  • when #call is overridden: standard YARD comments directly above def call
  • when #call is not overridden: a # @!method call(*, **) directive with nested standard YARD comments

The CLI argument mapping is still defined exclusively by the Arguments DSL. The Base class handles binding and execution.

DSL to CLI Mapping

<!--
Purpose: gives the agent the mental model for predicting CLI output from a
DSL definition — the mapping rules needed to execute the verification chain
(Ruby call → bound argument → expected git CLI).

CHECKLIST.md works in the reverse direction: given git man-page behavior,
which DSL method and modifiers to use.
-->

The Arguments DSL (arguments do ... end) declares how Ruby keyword and positional arguments map to git CLI flags, options, and operands. See CHECKLIST.md § Verify DSL method per option type for the full DSL method mapping table.

Key behaviors:

• Basic emit — flag_option :verbose → --verbose; value_option :message → --message <value>; operand :commit → bare <value> in positional slot.
• flag_or_value_option — hybrid: true → --flag; string → --flag value (or --flag=value with inline:); false/nil → nothing. Supports negatable:.
• key_value_option — accepts a Hash or Array of pairs; emits --flag key=value per pair. key_separator: overrides =; inline: joins as --flag=key=value.
• custom_option — block receives the raw value and returns CLI strings; String is appended, Array is concatenated, nil/empty emits nothing.
• nil / false suppression — for boolean-style options (flag_option, flag_or_value_option in boolean mode), false or nil suppresses emission. For value_option / inline_value options, false is treated as a value (stringified to "false") unless a type constraint rejects it. nil suppresses emission for all option types (including negatable options — false is absent, not --no-*).
• Output order matches definition order — bound arguments are emitted in the order entries appear in arguments do.
• Name-to-flag mapping — underscores become hyphens, single-char names map to -x, multi-char names map to --name. Case is preserved: :A → -A, :N → -N. Uppercase short flags do not require as:.
• as: override — emits a verbatim string instead of deriving the flag from the symbol name. See CHECKLIST.md § The as: escape hatch for when use is justified.
• Aliases — first alias is canonical and determines the generated flag; remaining aliases are accepted as caller-side synonyms. Long name first: %i[force f], not %i[f force].
• negatable: — registers two entries: the positive key and a no_ companion. Both follow standard boolean semantics: true emits the flag, false/nil omits it. Pass no_edit: true to emit --no-edit.
  • flag_option :edit, negatable: true → :edit [Boolean] and :no_edit [Boolean]
  • flag_or_value_option :track, negatable: true → :track [Boolean, String] (positive or value form) and :no_track [Boolean] (boolean only; the negated form never takes a value)
• inline: — value_option :format, inline: true emits --format=value as one token; without it, --format value as two tokens.
• max_times: — flag_option :force, max_times: 2 with force: 2 emits --force --force.
• repeatable: — accepts an array; emits the flag once per value (e.g., --include a --include b).
• as_operand: — value_option :pathspec, as_operand: true is passed as a keyword but emitted in the operand position after end_of_options.
• literal — always emits its string unconditionally; the caller has no control.
• execution_option — never emits anything to argv; forwarded as Ruby kwargs to the subprocess runner.
• skip_cli: on operands — operand ..., skip_cli: true binds and validates like any other operand and remains accessible on Bound, but is excluded from argv emission.
• end_of_options — signals end of options in the emitted argv; only operands may follow (though operands may also appear before it). Emits -- by default. Override with as: when the command uses a different token. See CHECKLIST.md § Choosing the as: token for the decision rule.
• Operand/option name collision — if a positional operand and a keyword option share the same name, the option keeps its name and the operand is renamed. For repeatable operands, prefer the plural form (:commit → :commits). See CHECKLIST.md § Operand naming for details.