git 4.3.2 → 5.0.0.beta.1

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

@@ -0,0 +1,426 @@
+---
+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`
+- **Missing `@raise [ArgumentError]` when `**options` is in the overload signature** —
+  every `@overload` that includes `**options` requires
+  `@raise [ArgumentError] if unsupported options are provided`. The base `ArgsBuilder`
+  always raises this at bind time for unknown keys. 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 base
+      `ArgsBuilder` always raises this at bind time for unknown keys
+- [ ] `@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

@@ -0,0 +1,72 @@
+---
+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
+```