Project Context

Project Context

Reference for ruby-git's architecture, coding standards, design philosophy, and technical constraints. Load this skill when answering questions about code structure, where logic belongs, or how the layers interact.

Contents

• How to use this skill
• Related skills
• Architecture & Module Organization
• Layer Responsibilities
• Coding Standards
• Design Philosophy
• Key Technical Details
• Compatibility
• Performance
• Implementation Notes

How to use this skill

Attach this file to your Copilot Chat context when you need architecture guidance, coding standard details, or implementation constraints.

Related skills

• Development Workflow — TDD cycle and commit conventions for day-to-day work
• Command Implementation — generating and reviewing command classes in the layered architecture
• Facade Implementation — generating and reviewing Git::Repository::* facade methods, the gem's public API layer
• YARD Documentation — documentation standards

Architecture & Module Organization

Key modules and their roles:

Key directories:

• lib/git/ — Core library code
• lib/git/commands/ — Command classes (new architecture)
• lib/git/repository/ — Facade topic modules (Git::Repository::*)
• spec/unit/ — RSpec unit tests (mocked execution context)
• spec/integration/ — RSpec integration tests (real git repositories)
• spec/support/ — Shared test contexts and helpers
• archive/ — Frozen records of completed projects, such as archive/v5-redesign/. History, not current policy; current standards live in .github/skills/
• docs/adr/ — decision records (ADRs): why something was decided

Layer Responsibilities

The three-layer architecture separates concerns cleanly:

Git::Repository (facade — topic modules under lib/git/repository/)
  └── Git::Commands::* (defines CLI API, binds args, executes via execution_context)
        └── Git::ExecutionContext::* (configured subprocess runner: env, binary, global opts)
              └── Git::CommandLine (subprocess execution)

• Commands layer (Git::Commands::*): Owns the git CLI contract. Declares arguments via DSL, executes command, returns Git::CommandLine::Result. No parsing.
  • literal entries are only for operation selectors (subcommand names, mode flags like --delete that define what the class does). Output-format flags, parser-contract options, and other caller-controlled options belong as flag_option / value_option — not as literal entries.
  • Each command class represents one operation, not one output format. Output-mode flags (--patch, --numstat, --raw, --format=…) are options declared in the DSL; the facade chooses which to pass. Separate subclasses for the same operation with different output modes are an anti-pattern.
• Parser layer (Git::Parsers::*): Transforms raw stdout/stderr into structured Ruby data. No execution.
• Facade layer (Git::Repository::*): Pre-processes caller arguments, invokes the right command class, calls parsers, constructs rich response objects. Parser-contract options (e.g. no_color: true, pretty: 'raw', format: FORMAT_STRING) are passed explicitly at the facade call site — this makes the parser contract auditable by reading the topic module method. What a facade method leaves behind when it fails partway through is decided in ADR-0009: it leaves whatever the caller can use.

Git::Commands::Base provides default #initialize(execution_context) and #call. Command classes that need non-zero successful exits declare allow_exit_status <Range> with a rationale comment.

Command-layer neutrality

Command classes are neutral, faithful representations of the git CLI. They declare options via the DSL but never embed policy choices (output-control flags, editor suppression, progress, verbose mode). The facade (Git::Repository::*) sets safe defaults at each call site. Some defaults are fixed (not in ALLOWED_OPTS — rejected by assert_valid_opts! before reaching the command); others are overridable (in ALLOWED_OPTS, placed before the caller's **opts so the caller's value wins). The execution layer (GIT_EDITOR='true') is an unconditional safety net.

Anti-pattern: literal '--no-edit', literal '--verbose', literal '--no-progress' inside a command class.

Correct pattern: flag_option :edit, negatable: true in the command; no_edit: true passed from the facade call site.

Validation Boundaries

This section is the authority on what command classes validate and what they delegate to git. Skills that need the rule link here. Because multiple skills depend on this section by link, editing it changes their meaning without touching their files — after edits, rerun bundle exec rake markdown:links and audit the linking skills with the Reviewing Skills skill.

