git 5.1.0 → 5.2.0

data/.github/skills/command-yard-documentation/SKILL.md

@@ -1,434 +0,0 @@
----
-name: command-yard-documentation
-description: "Command-specific YARD documentation rules for Git::Commands::Base subclasses, overriding and extending the general yard-documentation skill. Use when writing or reviewing YARD docs for command classes."
----
-
-# Command YARD Documentation
-
-Write and verify YARD documentation for command classes aligned with
-the `Git::Commands::Base` pattern. Use this skill when writing or reviewing
-YARD docs on command classes — it overrides and extends the general
-[YARD Documentation](../yard-documentation/SKILL.md) skill with
-command-specific rules.
-
-This skill verifies that YARD docs accurately mirror the `arguments do` block
-as-implemented. It does not re-adjudicate which options belong based on Git
-version — version gating is the domain of the DSL and the
-[Command Implementation](../command-implementation/SKILL.md) skill, not YARD review.
-
-## Contents
-
-- [Contents](#contents)
-- [Related skills](#related-skills)
-- [Input](#input)
-- [Reference](#reference)
-  - [Required documentation model](#required-documentation-model)
-    - [No `def call` override (simple commands)](#no-def-call-override-simple-commands)
-    - [Explicit `def call` override](#explicit-def-call-override)
-  - [DSL-to-YARD type mapping](#dsl-to-yard-type-mapping)
-  - [Common issues](#common-issues)
-- [Workflow](#workflow)
-  - [1. Class-level docs](#1-class-level-docs)
-  - [2. Arguments docs](#2-arguments-docs)
-  - [3. Return and raise tags](#3-return-and-raise-tags)
-  - [4. `allow_exit_status` rationale consistency](#4-allow_exit_status-rationale-consistency)
-  - [5. Formatting consistency](#5-formatting-consistency)
-  - [6. Avoid internal implementation detail leakage](#6-avoid-internal-implementation-detail-leakage)
-- [Output](#output)
-  - [When writing new YARD docs](#when-writing-new-yard-docs)
-  - [When reviewing existing YARD docs](#when-reviewing-existing-yard-docs)
-
-## Related skills
-
-- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative
-  source for general YARD formatting rules and writing standards
-- [Review Arguments DSL](../review-arguments-dsl/SKILL.md) — verifying DSL entries
-  match git CLI
-- [Command Implementation](../command-implementation/SKILL.md) — class
-  structure, phased rollout gates, and internal compatibility contracts
-- [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration
-  test conventions for command classes
-
-## Input
-
-Before starting, you **MUST** load the following skill(s) in their entirety:
-
-- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative
-  source for YARD formatting rules and writing standards
-
-Then gather the following for each command under review:
-
-1. **Command source** — one or more files from `lib/git/commands/` containing:
-   - `class < Git::Commands::Base`
-   - `arguments do ... end`
-   - optional `allow_exit_status`
-   - either a `# @!method call(*, **)` YARD directive (when no `def call` override)
-     or YARD doc comments directly above an explicit `def call` override
-
-2. **Git documentation for the git command**
-
-   - **Latest-version online command documentation**
-
-     Read the **entire** official git documentation online man page for the command
-     for the latest version of git. This version will be used as the primary
-     authority for verifying option names, aliases, descriptions, and ordering.
-     Fetch this version from the URL `https://git-scm.com/docs/git-{command}`
-     (this URL always serves the latest release).
-
-   - **Minimum-version online command documentation**
-
-     Read the **entire** official git documentation online man page for the command
-     for the `Git::MINIMUM_GIT_VERSION` version of git. This will be used to
-     confirm whether the command/class is gated by `requires_git_version` and,
-     when it is, that the YARD docs include a continuation paragraph noting the
-     minimum version requirement. Fetch this version from the URL
-     `https://git-scm.com/docs/git-{command}/{version}`.
-
-   Do **not** rely on local `git <command> -h` output — the installed Git version
-   is unknown and may differ from the minimum or latest supported version.
-
-## Reference
-
-### Required documentation model
-
-The placement of `call` documentation depends on whether the command class overrides
-`def call`.
-
-#### No `def call` override (simple commands)
-
-When the class does **not** define `def call`, use the `# @!method call(*, **)` YARD
-directive. This tells YARD to attach per-command docs to the inherited `call` method
-without a method definition in the subclass:
-
-```ruby
-# @!method call(*, **)
-#
-#   @overload call(**options)
-#
-#     Execute the git ... command.
-#
-#     @param options [Hash] command options
-#
-#     @option options [Boolean, nil] :force (nil) ...
-#
-#     @return [Git::CommandLineResult]
-```
-
-Note the placement rules:
-
-- The `@overload` description text **must appear inside the `@overload` block** (indented
-  one extra level, as in the template above). Do **not** place the description between
-  the `@!method` line and the `@overload` tag — that level belongs to any `@!method`-scope
-  prose that is not part of any overload, which is rarely needed.
-- Place the directive inside the class body, after the `arguments do` block (and after
-  `allow_exit_status` when present). Do **not** combine `@!method` with an explicit
-  `def call`.
-
-#### Explicit `def call` override
-
-When the class defines `def call` explicitly (for input validation, stdin feeding, or
-non-trivial option routing), place YARD docs **directly above** the `def call`
-method. Do **not** use `@!method` — YARD will read the normal doc comment on the real
-method:
-
-```ruby
-# @overload call(*revision_range, **options)
-#
-#   Execute the `git log` command.
-#
-#   @param revision_range [Array<String>] zero or more revision specifiers
-#
-#   @param options [Hash] command options
-#
-#   @option options [Boolean, nil] :all (nil) ...
-#
-#   @return [Git::CommandLineResult] the result of calling `git log`
-#
-#   @raise [ArgumentError] if conflicting options are given
-#
-#   @raise [Git::FailedError] if git exits with a non-zero exit status
-def call(*, **kwargs)
-  # custom logic …
-  super
-end
-```
-
-Using `@!method` when `def call` already exists causes YARD to generate duplicate or
-conflicting documentation for the method.
-
-### DSL-to-YARD type mapping
-
-| DSL method | YARD type |
-| --- | --- |
-| `flag_option` | `[Boolean, nil]` — default `(nil)` (flag not emitted by default; both `false` and `nil` suppress the flag) |
-| `flag_option ..., max_times: N` | `[Boolean, Integer, nil]` |
-| `flag_option ..., negatable: true` | registers two entries; document **two** `@option` tags: positive key `[Boolean, nil]` (`true` → `--flag`; default `(nil)` → nothing), negative key `[Boolean, nil]` (`true` → `--no-flag`; default `(nil)` → nothing) |
-| `flag_or_value_option` | `[Boolean, String, nil]` (or the specific value type with `nil` appended) |
-| `flag_or_value_option ..., negatable: true` | registers two entries; document **two** `@option` tags: positive key `[Boolean, String, nil]` (`true` → `--flag`; string → `--flag=value` with `inline: true`, or `--flag <value>` without; default `(nil)` → nothing), negative key `[Boolean, nil]` (`true` → `--no-flag`; default `(nil)` → nothing) |
-| `value_option` | `[String]` — `value_option` does not enforce types; it accepts any non-nil value and converts it to a string. Use `[String]` unless callers are expected to pass a narrower type, in which case widen the annotation to reflect reality (e.g. `[Integer, String]` for options documented as taking `<n>` lines/bytes). Never use a bare numeric type such as `[Integer]` alone — that misrepresents what the implementation accepts. |
-| `operand` (repeatable) | `[Array<String>]` |
-| `operand` (single) | `[String]` |
-
-### Common issues
-
-- Using `# @!method call(*, **)` when an explicit `def call` override exists — causes
-  YARD to generate duplicate or conflicting documentation; remove the `@!method`
-  directive and place the `@overload` docs directly above `def call`
-- Missing `# @!method call(*, **)` directive when there is no `def call` override
-  (loses child-specific docs in generated YARD)
-- `@option` docs out of sync with `arguments do`
-- **YARD tags inside the `arguments do` block** — placing a tag (`@see`, `@param`,
-  `@return`, etc.) in a comment above a DSL entry such as `flag_option :x` produces an
-  orphaned doc comment. The DSL call is not a documentable construct, so YARD silently
-  drops the comment and `Documentation/OrphanedDocComment` flags it. Document each
-  option in its `@option` tag (put URLs in continuation text) and use a class-level
-  `@see` for command-wide references. A plain-prose comment (no leading `@tag`) inside
-  the block is fine.
-- **Missing `@raise [ArgumentError]` when `**options` is in the overload signature** —
-  every `@overload` that includes `**options` requires
-  `@raise [ArgumentError] if unsupported options are provided`. The `Arguments` DSL
-  always raises this at bind time for unknown keys via `validate_unsupported_options!`.
-  For commands whose `arguments` block declares **no** options (only `operand` entries),
-  drop `**options` from the signature entirely — then no `@raise [ArgumentError]` is
-  needed.
-- **`**options` in `@overload` without `@param options [Hash]`** — whenever an
-  `@overload` signature includes `**options`, a corresponding `@param options [Hash]`
-  tag is required. For commands whose `arguments` block declares **no** options (only
-  `operand` entries), omit `**options` from the `@overload` signature entirely and
-  remove any `@raise [ArgumentError] if unsupported options are provided` tag.
-
-  ```ruby
-  # ❌ No options in DSL but **options appears in overload without @param
-  #   @overload call(name, **options)
-  #     @param name [String] the remote name to remove
-  #     @raise [ArgumentError] if unsupported options are provided
-
-  # ✅ Operand-only command: drop **options from the signature
-  #   @overload call(name)
-  #     @param name [String] the remote name to remove
-  ```
-- **Missing second `@option` tag for `negatable:` options** — when the DSL declares
-  `flag_option :foo, negatable: true` or `flag_or_value_option :foo, negatable: true`,
-  two separate `@option` entries are required: one for the positive key (`:foo`) and
-  one for the negative companion key (`:no_foo`). A single tag documents only half
-  the interface.
-
-  ```ruby
-  # ❌ Missing negative companion tag
-  # @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
-
-  # ✅ Both forms documented with separate tags
-  # @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
-  #
-  # @option options [Boolean, nil] :no_create_reflog (nil) suppress branch reflog
-  #   creation (`--no-create-reflog`)
-  ```
-- Missing/incorrect `@raise` guidance for `allow_exit_status`
-- **Overly specific `@raise [Git::FailedError]` description** — do not enumerate
-  specific failure causes (e.g., "if the branch doesn't exist", "if the target
-  already exists"). Git can fail for many reasons beyond any list (invalid ref name,
-  not a git repository, permission error, etc.). Use the generic range-based form:
-
-  ```ruby
-  # ❌ Overly specific — does not cover all failure cases
-  # @raise [Git::FailedError] if the branch doesn't exist or target exists (without force)
-
-  # ✅ Correct — generic, matches sibling commands, accurate for all failure causes
-  # @raise [Git::FailedError] if git exits with a non-zero exit status
-  ```
-
-  For commands with a non-default range (e.g. `allow_exit_status 0..1`):
-
-  ```ruby
-  # ✅ Correct for allow_exit_status 0..1
-  # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
-  ```
-- Legacy references to `ARGS` constant or command-specific `initialize`
-- **`@option` description references a short flag instead of the emitted long flag** —
-  `@option` prose must describe behavior using the emitted CLI form (the long flag),
-  not the git man-page synopsis short notation. The DSL emits the primary (long) flag
-  regardless of which alias the caller uses.
-
-  ```ruby
-  # ❌ Wrong — describes -v as if it is emitted
-  # @option options [Boolean, Integer, nil] :verbose (nil) ...
-  #   Pass `true` for `-v`; pass `2` for `-v -v`.
-
-  # ✅ Correct — describes the actually emitted flag
-  # @option options [Boolean, Integer, nil] :verbose (nil) ...
-  #   Pass `true` for `--verbose`; pass `2` for `--verbose --verbose`.
-  ```
-
-- Description leaks internal mechanics (e.g., "written via IO pipe") instead of
-  describing caller-facing behavior
-- **Uppercase first letter or trailing period on tag short descriptions** — the
-  summary text of every `@option`, `@param`, `@return`, and `@raise` tag must start
-  with a **lowercase** letter and must not end with punctuation (`.`, `,`, `;`, `:`).
-  Git man pages start descriptions with uppercase and end them with periods; both
-  mistakes are easy to copy verbatim. Run `bundle exec rake yard` to catch trailing
-  periods — YARD treats any failure as fatal. Correct form:
-
-  ```ruby
-  # ❌ Copied verbatim from the git man page
-  # @option options [Boolean, nil] :force (nil) Allow renaming even if target already exists.
-
-  # ✅ Correct — lowercase start, no trailing period
-  # @option options [Boolean, nil] :force (nil) allow renaming even if target already exists
-  ```
-- **Raw blank line inside a doc comment block** — a raw blank line (an empty line
-  with no leading `#`) silently terminates the YARD block. Any comment lines after
-  the raw blank line are dropped from generated docs. Replace every raw blank line
-  inside a block with a blank comment line (`#`). This is easy to miss in
-  continuation paragraphs and alias notes. Correct form:
-
-  ```ruby
-  # @option options [Boolean, nil] :ipv4 (nil) use IPv4 addresses only
-  #
-  #   Alias: :"4"
-  ```
-
-- **Multi-sentence short description without a blank comment line** — when an
-  `@option` needs more than one sentence, the first sentence is the short description
-  and all additional detail must go in a continuation paragraph separated by a blank
-  `#` line. Writing both sentences on the same run-in line violates YARD's
-  short-description rule. Correct form:
-
-  ```ruby
-  # @option options [Boolean, nil] :update_head_ok (nil) allow updating HEAD ref
-  #
-  #   When true, passes --update-head-ok. By default git fetch refuses to update HEAD.
-  ```
-
-## Workflow
-
-For each command file, run through these checks in order:
-
-### 1. Class-level docs
-
-- [ ] one-line summary
-- [ ] brief behavior description
-- [ ] `@example` blocks with representative usage
-- [ ] ``@note `arguments` block audited against https://git-scm.com/docs/git-{command}/<version>`` —
-      present and recording the latest git version at the time of the last DSL audit.
-      Flag as an error if missing or if the version in the URL does not match the
-      current latest git version (run `bin/latest-git-version` from the repo root to
-      check; a stale version means the DSL may be missing options added in later releases)
-- [ ] `@see` to parent command module where applicable
-- [ ] `@see` to the full documentation URL (e.g., `@see https://git-scm.com/docs/git-show-ref`)
-- [ ] `@api private`
-
-### 2. Arguments docs
-
-- [ ] `@overload` blocks cover valid call shapes
-- [ ] every positional arg has `@param`
-- [ ] every applicable option has `@option`
-- [ ] `@option` entries appear in the same order as the corresponding entries in the
-      `arguments do` block
-- [ ] `@option` types match the DSL method (see
-      [DSL-to-YARD type mapping](#dsl-to-yard-type-mapping))
-- [ ] `@option` defaults match the DSL method — `flag_option` (plain or negatable)
-      always uses `(nil)` for both the positive and negative `no_` companion tag;
-      `value_option` uses `(nil)`. Check every `@option` default tag against the DSL entry.
-      For `negatable:` options, verify that **two** `@option` tags are present (one
-      for the positive key, one for the `no_` companion key) and that both use `(nil)`.
-- [ ] option defaults/types are consistent with DSL definitions
-- [ ] `@option` descriptions for options that have an `allowed_values` declaration
-      enumerate the accepted values in the description text, e.g.: `@option options
-      [String] :cleanup (nil) Cleanup mode — one of verbatim, whitespace, or
-      strip`
-
-### 3. Return and raise tags
-
-- [ ] `@return [Git::CommandLineResult]` with wording: "the result of calling `git
-      <subcommand>`"
-- [ ] `@api public` is present at the end of the `@overload` block (after all `@raise`
-      tags) — every command class is `@api private` at the class level, but `call` is
-      the public contract and must be marked `@api public`
-- [ ] whenever the `@overload` signature includes `**options`, include
-      `@raise [ArgumentError] if unsupported options are provided` — the `Arguments`
-      DSL always raises this at bind time for unknown keys via `validate_unsupported_options!`
-- [ ] `@raise [Git::FailedError]` uses the canonical generic wording — **never**
-      enumerate specific failure causes; use the form that matches the command's
-      declared exit-status range:
-
-  | `allow_exit_status` | Canonical `@raise` wording |
-  | --- | --- |
-  | none declared (default `0..0`) | `if git exits with a non-zero exit status` |
-  | `allow_exit_status 0..1` | `if git exits outside the allowed range (exit code > 1)` |
-  | `allow_exit_status 0..N` | `if git exits outside the allowed range (exit code > N)` |
-
-### 4. `allow_exit_status` rationale consistency
-
-When command declares non-default exit range:
-
-- [ ] includes short rationale comment above declaration
-- [ ] YARD `@raise` text does not contradict accepted status behavior
-
-### 5. Formatting consistency
-
-- [ ] every YARD tag (`@param`, `@option`, `@return`, `@raise`, `@overload`,
-      `@see`, `@api`, etc.) is preceded by a blank comment line (`#`)
-- [ ] no raw blank lines (lines with no leading `#`) appear inside any doc block —
-      a raw blank line silently terminates the block and drops everything after it
-- [ ] tag short descriptions (the first sentence of each `@param`, `@option`,
-      `@return`, `@raise`, etc.) do not end with punctuation (no `.`, `,`, `;`, `:`)
-- [ ] multi-paragraph tag descriptions have a blank comment line (`#`) between the
-      short description and each continuation paragraph
-- [ ] `@option`, `@param`, `@return`, and `@raise` short descriptions all start with a
-      **lowercase** letter (e.g. `show the HEAD ref even when filtered`, `the path to the
-      repository`, `the result of calling \`git show-ref\``, `if git exits with a non-zero
-      status`)
-- [ ] consistent option wording and defaults across sibling commands
-- [ ] `max_times:` flags use `[Boolean, Integer]` type, not just `[Boolean]`, and
-      include a continuation paragraph explaining integer semantics (e.g. "When an
-      integer is given, the flag is repeated that many times")
-- [ ] no stale references to removed per-command implementation details
-- [ ] all other general formatting rules from [YARD
-  Documentation](../yard-documentation/SKILL.md) are satisfied
-
-### 6. Avoid internal implementation detail leakage
-
-Prefer interface-level wording (what callers can pass/expect), not internals.
-
-**Common example — stdin transport mechanism:**
-
-```ruby
-# Bad: leaks implementation detail (IO pipe, threading)
-# Object names are written to the process's stdin via an in-memory IO pipe;
-# this avoids spawning additional processes and works with the --batch protocol.
-
-# Good: describes caller-facing behavior
-# Object names are passed to the git process's stdin using the --batch protocol.
-```
-
-- [ ] description does not mention `IO.pipe`, threads, or pipe buffer management
-- [ ] description does not reference internal method names (`with_stdin`,
-  `run_batch`)
-- [ ] description describes what the caller passes and what they get back
-
-## Output
-
-### When writing new YARD docs
-
-Produce the complete YARD doc block(s) for the command class, then self-verify
-by running every checklist item from [Workflow](#workflow) against your output.
-If any issues are found, fix and re-verify until all checks pass.
-
-### When reviewing existing YARD docs
-
-For each file, provide:
-
-1. issue table
-
-   | Check | Status | Issue |
-   | --- | --- | --- |
-
-2. corrected doc block snippets (only where needed)
-
-3. **Self-verify before concluding** — after writing corrected snippets, re-run
-   every checklist item from [Workflow](#workflow) against your proposed
-   snippets. If any new issues are found, update the snippets and repeat until all
-   checks pass. Only then write the final issue table marking everything as passing.
-
-> **Branch workflow:** Implement any fixes on a feature branch. Never commit or push
-> directly to `main` — open a pull request when changes are ready to merge.

data/.github/skills/dependency-management/SKILL.md

@@ -1,72 +0,0 @@
----
-name: dependency-management
-description: "Updates gem dependencies, handles CVEs, and manages gemspec rules. Use when updating dependencies, checking for outdated gems, or fixing security vulnerabilities."
----
-
-# Dependency Management Workflow
-
-## Contents
-
-- [How to use this skill](#how-to-use-this-skill)
-- [Related skills](#related-skills)
-- [Project-Specific Rules](#project-specific-rules)
-- [Update Process](#update-process)
-- [Key Considerations](#key-considerations)
-- [Commit Guidelines](#commit-guidelines)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context, then invoke it with the specific
-dependency update or CVE remediation scope. Apply this workflow before changing
-version constraints so updates remain consistent with gem project rules.
-
-## Related skills
-
-- [CI/CD Troubleshooting](../ci-cd-troubleshooting/SKILL.md) — diagnose failures
-   introduced by dependency updates
-- [Development Workflow](../development-workflow/SKILL.md) — drive any required
-   code changes via TDD
-- [Release Management](../release-management/SKILL.md) — understand how
-   dependency changes flow into automated releases
-
-## Project-Specific Rules
-
-- **All dependencies go in `git.gemspec`** (both runtime and development) - enforced by Rubocop
-- **`Gemfile` should remain minimal/empty** - do not add dependencies here
-- **`Gemfile.lock` is NOT committed** - this is a gem/library project
-
-## Update Process
-
-1. **Assess:** Run `bundle outdated` and `bundle audit check --update` (if available)
-2. **Update:** Edit `git.gemspec` if constraints need changing, then run `bundle update`
-3. **Test:** Run `bundle exec rake default` - must pass on all supported Ruby versions (see CI matrix in `.github/workflows/` and minimum version in `git.gemspec`)
-4. **Commit:** Use conventional commit format:
-   - Security: `fix(deps): update <gem> to fix CVE-XXXX-XXXX`
-   - Regular: `chore(deps): update dependencies`
-   - Breaking: `chore(deps)!: update <gem>` with `BREAKING CHANGE:` footer
-
-## Key Considerations
-
-- Security vulnerabilities are highest priority - address immediately
-- For gem projects, version constraints in gemspec must be carefully chosen since users resolve dependencies independently
-- Breaking changes in dependencies may require code changes (use TDD workflow)
-- Test with both minimum supported versions and latest versions when possible
-- If tests fail, isolate by updating gems one at a time or use binary search
-
-## Commit Guidelines
-
-This project uses [Conventional Commits](https://www.conventionalcommits.org/). A
-commit hook enforces the format. See the "Commit message guidelines" section in
-`CONTRIBUTING.md` for the full format and allowed types.
-
-**Issue and PR references in the body:** Do not use `#<number>` in the commit
-body — write `issue 1000` not `issue #1000`. A commitlint parser flaw treats any
-line containing `#<number>` as a footer token, breaking the body/footer split. To
-close an issue/PR, use `Closes`/`Fixes`/`Resolves #<number>` in the footer. To
-merely mention one for context, omit the `#` and no footer line is needed.
-
-To validate a commit message file before committing:
-
-```bash
-npx commitlint --format @commitlint/format < commit_msg.txt
-```