Refactor Command To Commandlineresult
Developmentrefactor-command-to-commandlineresultRefactor 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
- 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
- Move parsing/transforming logic out of command class into caller/facade/parser.
- Replace legacy
ARGSconstant + custominitializewitharguments do+ inheritance fromBase. - Remove custom
#callbody and add# @!method call(*, **)YARD directive. - If command requires non-default success exits, add
allow_exit_statuswith rationale comment. - Update callers to consume
CommandLineResultand parseresult.stdoutwhere needed.
What to remove from command classes
- parser invocations
- output transformation logic
literalentries 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 toflag_option/value_optionso 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
CommandLineResultbehavior - remove parsed-object assertions from command unit specs
- move parsing expectations to parser/facade tests
- include
raise_on_failure: falsein mocked command expectations
YARD updates
- update
@returntoGit::CommandLineResult - keep command-specific
@overloaddocs nested under# @!method call(*, **)directive - ensure
@raisewording 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