Git Workflow

Breaking Changes

Append ! after the type/scope, and include a BREAKING CHANGE: footer:

feat(api)!: remove deprecated /v1/users endpoint

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

Branch Naming

<type>/<ticket-id>-<short-description>

• feat/PROJ-123-user-auth
• fix/PROJ-456-null-pointer-crash
• chore/PROJ-789-upgrade-dependencies

Never work directly on main or develop. Always branch.

PR Descriptions

Structure every PR description with:

1. Summary -- 1-3 sentences on what and why
2. Changes -- bulleted list of specific modifications
3. Testing -- how you verified correctness
4. Screenshots -- if UI changes are involved
5. Breaking changes -- if any, with migration steps

Keep the PR title under 70 characters. Use imperative mood ("Add feature" not "Added feature").

Merge Strategies

When to squash merge

• Feature branches with messy WIP commits
• Single-purpose branches where individual commits add no value
• Always squash into a well-written conventional commit message

When to rebase merge

• Clean commit history where each commit is atomic and meaningful
• When you want a linear history on the target branch

When to merge commit

• Long-lived branches where preserving the full history matters
• Release branches merging back to main

Anti-pattern: Never merge main into your feature branch. Rebase onto main instead:

git fetch origin
git rebase origin/main

Stashing

Use descriptive stash messages:

git stash push -m "WIP: auth middleware token refresh logic"

Prefer git stash push over git stash save (deprecated).

To stash only specific files:

git stash push -m "partial work" -- path/to/file.ts

List and apply by index or message:

git stash list
git stash apply stash@{2}
git stash pop  # apply + drop

Clean up old stashes regularly. Stashes are not a substitute for branches.

Bisect

Use bisect to find the commit that introduced a bug:

git bisect start
git bisect bad                 # current commit is broken
git bisect good <known-good>   # last known working commit
# Git checks out a middle commit. Test it, then:
git bisect good   # or
git bisect bad
# Repeat until Git identifies the culprit
git bisect reset  # return to original HEAD

Automate with a test script:

git bisect start HEAD v1.2.0
git bisect run ./test-script.sh

Reflog

The reflog is your safety net. It records every HEAD movement:

git reflog                          # see recent HEAD changes
git checkout HEAD@{3}               # go back 3 moves
git branch recovery-branch HEAD@{5} # recover lost commits

Reflog entries expire after 90 days (30 for unreachable commits). Do not rely on it as permanent storage.

Cherry-Pick

Apply a specific commit to the current branch:

git cherry-pick <commit-hash>
git cherry-pick -x <commit-hash>  # adds "cherry picked from" to message

For a range of commits:

git cherry-pick A..B   # excludes A, includes B
git cherry-pick A^..B  # includes both A and B

Anti-pattern: Do not cherry-pick as a routine workflow. It creates duplicate commits. Prefer merging or rebasing.

Interactive Rebase

Clean up history before opening a PR:

git rebase -i origin/main

Common operations in the interactive editor:

• pick -- keep commit as-is
• reword -- change commit message
• squash -- combine with previous commit, edit message
• fixup -- combine with previous commit, discard message
• drop -- remove commit entirely
• edit -- pause to amend the commit

Rule: Never rebase commits that have been pushed to a shared branch.

Git Hooks

pre-commit

• Run linters (eslint, ruff, golangci-lint)
• Run formatters (prettier, black, gofmt)
• Check for secrets (use detect-secrets or gitleaks)
• Validate commit message format
• Use lint-staged to only check staged files

pre-push

• Run the full test suite
• Check for TODO or FIXME markers that should be resolved
• Verify the branch name follows conventions

commit-msg

• Validate conventional commit format
• Check for ticket ID in the message or branch name

Hook management

Use husky (Node.js) or pre-commit (Python) to manage hooks in version control. Never rely on manually installed local hooks.

// package.json (husky)
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Anti-Patterns

• Force pushing to shared branches -- only force-push to your own feature branches
• Giant commits -- each commit should represent one logical change
• Vague messages -- "fix stuff", "updates", "WIP" are not acceptable in the final history
• Committing generated files -- add build outputs, .env, and secrets to .gitignore
• Not pulling before pushing -- always git pull --rebase before push
• Using git add . blindly -- review git status and stage specific files