Git Patterns

---
name: git-patterns
description: >
  Git workflow patterns covering Conventional Commits, interactive rebase,
  branch strategy, recovery with reflog, bisect, worktrees, and stash. Use
  whenever the project is a git repository (a `.git` directory present), OR
  the task involves a git operation - commit, branch, rebase, bisect, merge
  conflict, or recovering lost history - even if "git" is not mentioned by
  name.
---

# Git Patterns

Review checklist and the handful of git behaviors that are easy to get wrong. Command syntax is in the man pages; this file is what to flag and what to reach for.

## Conventional Commits

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

- `feat` bumps MINOR, `fix` bumps PATCH, everything else (`docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`) bumps nothing.
- Breaking change: `!` after the type/scope, or a `BREAKING CHANGE:` footer. Either maps to MAJOR.
- Match the project's existing style before assuming Conventional Commits - see `rules/workflow.md`.

---

## Reach for these

| Situation                                | Tool                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Commits lost after a bad rebase or reset | `git reflog` - every HEAD move is recorded; branch off `HEAD@{n}`        |
| Need each commit in a series to build    | `exec` lines in the `rebase -i` todo (`exec make test`)                  |
| Hunting the commit that broke something  | `git bisect run <cmd>` - automates the whole search; exit 0 = good       |
| Reviewing a branch mid-edit on another   | `git worktree add <dir> <branch>` - separate working tree, shared `.git` |
| Fixups for already-staged hunks          | `git absorb` (see `rules/tooling.md`) beats hand-written `rebase -i`     |
| A file is ignored and you cannot see why | `git check-ignore -v <path>` names the rule and its source line          |

---

## Anti-patterns

**failure: force-pushing to a shared branch**
`git push --force` on `main` or any branch other people are using rewrites history and destroys their local branches. Use `--force-with-lease --force-if-includes` if you must force-push to your own remote branch: the first fails if someone else pushed since your last fetch, the second also fails when a background fetch updated the ref without you seeing it.

**failure: committing secrets**
If a secret lands in git history, rotate it immediately regardless of whether you think the repo is private. `git rm` does not remove it from history; the secret is still in every clone.

**warning: merge commit spam on feature branches**
Merging `main` into a feature branch repeatedly to stay up to date produces a messy history. Prefer `git rebase main` on the feature branch to keep a linear history before merge.

**warning: squashing a merge commit into a feature commit**
Interactive rebase cannot squash across a merge commit. Resolve by rebasing onto `main` first to linearize history, then squash.

**warning: committing with `--no-verify`**
Skipping pre-commit hooks bypasses linting, type checks, and secret scanning. Only use if you understand exactly which hook is blocking you and why it is safe to skip in that moment.

**warning: `git reset --hard` as a routine undo**
It discards working tree changes with no reflog entry for them. `git reset --soft HEAD~1` keeps the changes staged and is the right default.

**info: no `.gitignore` for secrets patterns**
An `.env` or `*.key` file not listed in `.gitignore` will eventually be committed by accident. Add secret file patterns before any other work in a new repo.

---

## References

- https://www.conventionalcommits.org/en/v1.0.0/
- https://git-scm.com/docs/git-rebase
- https://git-scm.com/docs/git-reflog
- https://git-scm.com/docs/git-bisect
- https://git-scm.com/docs/git-worktree
- https://git-scm.com/docs/git-push
- https://git-scm.com/docs/git-switch

## Version notes

Checked: 2026-09-26 against https://git-scm.com, https://github.com/git/git/blob/master/Documentation/RelNotes/2.30.0.adoc and https://www.conventionalcommits.org/en/v1.0.0/

- git 2.55.0 (2026-06-29): no guidance change. `git switch` / `git restore` are the documented replacements for branch and file `checkout`; `checkout` still works.
- `--force-if-includes` (2.30+): pairs with `--force-with-lease` against the background-fetch gap; added to the force-push guidance 2026-09-12.
- Conventional Commits spec is 1.0.0; unchanged.