OpenParable
Skip to content
← Back to skills

Refactor Command To Commandlineresult

Development
refactor-command-to-commandlineresult

Refactor Command To Commandlineresult is an Agent Skill for development published in the ruby-git/ruby-git repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Migrates a command class that still performs parsing or custom execution logic to return raw Git::CommandLineResult, moving parsing to facade/parser layers. Use during architectural redesign refactoring.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/ruby-git/ruby-git/blob/HEAD/.github/skills/refactor-command-to-commandlineresult/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/refactor-command-to-commandlineresult, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

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

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