Commits, Branches and Pull Requests

Version control is how the team reads, reviews and undoes your work. A good change is a branch of small commits, each of which builds and says why it exists, and a pull request that a reviewer can understand in two minutes. The hard rules: you never lose anyone's work, you never rewrite history others have pulled without permission, and you never push secrets.

When to use

• "Commit this", "push it", "open a PR", "update the PR", "rebase on main", "clean up the branch".
• Finishing any coding task where the owner's workflow includes commits or pull requests.
• Undoing a mistake in git (wrong file committed, wrong branch, bad merge).

What you need

• Push access: the owner's GitHub or GitLab connected app (Connections page), the gh or glab CLI authenticated on your computer, or an SSH key the owner set up. If none is there, ask with clarify; you can still commit locally and hand over a patch (git format-patch origin/main).
• The commit identity the owner wants (their name, or a bot or agent identity). Check memory; if unknown, ask once and save it. Never commit as another person without consent.
• The owner's rules on pushing and merging (may you push branches? open PRs? merge after approval?), saved in memory.

Method

1. Learn the house conventions. Read CONTRIBUTING and the PR template (.github/pull_request_template.md, .gitlab/merge_request_templates/). Look at recent history for the style:

   git log --oneline -20 origin/HEAD
   git symbolic-ref refs/remotes/origin/HEAD          # the default branch
   

   Note the commit style (Conventional Commits like feat(api): ..., ticket prefixes like ABC-123: ..., or plain sentences), branch naming, and merge strategy (squash, merge commits, rebase).

2. Set identity and check state.

   git config user.name; git config user.email        # set per repo if needed: git config user.email "..."
   git status --short
   

   Uncommitted changes you did not make: stop and ask before stashing, committing or discarding them.

3. Branch from an up-to-date base.

   git fetch origin
   git switch -c fix/refund-cap origin/main
   

   Name branches <type>/<short-description> unless the repo uses something else (for example ABC-123-refund-cap).

4. Stage deliberately. Look before you add:

   git status --short && git diff
   git add src/billing/refund.py tests/test_refund.py   # explicit paths, or: git add -p
   git diff --cached --stat
   

   Never git add -A or git add . without reading git status first. Keep out: .env and any credentials, keys, tokens, large binaries, build output, editor files, debug scripts, files from other tasks. If a secret is about to be committed, unstage it and add it to .gitignore. If a secret was already pushed, tell the owner at once: it must be rotated, and removing it from history needs their go-ahead.

5. Write the commit message.

   fix(billing): cap partial refunds at the captured amount
   
   A second partial refund could exceed the original payment because the
   check compared against the order total, not captured minus refunded.
   Compute the remaining refundable amount from the payment record.
   
   Tested: pytest tests/test_refund.py (new test fails without the fix).
   Refs: #482
   

   • Subject: imperative mood ("Fix", not "Fixed"), about 50 characters, at most 72, no trailing full stop, prefixed the way the repo does it.
   • Body, wrapped at 72: why the change was needed, what approach you took and anything surprising. The diff already shows what changed line by line.
   • Footer: issue references (Fixes #482 closes it on merge where supported), BREAKING CHANGE: notes, co-author lines if the repo uses them.

6. One logical change per commit, each one green. Separate refactors from behaviour changes, and formatting from both. Each commit should build and pass tests on its own, so git bisect and git revert work later. Several commits for one task are fine; one commit for several unrelated tasks is not.

7. Bring in upstream changes safely.

   • Your branch, not yet pushed or used only by you: git fetch origin && git rebase origin/main.
   • A branch others have pulled or that is under review: git merge origin/main (no history rewrite), unless the owner prefers rebasing.
   • Conflicts: open each conflicted file with read_file, understand what both sides intended (git log --oneline origin/main -- <file>), combine them, remove every conflict marker, then run the tests. Lost: git rebase --abort or git merge --abort returns you to where you started.

8. Push.

   git push -u origin HEAD
   

   Rejected because the remote moved: fetch and integrate (step 7), then push again. Do not force. If history must be rewritten on a pushed branch (the owner asked you to squash or rebase), use git push --force-with-lease and only with their go-ahead; never on main, master, release branches or anyone else's branch.

9. Open the pull request. Small and focused: under about 400 changed lines of logic is a good target; split bigger work into stacked or sequential PRs. Use the repo's template or references/pr-and-commit-templates.md:

   gh pr create --base main --title "fix(billing): cap partial refunds at the captured amount" --body-file pr.md
   gh pr create --draft ...                     # when not ready for review
   glab mr create --target-branch main --title "..." --description "$(cat pr.md)"
   

   The description says what and why, how you tested it (commands and results), risks and how to roll back, screenshots for UI changes, and links the issue. Request reviewers per CODEOWNERS or the owner's instruction.

10. Watch CI and keep it green. gh pr checks --watch (or glab ci status). If a check fails, read the failing job's log, fix the cause in a new commit, push, and watch again. Do not re-request review while red.

11. Merging. Merge only if the owner's rules allow it, the required reviews are in and CI is green; use the repo's strategy (gh pr merge --squash --delete-branch, or as configured). Delete only branches you created; ask before deleting anyone else's.

12. Undo safely. Common fixes are in references/pr-and-commit-templates.md (undo table). Prefer moves that keep history (git revert) on anything pushed. git reflog can recover almost any local "lost" commit; check it before declaring work gone.

Always ask before

Force-pushing; git reset --hard or git checkout -- . / git restore . when there are uncommitted changes; git clean -fdx; deleting branches or tags; rewriting pushed history; pushing to or merging into main or release branches directly; changing branch protection or repository settings; removing anything from history.

Output

The pushed branch and pull request link, with a short note: commits made (subject lines), checks run locally and their results, CI status, reviewers requested, and anything you need from the owner (approval to merge, a decision).

Checks before you finish

• git status is clean; every intended file is committed and nothing else.
• No secrets or large binaries in the diff (git diff origin/main...HEAD --stat and a scan of added lines).
• Each commit message has an imperative subject and a body explaining why where needed.
• Tests, lint and type checks pass on the final commit; CI is green or its failures are understood and reported.
• No force-push, branch deletion or history rewrite happened without the owner's go-ahead.

Pitfalls

• git add -A habits. The fastest way to commit .env or a 200 MB dump.
• "WIP", "fix", "updates" messages. They make history useless. Say what and why.
• Mixing a refactor with a fix. The reviewer cannot tell which lines change behaviour.
• Rebasing a shared branch. Teammates' clones break and review comments lose their anchors.
• Force-push to make a rejection go away. A rejection means someone else pushed. Integrate their work.
• Resolving conflicts by picking one side wholesale. You silently delete someone's change. Read both sides.
• Giant PRs. Review quality drops sharply with size. Split.