Git Workflow

Git Workflow Skill

Practical patterns, examples, and edge case guidance for Git workflows. For the base rules, see git.instructions.md. This skill extends those rules with how-to guidance.

WHEN_TO_USE

Apply this skill when:

• Writing commit messages for non-trivial changes (multi-scope, breaking changes, reverts).
• Handling complex merge/rebase scenarios.
• Preparing a release (tagging, changelog, version bumps).
• Reviewing Git history for consistency.

Commit Message Examples

Good vs Bad

# BAD: vague, no type, past tense
fixed stuff
updated code
changes

# BAD: too long, wrong mood, has period
feat(authentication): Added the new OAuth2 login flow for users to authenticate with Google and GitHub providers.

# GOOD: clear type, imperative, concise
feat(auth): add OAuth2 login flow
fix(api): handle null response from payment gateway
refactor(db): extract query builder into separate module

# GOOD: scoped to specific area
test(auth): add integration tests for login flow
build(deps): upgrade React to v19
ci(actions): add staging deployment workflow

Multi-Scope Commits

When a change spans multiple scopes, pick the primary scope and mention others in the body:

feat(auth): add session refresh on token expiry

Affects auth, api, and middleware modules.
- Auth: add refreshToken() to session manager
- API: pass refresh token header on 401 retry
- Middleware: check token expiry before route handler

Breaking Change Commits

feat(api)!: change pagination from offset to cursor-based

BREAKING CHANGE: All list endpoints now require `cursor` parameter
instead of `page`/`limit`. Responses include `nextCursor` instead
of `totalPages`.

Migration: Replace `?page=2&limit=20` with `?cursor=<nextCursor>&limit=20`.

Revert Commits

revert: feat(auth): add OAuth2 login flow

This reverts commit abc1234.

Reason: OAuth provider rate-limiting caused login failures
under load. Reverting until rate-limit handling is implemented.

Complex Merge Scenarios

Feature Branch Behind Main

# Preferred: rebase onto main (clean linear history)
git fetch origin
git rebase origin/main

# If conflicts arise, resolve file-by-file
git status                    # see conflicted files
# edit files to resolve conflicts
git add <resolved-file>
git rebase --continue

# Abort if rebase becomes unmanageable
git rebase --abort

When to Rebase vs Merge

Interactive Rebase to Clean Up History

Before opening a PR, clean up work-in-progress commits:

# Squash last 4 commits into meaningful units
git rebase -i HEAD~4

# In the editor:
pick abc1234 feat(auth): add login form
squash def5678 wip: form validation
squash ghi9012 fix: typo in error message
squash jkl3456 wip: add tests

# Rewrite the combined commit message
feat(auth): add login form with validation

- Email/password form with client-side validation
- Error messages for invalid credentials
- Unit tests for form submission

Resolving Merge Conflicts

1. Understand both sides — read the diff, not just the conflict markers.
2. Keep the intent of both changes when possible.
3. Run tests after resolving — a clean merge is not necessarily a correct merge.
4. Never blindly accept "ours" or "theirs" on non-trivial conflicts.

Release Workflow

Tagging a Release

# Create annotated tag (preferred over lightweight)
git tag -a v2.1.0 -m "Release v2.1.0: cursor pagination, OAuth2 flow"

# Push tag
git push origin v2.1.0

Semantic Versioning from Commits

Changelog Generation from Commits

Structure generated changelogs by commit type:

## [2.1.0] - 2026-02-23

### Added
- OAuth2 login flow (`feat(auth): add OAuth2 login flow`)
- User profile page (`feat(ui): add profile page`)

### Fixed
- Null response handling in payment gateway (`fix(api): handle null response`)

### Performance
- Added index on user_email column (`perf(search): add index on user_email`)

### Breaking Changes
- Pagination changed from offset to cursor-based (`feat(api)!: change pagination`)

Hotfix Flow

# Branch from the release tag, not main
git checkout -b hotfix/payment-timeout v2.1.0

# Fix, commit, tag
git commit -m "fix(payments): increase gateway timeout to 30s"
git tag -a v2.1.1 -m "Hotfix: payment gateway timeout"

# Merge back to main AND the current release branch
git checkout main
git merge hotfix/payment-timeout
git checkout release/2.2.0
git merge hotfix/payment-timeout
git branch -d hotfix/payment-timeout

Common Mistakes to Avoid

TROUBLESHOOTING

Undo Last Commit (Keep Changes)

git reset --soft HEAD~1

Undo Last Commit (Discard Changes)

git reset --hard HEAD~1

Remove Sensitive Data from History

# Install git-filter-repo (preferred over filter-branch)
git filter-repo --path secrets.env --invert-paths
git push --force-with-lease

Find Which Commit Introduced a Bug

git bisect start
git bisect bad                 # current commit is broken
git bisect good v2.0.0         # last known good version
# Git checks out middle commits — test each one
git bisect good                # or git bisect bad
# Repeat until the culprit is found
git bisect reset