Command classes use per-argument validation parameters (required:, type:, allow_nil:, etc.) and operand format validation. They generally do not declare cross-argument constraint methods (conflicts, requires, requires_one_of, requires_exactly_one_of, forbid_values, allowed_values) — git is the single source of truth for its own option semantics, subject only to the two exceptions defined under Exception criteria for constraint declarations.

The constraint DSL infrastructure (conflicts, requires, requires_one_of, requires_exactly_one_of, forbid_values, allowed_values) remains available in Git::Commands::Arguments and is kept intact, but command classes reach for it only under the exception criteria below.

Exception criteria for constraint declarations

Two exceptions, each defined in its own subsection below, permit a constraint declaration: the argv-invisible exception and the silent-wrong-result exception. Skills that reference an individual exception link to it by these names and anchors.

The argv-invisible exception

The test: does this argument appear in git's argv?

• Yes (normal flag_option, value_option, etc.) — git can observe it and report the error, so do not declare a constraint.
• No — the argument is consumed entirely on the Ruby side and has no argv representation at all: skip_cli: true operands, execution_option entries, and anything else that never becomes a token git can see. Git has no mechanism to detect incompatibilities, so Ruby must enforce them with a constraint declaration.

This is about presence in argv, not about transformation. Every DSL entry transforms something — flag_option :force turns force: true into --force — and those still belong to the Yes branch, because --force reaches git and git can object to it.

The canonical case is skip_cli: true operands routed via stdin. cat-file --batch commands declare both conflicts :object, :batch_all_objects and requires_one_of :object, :batch_all_objects. :object is skip_cli: true, so it reaches git over stdin rather than in argv — git does receive the object names, but it has no argv token to reason about them with, and --batch-all-objects makes it discard stdin unread. Both failure modes are therefore silent:

Neither is an error git can report, so Ruby must enforce those constraints.

The distinction matters when reasoning about a new command: skip_cli: true means absent from argv, not invisible to git. A stdin-fed value git still reads is covered by this exception because git cannot correlate it with the argv flags, not because git never receives it.

Git::Commands::Archive is the other shape: it declares conflicts :output, :out because :out is an execution_option naming a Ruby IO object to stream into. Only --output reaches argv, so git cannot see that both were requested.

The silent-wrong-result exception

If a combination of git-visible arguments causes git to silently discard data or produce a wrong result (no error, wrong answer), a constraint declaration MAY be added with a code comment explaining why, a reference to the git version(s) where the behavior was verified, and a test.

A flag that is invalid in the selected mode is still not this exception, whether git rejects the combination loudly (delegation's normal case) or accepts the flag and silently ignores it (a no-op produces no wrong answer). Delegate both. Git::Commands::CatFile::Raw once declared requires_one_of :t, :s, when: :allow_unknown_type, duplicating a check git 2.28-2.49 performs itself and git 2.50 removed along with the unknown-type feature; the constraint was removed and the flag passed through until v6.0.0 removed the option — see the note in Command Implementation.

Why the semantic checks are delegated

The decision and its rationale are recorded in ADR-0003: duplicated rules go stale under git's moving semantics, partial coverage creates a false promise of safety, and a constraint violation is a programming error the developer must fix whichever exception reports it.

The operational consequence: every semantic rejection in the delegated table above surfaces the same way — Git::FailedError carrying git's actual message — rather than as a mix of Ruby constraint errors and git rejections. The per-argument checks in the first table still raise ArgumentError; the split is between "this call is malformed" and "git says no", not between two arbitrary error classes.

Coding Standards

Ruby Style

• frozen_string_literal: true at the top of every Ruby file
• Ruby 3.3.0+ idioms; keyword arguments for multi-parameter methods
• private keyword form (not private :method_name)
• Pattern matching for complex conditionals where appropriate