/git-workflow

name: git-workflow
description: Use for branching, committing, history repair, and release hygiene. Covers atomic commits, rebase versus merge, bisect, reflog recovery, and undoing mistakes safely. Trigger on "undo my last commit", "i messed up a rebase", "squash these commits", "find which commit broke this". Do not use for pipeline and deploy automation — see the ci-cd skill.
metadata:
  category: development
  version: 1.0.0
  tags: [git, version-control, rebase, bisect, workflow]

Git Workflow

Purpose

Keep history readable and recoverable. A good history is a debugging tool: it lets you bisect, revert, and explain. A bad one is a wall of "fix", "fix again", "wip".

When to Use

• Structuring commits before opening a pull request.
• Recovering from a bad rebase, reset, or force-push.
• Bisecting to find the commit that introduced a regression.
• Cleaning up a branch's history.
• Deciding a team branching strategy.

Capabilities

• Atomic commit construction, including interactive staging.
• History rewriting: interactive rebase, squash, fixup, autosquash.
• Recovery: reflog, `ORIG_HEAD`, `git restore`, cherry-pick.
• Bisection, including automated bisection with a test script.
• Conflict resolution and `rerere`.

Inputs

• The repository state and the branch's relationship to its base.
• Whether the branch has been pushed and whether others have based work on it.

Outputs

• A branch whose commits each build, pass tests, and do one thing.
• Commit messages that explain why, not what.
• A rebase or merge that preserves the ability to revert cleanly.

Workflow

1. **Commit atomically** — One logical change per commit. Use `git add -p` to split a messy working tree. 2. **Write the message for the future** — Subject in the imperative under 72 characters; body explaining why the change was needed. 3. **Clean before review** — `git rebase -i` to squash fixups and reorder. Reviewers should read the story, not the process. 4. **Rebase private branches, merge shared ones** — Rewriting history that others have pulled is how you lose their work. 5. **Recover with reflog** — Almost nothing is truly lost. `git reflog` shows every position HEAD has held.

Best Practices

• Never `git push --force` to a shared branch. Use `--force-with-lease`, which refuses if someone else has pushed.
• A commit that does not build is a commit that breaks bisect. Keep every commit green.
• `git commit --fixup <sha>` plus `git rebase -i --autosquash` makes review-response commits disappear cleanly.
• Do not commit generated files, secrets, or large binaries. Removing them later requires rewriting history for everyone.
• `git bisect run ./test.sh` finds the offending commit automatically. It is the fastest regression hunt available.
• Enable `rerere` — Git will remember how you resolved a conflict and reapply it next time.

Examples

**Automated bisection:**

git bisect start
git bisect bad HEAD             # current commit is broken
git bisect good v2.14.0         # this release was fine

# Any script exiting 0 for good, non-zero for bad.
git bisect run pytest tests/test_checkout.py::test_total

# Git prints the first bad commit, then:
git bisect reset

**Recovering a branch destroyed by a bad reset:**

git reflog                       # find the sha from before the reset
# 8a3f1c2 HEAD@{3}: commit: add proration handling
git reset --hard 8a3f1c2         # branch is back

**Splitting a messy working tree into reviewable commits:**

git add -p                       # stage hunks belonging to the first change
git commit -m "Extract proration calculator"
git add -p                       # stage the next logical change
git commit -m "Fix double-charge on mid-cycle upgrade"

Notes

• The reflog is local and expires (90 days by default). It will not save you from a force-push that only ever existed on someone else's machine.
• Merge commits make `git log --oneline` noisy but preserve the true topology. On a team that reviews by PR, squash-merging to main and keeping the branch history in the PR is a reasonable middle ground.
• If a secret is committed, rotating it is mandatory and rewriting history is optional. Assume it is compromised the moment it is pushed.