Git

---
name: git
description: >
  Manage git commits, branches, conflicts, rebases, PRs/MRs, tags, releases, and GitHub/GitLab/Forgejo/Gitea workflows.
license: MIT
compatibility: "Requires git. Optional: gh (GitHub CLI), glab (GitLab CLI), fj (Forgejo CLI), git-filter-repo, git-cliff"
metadata:
  source: iuliandita/skills
  date_added: "2026-03-24"
  effort: high
  argument_hint: "[git-task-or-target]"
---

# Git: Multi-Forge Production Workflow

Perform git operations, manage branches, handle multi-remote setups, create PRs/MRs,
cut releases, and maintain audit-grade change history across GitHub, GitLab, and Forgejo.
The goal is clean, signed, traceable history that satisfies both engineering standards and
compliance requirements (PCI-DSS 4.0).

**Target versions** (October 2026):
- **git**: 2.56.0 (current stable, 2026-09-28). Additions include `git refs` create/delete/update/rename, `fetch.followRemoteHEAD`, and `git history drop`; 2.55 added Linux fsmonitor, remote-group push, and parallel compatible hooks.
- **GitHub CLI (`gh`)**: 2.102.0
- **GitLab CLI (`glab`)**: 1.120.0
- **Forgejo CLI (`fj`)**: 0.6.0 (latest Codeberg release, rechecked 2026-10-02; `fj pr merge --help` confirmed September 25; source `codeberg.org/forgejo-contrib/forgejo-cli`). Rust-written, official community CLI. Covers PRs (incl. AGit), issues, repos, releases, tags, actions.
- **Forgejo**: v16.0.5 current; v15.0.9 is the current LTS (both 2026-09-17). Critical RCE (CVE-2025-68937) patched in v13.0.2+.
- **prek**: 0.5.4 (Rust, recommended) or **pre-commit**: 4.6.2 (Python, largest ecosystem)
- **git-filter-repo**: 2.47.0
- **gitleaks**: 8.30.1 (secret scanning)
- **cosign**: 3.1.3 (Sigstore, for tag/release signing context)

This skill covers five domains depending on context:
- **Operations** - commits, branches, merges, rebases, stashing, bisect, reflog, recovery
- **Remotes & forges** - multi-remote setups, GitHub/GitLab/Forgejo differences, mirroring
- **PR/MR workflow** - feature branches, review flow, merge strategies, release cutting
- **Security** - commit signing, credential management, hooks, secret scanning, history scrubbing
- **Compliance** - PCI-DSS 4.0 change management, audit trails, branch protection as controls

## When to use

- Creating commits (message style, signing, authorship)
- Managing branches (creation, cleanup, protection, naming)
- Working with remotes (push, pull, fetch, multi-remote sync)
- Creating PRs/MRs (title, description, review process, merge strategy)
- Cutting releases (tagging, changelog, GitHub/Forgejo releases)
- Resolving merge conflicts or rebasing
- Recovering from mistakes (reflog, reset, revert, cherry-pick, bisect)
- Configuring git (aliases, hooks, attributes, credentials, signing)
- Scrubbing sensitive data from history (filter-repo)
- Setting up branch protection rules or rulesets
- Multi-forge workflows (mirroring, token management, SSH keys)
- PCI-DSS change management evidence

## When NOT to use

- CI/CD pipeline design - use **ci-cd**; this skill handles git operations *within* pipelines, not pipeline architecture
- PR/MR code review - use **code-review**; this skill creates PRs, doesn't review code in them
- Full application security audit - use **security-audit**; this skill covers secrets *in git history* and git-specific security, not application-level vulnerability assessment
- Docker image tagging strategy - use **docker**; this skill handles git tags, not container tags
- Post-session or post-merge documentation sweeps (README, changelog, runbooks) - use **update-docs**

---

## AI Self-Check

AI tools consistently produce the same git mistakes. **Before performing any git operation,
verify against this list:**

