Extract Command from Git::Lib

Extract Command from Lib

Replace a direct #command call in Git::Lib with a call to a Git::Commands::* class. The git subcommand is determined by the first (or first few) arguments to the #command method call.

Contents

• How to use this skill
• Prerequisites
• Related skills
• Input
• Workflow
  • Branch setup
  • Step 1 — Identify the #command call
  • Step 2 — Plan the migration and get approval
  • Step 3 — Ensure adequate legacy tests
  • Step 4 — Ensure the Git::Commands::* class exists
  • Step 5 — Update Git::Lib to delegate to the command class
• Commit discipline
• Create a pull request
• Quality gates (run at every step)
• Common patterns
  • Simple delegation (stdout passthrough)
  • Delegation with post-processing
  • Delegation with parsed return value
  • Delegation with opts-hash key normalization
  • Delegation with option filtering (preventing API expansion)
• What stays in Git::Lib
• What moves to Git::Commands::*

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with a short message identifying the Git::Lib method or #command call to migrate. Examples:

Using the Extract Command from Lib skill, migrate Git::Lib#worktree_add —
it calls command('worktree', 'add', ...).

Extract Command from Lib: command('ls-tree', ...)

The invocation needs either the Git::Lib method name or the git subcommand string from the #command call (or both).

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

Run or reference these skills during the workflow:

• Command Implementation — generates and reviews Git::Commands::* classes, unit tests, integration tests, and YARD docs (used in Step 4 if the command class does not exist yet); also the 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
• Command YARD Documentation — documentation completeness for command classes
• Review Cross-Command Consistency — sibling consistency within a command family
• Review Backward Compatibility — preserving Git::Lib return-value contracts
• Extract Facade from Base/Lib — the follow-on extraction that moves the public method from Git::Base / Git::Lib into a Git::Repository::* facade method (Phase 4 deletes both Git::Base and Git::Lib)

Input

Required:

1. A Git::Lib method that contains one or more command(...) calls to replace
2. The git subcommand name (derived from the first arguments to #command)

Workflow

Branch setup

All work must be done on a feature branch. Never commit or push directly to main.

Before starting, create a new branch:

git checkout -b <feature-branch-name>

All commits in this workflow go on the feature branch. When work is complete, open a pull request — do not merge or push directly into main.

Step 1 — Identify the #command call

1. Locate the Git::Lib method that calls command(...).

2. Note:

   • the git subcommand (first argument(s) to #command)
   • the options/arguments passed after the subcommand
   • execution options (e.g., timeout:, out:, err:, env:)
   • the return value and any post-processing (.stdout, parsing, regex matching)

3. Document the method's current public contract: signature, return type, and return-value format (String, Array, Hash, Boolean, etc.)

4. Run linters and rubocop to confirm a clean baseline:

   bundle exec rubocop

   Fix any issues before continuing.

Step 2 — Plan the migration and get approval

Before writing or changing any code, present a migration plan and wait for explicit confirmation from the user. Do not proceed until they approve.

The plan must cover every #command call identified above. For each one, state:

Also state:

• Which (if any) new Git::Commands::* classes need to be created
• How optional or empty arguments will be handled (e.g., nil vs '' operands)
• Any return-value post-processing that stays in Git::Lib

Then ask:

Does this mapping look correct? Any changes before I start implementing?

Do not move to Step 3 until the user confirms the plan.

Step 3 — Ensure adequate legacy tests

Before making any changes, verify that tests/units/ has adequate tests for the Git::Lib method being migrated.

1. Search existing legacy tests for coverage of the method:

   grep -rn '<method_name>' tests/units/

2. If coverage is insufficient, add minimal new tests to the legacy test suite that exercise the method's current behavior. These tests ensure the refactor does not break backward compatibility.

   • Do not change existing tests.

   • Follow existing legacy test conventions (Test::Unit::TestCase, assert_command_line_eq, in_temp_dir, etc.).

   • Verify new tests pass:

     bundle exec bin/test <test-file-basename>

   • Run rubocop against the new test file:

     bundle exec rubocop tests/units/<test-file>

   • Fix any issues before continuing.

3. Commit the new legacy tests:

   git add tests/units/<test-file>
   git commit -m "refactor(test): add legacy tests for <method_name>"

Step 4 — Ensure the Git::Commands::* class exists

1. Search lib/git/commands/ for an existing command class that matches the git subcommand:

   find lib/git/commands -name '*.rb' | sort

   Also check the class contents to confirm the existing class covers the same subcommand variation (e.g., branch --show-current vs. branch --list).

2. If the command class already exists, skip to Step 5.

3. If the command class does not exist, scaffold it using the Command Implementation skill. This produces:

   • lib/git/commands/<command>.rb (or lib/git/commands/<family>/<action>.rb)
   • spec/unit/git/commands/<command>_spec.rb
   • spec/integration/git/commands/<command>_spec.rb

4. Verify the new command class:

   bundle exec rspec spec/unit/git/commands/<command>_spec.rb
   bundle exec rspec spec/integration/git/commands/<command>_spec.rb
   bundle exec rubocop lib/git/commands/<command>.rb
   bundle exec rake yard

   Fix any issues before continuing.

5. Commit the new command class and its tests:

   git add lib/git/commands/<command>*.rb spec/
   git commit -m "refactor(command): add Git::Commands::<Command> class"

Step 5 — Update Git::Lib to delegate to the command class

1. Replace the command(...) call with a call to the Git::Commands::* class:

   # Before
   def some_method(args)
     command('some-command', '--flag', args).stdout
   end
   
   # After
   def some_method(args)
     Git::Commands::SomeCommand.new(self).call(args, flag: true).stdout
   end

2. Preserve the method's exact return value contract — apply any parsing or transformation after .stdout / .stderr / .status to match the original return type.

3. Prevent API expansion — the command class may accept many more options than the legacy Git::Lib method ever exposed. Only forward the options that were part of the original Git::Lib method's public API. Use a <COMMAND>_ALLOWED_OPTS constant to whitelist permitted option keys, call assert_valid_opts to raise on unknown keys, then filter with opts.slice before forwarding:

   PULL_ALLOWED_OPTS = %i[allow_unrelated_histories].freeze
   
   def pull(remote = nil, branch = nil, opts = {})
     assert_valid_opts(opts, PULL_ALLOWED_OPTS)
     allowed_opts = opts.slice(*PULL_ALLOWED_OPTS)
     Git::Commands::Pull.new(self).call(remote, branch, **allowed_opts).stdout
   end

   assert_valid_opts raises ArgumentError for any unrecognised key, giving callers a clear error instead of silently ignoring unknown options. This ensures that callers cannot accidentally pass options that happen to match command DSL option names but were never part of the public contract.

4. Add the appropriate require_relative at the top of lib/git/lib.rb if not already present.

5. Verify:

   bundle exec bin/test <legacy-test-file-basename>
   bundle exec rspec
   bundle exec rubocop
   bundle exec rake yard

   Fix any issues before continuing.

6. Commit the Git::Lib change:

   git add lib/git/lib.rb
   git commit -m "refactor(lib): delegate <method_name> to Git::Commands::<Command>"