refactor-command-to-commandlineresult

Refactor Command to CommandLineResult

Migrate a command that still performs parsing or custom execution logic to the Git::Commands::Base pattern, so command classes return raw Git::CommandLineResult and parsing moves to facade/parser layers.

Contents

• How to use this skill
• Prerequisites
• Related skills
• Target end state
• Refactor steps
• What to remove from command classes
• What to update in tests
• YARD updates
• Migration process and internal compatibility

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the command class or source file to migrate. Examples:

Using the Refactor Command to CommandLineResult skill, migrate
Git::Commands::Stash::Pop to the Base pattern.

Refactor Command to CommandLineResult: lib/git/commands/branch/delete.rb

The invocation needs the command class name or file path of the command to refactor.

Prerequisites

Before starting, you MUST load the following skill(s) in their entirety:

• YARD Documentation — authoritative source for YARD formatting rules and writing standards;

Related skills

• Command Implementation — canonical class-shape checklist, phased rollout gates, and internal compatibility contracts
• Review Arguments DSL — verifying DSL entries match git CLI
• Command Test Conventions — unit/integration test conventions for command classes
• Facade Implementation — preserving Git::Repository::* return-value contracts

Target end state

class SomeCommand < Git::Commands::Base
  arguments do
    ...
  end

  # optional for non-zero successful exits
  # rationale comment
  # allow_exit_status 0..1

  # @!method call(*, **)
  #
  #   @overload call(**options)
  #
  #     Execute the git ... command.
  #
  #     @return [Git::CommandLineResult]
end

Refactor steps

1. Move parsing/transforming logic out of command class into caller/facade/parser.
2. Replace legacy ARGS constant + custom initialize with arguments do + inheritance from Base.
3. Remove custom #call body and add # @!method call(*, **) YARD directive.
4. If command requires non-default success exits, add allow_exit_status with rationale comment.
5. Update callers to consume CommandLineResult and parse result.stdout where needed.

What to remove from command classes

• parser invocations
• output transformation logic
• literal entries for policy/output-control flags (e.g. literal '--no-edit', literal '--verbose', literal '--no-progress', literal '--no-color') — command classes are neutral, faithful representations of the git CLI; convert to flag_option / value_option so the facade can pass the policy value. See "Command-layer neutrality" in CONTRIBUTING.md.
• manual raise_on_failure / manual exit-code checks (unless temporarily needed in an unmigrated class)
• duplicated bind/execute logic

What to update in tests

• unit specs should assert CLI args and CommandLineResult behavior
• remove parsed-object assertions from command unit specs
• move parsing expectations to parser/facade tests
• include raise_on_failure: false in mocked command expectations

YARD updates

• update @return to Git::CommandLineResult
• keep command-specific @overload docs nested under # @!method call(*, **) directive
• ensure @raise wording reflects allowed range behavior
• tag short descriptions must not end with punctuation (no trailing period, comma, or colon)
• multi-paragraph tag descriptions must have a blank comment line (#) between the short description and each continuation paragraph

Migration process and internal compatibility

See Command Implementation for the canonical phased rollout checklist and internal compatibility contract. In summary:

• always work on a feature branch — never commit or push directly to main; create a branch before starting (git checkout -b <feature-branch-name>) and open a pull request when the slice is ready
• perform refactor in phased slices (pilot/family)
• keep each slice independently revertible
• do not mix unrelated behavior changes with refactor-only changes
• pass slice gates: bundle exec rspec, bundle exec rake test, bundle exec rubocop, bundle exec rake yard