- [ ] **Read before rewrite.** Never `Edit`/`Write` files without `Read`ing them first. Never `git commit` without checking `git status` + `git diff`.
- [ ] **No destructive ops without confirmation.** `reset --hard`, `push --force`, `branch -D`, `clean -fd`, `checkout .`, and `rebase` on shared branches all require explicit user approval. Propose safer alternatives first (`--force-with-lease`, `revert`, new branch, `stash`).
- [ ] **Authorship correct.** Check the project's instruction file for author overrides. Many setups have a local git config that's wrong for the remote (e.g., Forgejo identity vs GitHub identity).
- [ ] **Commit message format.** Follow the project's convention (check recent `git log`). Default: conventional commits (`type(scope): description`).
- [ ] **No secrets in commits.** Check `git diff --cached` for API keys, tokens, passwords, `.env` files, private keys before committing. If found, unstage immediately.
- [ ] **No AI attribution in commits.** Never add `Co-Authored-By` lines or any mention of AI tools in commits. No exceptions unless the project explicitly requires it.
- [ ] **Instruction-file policy respected.** Follow the repo's policy for `AGENTS.md` or other instruction files. Never commit local agent state directories like `.claude/`, and never mention local-only tooling files in commit messages.
- [ ] **No tool-specific paths in commits.** `.claude/`, `.cursor/`, `.superpowers/`, `.worktrees/`, `docs/local/`, `PLAN.md`, `SECURITY-AUDIT.md` are local artifacts. Verify `.gitignore` covers AI tooling artifacts BEFORE staging (.claude/, .cursor/, .codex/, PLAN.md)
- [ ] **Branch target correct.** Verify you're on the right branch before committing. Verify the PR/MR targets the right base branch.
- [ ] **Requester authorized for admin changes.** In shared chats, do not commit or push infrastructure, Kubernetes, secrets, firewall, or other admin changes from a participant who is not authorized to approve them. Stop and ask the authorized owner first.
- [ ] **Remote target correct.** Multi-remote setups exist. Check which remote(s) to push to. Some projects push to multiple remotes (e.g., Forgejo + GitHub).
- [ ] **Signing configured.** If the project requires signed commits, verify signing works before committing (`git log --show-signature -1`).
- [ ] **No `--no-verify`.** Never skip pre-commit hooks unless the user explicitly asks. Hooks exist for a reason - fix the underlying issue instead.
- [ ] **No interactive flags.** Never use `-i` (interactive) flags (`git rebase -i`, `git add -i`) in automated contexts - they require TTY input.
- [ ] **Tags pushed separately.** `git push` doesn't push tags by default. Always `git push --tags` or `git push origin <tag>` explicitly.
- [ ] **Feature branch up to date.** Before creating a PR/MR, rebase onto the latest base branch to avoid merge conflicts.
- [ ] **Lock files regenerated after conflict resolution.** After resolving conflicts in dependency files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`), re-run the package manager to regenerate the lock file. Never manually merge lock files. Then regenerate: `npm install`, `yarn install`, `go mod tidy`, or `cargo generate-lockfile`.
- [ ] **Force-push safety.** If force-push is needed, always use `--force-with-lease` (refuses if remote has unfetched commits). Plain `--force` requires explicit user approval and team coordination.
- [ ] **Version info dated.** When citing tool versions, include a date so readers know when to re-check. Stale version numbers cause silent breakage.
- [ ] **Forge-CLI subcommands verified.** Before scripting `fj`/`gh`/`glab`/`tea` commands in a runbook, hooks, or CI, confirm the subcommand and flags exist on the target version (`<cli> <cmd> --help`). These CLIs add, rename, and remove subcommands across minor versions; docs lag behind the binary.
- [ ] **Ref safety checked**: branch, remote, upstream, and worktree path are verified before history edits
- [ ] **Recovery path known**: reflog, backup branch, or bundle exists before destructive history operations
- [ ] Cross-cutting agent hygiene applied - see `references/agent-hygiene.md`

---

## Performance

- Use path-limited `git log`, `git diff`, and `git grep` before whole-history scans.
- Fetch only needed remotes/branches in large repos when full prune is unnecessary.
- Keep commits small enough for review and bisect, but not so small that they split one behavior across many commits.

---

## Workflow

### Step 1: Identify the forge and project context

| Signal | Forge |
|--------|-------|
| `.github/` directory, `gh` CLI | GitHub |
| `.gitlab-ci.yml`, `glab` CLI, user says "work" | GitLab |
| `.forgejo/` directory, user says "home" | Forgejo |
| Multiple remotes in `git remote -v` | Multi-forge |

Read the project's instruction file (`AGENTS.md` or equivalent) for:
- **Commit conventions** (message format, scope list, authorship overrides)
- **Branch strategy** (trunk-based, feature branches, release branches)
- **Remote setup** (which remotes exist, which to push to, SSH keys)
- **Release process** (version bump files, tag format, changelog)
- **Signing requirements** (GPG, SSH, or unsigned)
- **Content restrictions** (domains, tool names, paths that must not appear in git history)

### Step 2: Determine the operation

- **"Commit this" / "save my work"** -> Commit workflow (Step 3a)
- **"Create a PR/MR"** -> PR/MR workflow (Step 3b)
- **"Cut a release"** -> Release workflow (Step 3c)
- **"Fix this mess" / "undo" / "recover"** -> Recovery operations (Step 3d)
- **"Pull failed" / "branches diverged"** -> Diverged branch resolution (Step 3e)
- **"Pull/update all repos under a directory"** -> Bulk repo update workflow (Step 3f)
- **"Set up signing" / "configure git"** -> Configuration (references)
- **"Clean up history" / "scrub secrets"** -> History rewriting (references)
- **"Set up branch protection"** -> Protection rules (references)

### Step 3a: Commit workflow

Copy this checklist and track progress:
- [ ] Inspect state and diff
- [ ] Stage selected files only
- [ ] Review the staged diff (secrets, debug code, unrelated changes)
- [ ] Write the message in the project's convention
- [ ] Commit with required authorship and signing
- [ ] Verify authorship and signature before pushing

1. **Check state**: `git status` (never `-uall` on large repos) + `git diff` (staged and unstaged)
2. **Stage selectively**: `git add <specific files>` - never `git add -A` or `git add .` without reviewing what's included. Check for secrets, binaries, generated files, AI tooling artifacts.
3. **Check the diff**: `git diff --cached` - read what you're about to commit. Look for debug code, TODO comments, accidental changes to unrelated files. If anything does not belong, unstage it (`git restore --staged <file>`) and return to step 2.
4. **Write the message**: follow the project's convention. Default format:

```
type(scope): concise description

Optional body explaining *why*, not *what*.
```

Select `type` from: `feat`, `fix`, `docs`, `refactor`, `chore`, `ci`, `build`, `revert`.
Extended types (use if the project convention allows): `test`, `perf`, `security`.
**Always check the project's instruction file and recent `git log` first** - the project may have a
different type list or naming convention. Project instructions override these defaults.

**Scopes** are strongly recommended but not blindly enforced. A scope adds context that makes
`git log --oneline` scannable: `fix(auth): token expiry` vs `fix: token expiry`. Use the
component, module, or area name. Skip the scope only when the change is truly cross-cutting
or the project doesn't use scopes.

**Breaking changes**: append `!` after the type/scope: `feat(api)!: drop v1 endpoints`.
For detailed breakage notes, add `BREAKING CHANGE:` in the commit body footer.

Message guidelines:
- Imperative mood ("add feature", not "added feature" or "adds feature")
- First line under 72 characters
- Body wrapped at 72 characters
- Explain *why* the change was made, not *what* changed (the diff shows *what*)
- Reference issue/ticket numbers where applicable
- **Casual, human-sounding tone.** Like a competent human wrote it, not an AI.
  Good: `fix(caddy): self-healing volume permissions`, `feat(auth): add OIDC login`
  Bad: "fix stuff", "wip", "update files", "enhance the robustness of the authentication module"
- **Plain ASCII only.** No em-dashes, curly quotes, ligatures, or fancy punctuation in commit messages.
- **Never mention local instruction files or AI tooling** in commit messages or bodies.
  If you're updating local-only instruction files alongside code changes, don't include them in the commit.
- **Never add `Co-Authored-By` or AI attribution** lines. No `Signed-off-by: AI`. No mentions
  of specific AI tools in the commit metadata.

5. **Commit**: with any required authorship overrides and signing flags from project config.
6. **Verify**: `git log -1 --format="%h %s%n  Author: %an <%ae>%n  Committer: %cn <%ce>"` - check authorship is correct before pushing. If it is wrong and the commit is unpushed, fix the identity config, run `git commit --amend --reset-author --no-edit`, and repeat this step.

### Step 3b: PR/MR workflow

**First check**: does the project use feature branches? Read the project instruction file. Some projects
(especially solo projects) work directly on `main` by preference. The default here assumes
collaborative development with review. Adapt to the project's actual workflow.

Read `references/forge-workflows.md` for forge-specific PR/MR creation
patterns (GitHub `gh pr create`, GitLab `glab mr create`, Forgejo `fj pr create` or web UI/API).
Detect the forge CLI first (`command -v gh`, `glab`, or `fj`); if it is missing, use the install
table or the REST API fallback in that reference.

Select verification from the diff and repository policy. Opening a PR does not by itself
justify a full build, integration suite, or release pipeline. Run affected checks and
honor required merge gates; reuse passing results for the same revision and relevant inputs.
If CI does unnecessary work, use **ci-cd** to scope its triggers and jobs rather than
bypassing checks or repeatedly dispatching the full pipeline.

General flow:
1. **Create feature branch**: `git checkout -b type/short-description` (e.g., `feat/user-search`, `fix/auth-bypass`). Keep branch names lowercase, hyphenated, prefixed with type.
2. **Make changes**: commit early, commit often. Each commit should be a logical unit.
3. **Rebase onto base**: `git fetch origin && git rebase origin/main` (or whatever the base branch is). Resolve conflicts: look for `<<<<<<<`, `=======`, `>>>>>>>` markers, keep the correct content from both sides (often both additions belong), then `git add` and `git rebase --continue`. After resolving conflicts in dependency files (`package.json`, `Cargo.toml`, `go.mod`, etc.), re-run the package manager to regenerate the lock file. Never merge the base into the feature branch. For merge strategy guidance, see `references/forge-workflows.md`.

   **Dependency file conflicts** (`package.json`, `go.mod`, `pyproject.toml`): keep additions from both branches; when the same dependency has conflicting version pins, reconcile both branches' constraints and intent, then let the package manager resolve a compatible version and validate the affected behavior. Never hand-edit the lock file - always regenerate it by running the package manager (`npm install`, `go mod tidy`, `uv sync`, etc.) after resolving the manifest conflict. Do not use `--ours` or `--theirs` for dependency manifest conflicts - these silently drop one branch's additions.
4. **Push**: `git push -u origin feat/short-description`. Then verify the remote actually
   advanced: compare `git rev-parse HEAD` with the forge PR/MR head SHA (`gh pr view ...`,
   `glab mr view ...`, or forge API). Do not rely on a terse or aliased push wrapper alone.
   If upstream tracking is missing or odd, push the exact refspec explicitly and re-check the
   PR/MR head before claiming the update landed.
5. **Create PR/MR**: with a clear title (under 70 chars), body with summary + test plan.
6. **Review cycle**: address feedback with follow-up commits by default. Rebase and push with `--force-with-lease` only on a private feature branch after explicit user confirmation and a fresh fetch. Never rewrite a shared branch.
7. **Merge**: squash-merge for clean history (default), or rebase-merge if commit history is meaningful.
8. **Cleanup**: delete the remote branch after merge. `git branch -d feat/short-description` locally.

Branch naming convention:
- `feat/description` - new features
- `fix/description` - bug fixes
- `refactor/description` - code restructuring
- `chore/description` - maintenance, deps, config
- `docs/description` - documentation only
- `ci/description` - CI/CD changes
- `security/description` - security fixes (consider if this should be a private advisory instead)

### Step 3c: Release workflow

Read `references/forge-workflows.md` for forge-specific release creation.

**Versioning scheme**: semver `vMAJOR.MINOR.PATCH` with optional pre-release suffixes.

| Version | When | CI behavior |
|---------|------|-------------|
| `v0.12.0-alpha.1` | Start of new minor version, iterating on new features | Tag + release (marked pre-release). Image build optional per project. |
| `v0.12.0-alpha.2` | Continued iteration, not stable yet | Same as above. |
| `v0.12.0` | Features stable, ready for production | Full release: tag + release + image build + deploy. |
| `v0.12.1` | Patch fix on stable release | Full release. |

**Alpha workflow**:
- When starting work on a new minor version, tag `vX.Y.0-alpha.1`
- Increment the alpha number (`-alpha.2`, `-alpha.3`) as you iterate
- When stable, drop the `-alpha` suffix and release `vX.Y.0`
- Alpha tags still get GitHub/Forgejo releases (marked `--prerelease`) so CI can optionally build images
- The project instruction file defines whether alpha tags trigger image builds or not

Copy this checklist and track progress:
- [ ] Version files bumped
- [ ] Bump commit created
- [ ] Annotated tag created
- [ ] Commit and tag pushed to every release remote
- [ ] Forge release created
- [ ] Release pipeline confirmed running on the tag

General flow:
1. **Version bump**: update all version files (check the project instruction file for the list - every project is different).
2. **Commit**: `chore: bump version to X.Y.Z` (or `chore: bump version to X.Y.Z-alpha.N`)
3. **Tag**: `git tag -a vX.Y.Z -m "vX.Y.Z"` (annotated tags, not lightweight).
4. **Push**: push commits AND tags. `git push origin main && git push origin vX.Y.Z`. If multi-remote, push to all.
5. **Create release**: GitHub (`gh release create`), GitLab (`glab release create`), or Forgejo (API/web).
   For alpha/pre-release: `gh release create vX.Y.Z-alpha.N --prerelease --title "vX.Y.Z-alpha.N"`
6. **Verify**: check that CI/CD picked up the tag and started the release pipeline. If it did
   not, confirm the tag reached the remote (`git ls-remote --tags origin vX.Y.Z`) and matches
   the workflow's tag trigger, then return to step 4.

**Changelog generation**: default to the project's existing tool. With none, use
`gh release create --generate-notes` (PR titles since the last tag) on GitHub, or `git-cliff`
when the project keeps a committed `CHANGELOG.md`. The `!` marker and consistent scopes make
either output more useful.

### Step 3d: Recovery operations

Read `references/recovery-and-maintenance.md` for detailed recovery
procedures (reflog, bisect, rerere, filter-repo, etc.).

Git almost never loses data. Reflog retention is configurable: defaults are 90 days for reachable entries and 30 for unreachable entries; expiration and GC can remove recovery data.

Quick reference:
- **Undo last commit (keep changes)**: `git reset --soft HEAD~1`
- **Undo last commit (discard changes)**: `git reset --hard HEAD~1` - **DESTRUCTIVE, confirm first**
- **Revert a pushed commit**: `git revert <sha>` (creates a new commit, safe for shared branches)
- **Find lost commits**: `git reflog` - shows retained HEAD movements; do not assume a fixed recovery window
- **Find which commit broke something**: `git bisect start && git bisect bad && git bisect good <sha>`
- **Automated bisect with test script**: `git bisect start HEAD v1.0.0 && git bisect run bun test src/auth.test.ts` - runs the test at each bisect step automatically. Exit codes: 0 = good, 1-127 except 125 = bad, 125 = skip this commit, 128-255 = abort the bisect immediately. Ideal for CI integration: `git bisect run ./scripts/ci-check.sh`
- **Squash last N commits (no interactive rebase)**: `git reset --soft HEAD~N && git commit -m "feat: combined change"` - resets N commits but keeps all changes staged, then commits them as one. Safer than `git rebase -i` in automated contexts.
- **Recover deleted branch**: `git reflog`, find the SHA, `git checkout -b branch-name <sha>`
- **Scrub secrets from history**: check `command -v git-filter-repo >/dev/null || { echo "install git-filter-repo (pipx install git-filter-repo, or the distro package)" >&2; exit 1; }` and stop if it is missing, then set `GIT_FILTER_REPO_REPLACEMENTS` to a mode-0600 temporary replacement file populated from a secret manager or no-echo stdin, then run `: "${GIT_FILTER_REPO_REPLACEMENTS:?set a mode-0600 replacement file}"` followed by `git filter-repo --replace-text "$GIT_FILTER_REPO_REPLACEMENTS"`. Remove the temporary file normally after use. Never put the leaked value in argv, command text, or shell history. Then force-push ALL branches and tags, coordinated with the team. See references.

---

### Step 3e: Diverged branch resolution

When `git pull` fails with "divergent branches" or `git status` shows "have diverged":

1. **Understand the divergence**: `git log --oneline HEAD..origin/branch` (what remote has) and `git log --oneline origin/branch..HEAD` (what you have locally).
2. **Choose strategy based on context**:
   - **Your commits are the ones that matter** (common for solo work): `git pull --rebase origin branch` - replays your local commits on top of remote.
   - **Remote commits are the ones that matter** (someone force-pushed, or you want to discard local): `git reset --hard origin/branch` - **DESTRUCTIVE, confirm first**.
   - **Both sides have real work** (collaboration divergence): `git pull --rebase origin branch`, resolve conflicts at each step, `git rebase --continue`.
   - **You don't know yet**: inspect both histories and repository policy before selecting a strategy; do not run a configuration-dependent pull as a probe.
3. **After resolving**: verify with `git log --oneline -10` that history looks correct.
4. **Prevent recurrence**: if this was caused by force-push on a shared branch, set up branch protection. If caused by forgetting to pull before committing, consider `git config pull.rebase true` for rebase-on-pull default.

---

### Step 3f: Bulk repo update workflow

When asked to pull or update many repositories under a directory, keep the run sequential,
auditable, and conservative. Per repository, track:
- [ ] Branch, upstream, and dirty state recorded
- [ ] Fetched and fast-forwarded (or skipped with a reason)
- [ ] Stash, if any, re-applied and verified
- [ ] Ahead/behind and porcelain status checked

1. Discover only real repo roots first, usually direct children of the requested directory
   unless the user explicitly asks for a recursive scan. Avoid vendored repos, worktrees,
   dependency caches, and generated checkouts.
2. Process repos sequentially, not in parallel. This avoids hammering SSH remotes, rate
   limits, or firewall protections.
3. For each repo, record the branch, upstream, and dirty state before changing anything.
4. Run `git fetch --all --prune`, then `git pull --ff-only --recurse-submodules` only
   when an upstream exists. Do not create merge commits during bulk maintenance.
   When submodules are present, also run `git submodule update --init --recursive` after
   the pull - `--recurse-submodules` updates existing submodule checkouts but does not
   initialize new submodules added since the last pull.
5. If authorized to stash local changes, record the original index and worktree diffs,
   create a named stash, fast-forward, then use `git stash apply --index` with that stash's
   exact object id. Keep it until both content and the staged/unstaged split are verified.
6. If applying the index conflicts, preserve the stash and stop updating that repository.
   Resolve against the saved staged and unstaged patches deliberately; never blanket-unstage
   user work. Report the unresolved repository and continue independent repositories.
7. Verify every repo with `git rev-list --left-right --count HEAD...@{u}` and
   `git status --porcelain`. Report repos that remain dirty or have no upstream.

---

## Multi-Forge Patterns

Many projects use multiple git remotes (e.g., Forgejo for self-hosted CI + GitHub for public releases,
or GitLab at work + GitHub for open source mirrors).

- Keep `origin` as the primary development remote and name mirrors explicitly.
- Push to multiple remotes explicitly; do not make "push everywhere" the default.
- Use separate SSH keys per forge.
- Remember that CLI auth can be overridden by environment variables, especially `GITHUB_TOKEN`.

Detailed multi-forge workflows stay in `references/forge-workflows.md`.

---

## Commit Signing
- Sign commits because unsigned authorship is trivial to spoof.
- SSH signing is the default recommendation for most teams.
- GPG still matters where long-lived key lifecycles or policy require it.
- gitsign is attractive for low-management open-source flows, but it changes the trust model.

Detailed signing setup stays in `references/security-and-signing.md`.

---

## Security
- Keep credentials out of the repo, including `.env` files, keys, and embedded connection strings.
- Use secure credential helpers, not plaintext storage.
- Use hooks for secrets, lint, and branch protection, but treat untrusted hook configs as code execution surfaces.
- If a secret hit history, scrub it and rotate it. History rewriting does not undo the exposure.
- Keep `.gitignore` and `.gitattributes` intentional; AI tooling artifacts belong out of the repo by default.

Detailed security and signing guidance stays in `references/security-and-signing.md`.

---

## PCI-DSS 4.0 Change Evidence

For repositories in PCI scope, use protected branches, required review, linked test and security
checks, and retained or exported forge audit evidence for the organization's applicable software
change controls. Map each control to the current PCI DSS text with the assessor; Git configuration
alone does not prove training, environment separation, or the full change-management process.
Signed commits authenticate a signing key under the chosen trust model. They do not prove that the
signer completed security training or that the change was reviewed, tested, or authorized.

---

## Reference Files

- `references/forge-workflows.md` - GitHub, GitLab, and Forgejo-specific patterns for PRs/MRs,
  releases, branch protection, rulesets, CLI usage, and API calls
- `references/security-and-signing.md` - commit signing setup (SSH/GPG/gitsign), credential
  management, secret scanning, CVE reference, git security hardening
- `references/recovery-and-maintenance.md` - reflog, bisect, rerere, filter-repo, stash,
  worktree, submodule/subtree, large repo optimization, housekeeping

## Output Contract

See `references/output-contract.md` for the full contract.

- **Skill name:** GIT
- **Deliverable bucket:** `audits`
- **Mode:** conditional. When invoked to **analyze, review, audit, or improve** existing repo content, apply the reporting size and evidence rules in `references/output-contract.md` and write the deliverable to `docs/local/audits/git/<YYYY-MM-DD>-<slug>.md`. When invoked to **answer a question, teach a concept, build a new artifact, or generate content**, respond freely without the contract.
- **Severity scale:** `P0 | P1 | P2 | P3 | info` (see shared contract; only used in audit/review mode).

## Related Skills

- **ci-cd** - pipeline design that triggers on git events (push, PR, tag). This skill handles
  the git operations; ci-cd handles the pipeline that reacts to them.
- **security-audit** - application-level secret scanning and vulnerability assessment. This skill
  covers secrets *in git history* and git-specific security (signing, hooks, credentials).
- **code-review** - reviews code quality. This skill creates the PR/MR; code-review evaluates
  the code in it.
- **update-docs** - post-session documentation sweep. May update shared instruction files with new git gotchas
  discovered during a session.

## Rules

The AI Self-Check above holds the per-operation guards (confirmation for destructive ops,
authorship, selective staging, hooks, tags, force-push, admin authorization). These add:

- **Show the target set before cleanup.** Never run commands that delete branches, tags, or
  ignored files without listing what they will remove first.
- **Prefer revert over history rewrite on shared branches.** Rewrites need a force-push and
  break every other clone.
- **Feature branches for collaboration.** When others will review the work, use feature branches
  with PRs/MRs. Direct-to-main is acceptable for solo projects when the user explicitly prefers it.
- **Rebase workflow.** Rebase feature branches onto base, don't merge base into feature. Squash
  on merge for clean history unless the commit history is meaningful.
- **Annotated tags for releases.** `git tag -a vX.Y.Z -m "vX.Y.Z"`, not lightweight tags.
  Annotated tags carry metadata (tagger, date, message) and are what forges use for releases.
- **PCI-DSS evidence.** In regulated environments, git history IS the audit trail. Protect it:
  signed commits, branch protection, required reviews, no history rewriting on release branches.