Git Workflow Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: git-workflow for comprehensive documentation.

When NOT to Use This Skill

This skill focuses on Git workflow and collaboration. Do NOT use for:

Git command syntax - Use Git official documentation or man git
CI/CD pipelines - Use ci-cd or GitHub Actions specific skills
Code quality review - Use code-reviewer agent or clean-code skill
Deployment strategies - Use DevOps or infrastructure skills
Project management - Use issue tracking and planning tools documentation

Anti-Patterns

Anti-Pattern Why It's Bad Best Practice

Giant commits Hard to review, risky to revert Atomic commits with single purpose

Vague commit messages "fix", "update" Conventional commits with context

Committing directly to main No review, breaks builds Feature branches + PR workflow

Force push to shared branches Destroys history, breaks others Use --force-with-lease , communicate

Merge commits everywhere Cluttered history Rebase feature branches before merge

No PR description Reviewers don't know context Clear description with why/what/how

Large PRs (1000+ lines) Impossible to review Small, focused PRs

Mixing refactor + feature Hard to review, hard to revert Separate refactor and feature PRs

WIP commits in main Unprofessional history Squash before merge

Quick Troubleshooting

Issue Check Solution

Accidental commit to main git status

git reset --soft HEAD~1 , create branch, commit there

Need to undo last commit Keep changes? git reset --soft HEAD~1 (keep) or --hard (discard)

Merge conflict Conflicting changes Resolve manually, git add , git commit

Pushed wrong code Already pushed? git revert <commit> (safe) or coordinate force push

Lost commits Deleted branch? git reflog , find SHA, git cherry-pick or checkout

Want to change commit message Last commit? git commit --amend (if not pushed)

PR too large

500 lines Split into multiple PRs with dependencies

Branch Naming

feature/add-user-authentication bugfix/fix-login-redirect hotfix/critical-security-patch release/v1.2.0 chore/update-dependencies docs/api-documentation

Conventional Commits

feat: add user authentication fix: resolve login redirect issue docs: update API documentation style: format code with prettier refactor: extract validation logic test: add user service tests chore: update dependencies perf: optimize database queries

Common Commands

Branch operations

git checkout -b feature/new-feature git branch -d feature/merged-branch git push -u origin feature/new-feature

Stashing

git stash git stash pop git stash list git stash drop

History

git log --oneline -20 git log --graph --oneline git reflog

Undo changes

git checkout -- file.txt # Discard file changes git reset HEAD file.txt # Unstage file git reset --soft HEAD~~1 # Undo last commit, keep changes git reset --hard HEAD~~1 # Undo last commit, discard changes git revert <commit> # Create undo commit

Rebase vs Merge

Rebase (clean history)

git checkout feature git rebase main git push --force-with-lease

Merge (preserve history)

git checkout main git merge feature

Interactive rebase

git rebase -i HEAD~3 # Squash, reorder, edit

Pull Request Best Practices

Do Don't

Small, focused PRs Giant PRs with unrelated changes

Clear description Empty description

Self-review before requesting Push broken code

Respond to feedback promptly Ignore comments

Squash fixup commits Leave WIP commits

Protected Branch Rules

Require pull request reviews
Require status checks to pass
Require branches to be up to date
No force pushes
No deletions

Production Readiness

Branch Strategy

main (production) └── develop ├── feature/user-auth ├── feature/payment └── bugfix/login-issue

Release Flow: develop → release/v1.2.0 → main (tag v1.2.0)

Hotfix Flow: main → hotfix/critical-fix → main + develop

Commit Hooks

.husky/commit-msg

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit $1

// commitlint.config.js export default { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [2, 'always', [ 'feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf', 'ci', 'revert' ]], 'subject-max-length': [2, 'always', 72], 'body-max-line-length': [2, 'always', 100], }, };

Automated Changelog

// release.config.js (semantic-release) export default { branches: ['main'], plugins: [ '@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/changelog', '@semantic-release/npm', '@semantic-release/github', ['@semantic-release/git', { assets: ['CHANGELOG.md', 'package.json'], message: 'chore(release): ${nextRelease.version}' }] ] };

Code Review Checklist

PR Review Checklist

Code Quality

Follows project conventions
No unnecessary complexity
Proper error handling
No security vulnerabilities

Testing

Unit tests for new code
Integration tests if needed
All tests passing

Documentation

Code is self-documenting
Complex logic has comments
API changes documented

Performance

No N+1 queries
No memory leaks
Appropriate caching

GitHub Actions Integration

.github/workflows/pr-check.yml

name: PR Check

on: pull_request

jobs: lint-commits: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0

  - name: Lint commits
    uses: wagoid/commitlint-github-action@v5

validate-pr: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Check PR title
    uses: amannn/action-semantic-pull-request@v5
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Git Configuration

~/.gitconfig

[user] name = Your Name email = your.email@example.com signingkey = YOUR_GPG_KEY

[commit] gpgsign = true

[pull] rebase = true

[fetch] prune = true

[init] defaultBranch = main

[alias] co = checkout br = branch ci = commit st = status lg = log --oneline --graph --decorate undo = reset --soft HEAD~1

Monitoring Metrics

Metric Target

PR merge time < 24h

Review turnaround < 4h

Failed CI on PR < 10%

Commit message compliance 100%

Checklist

Branch naming convention
Conventional commits
Commit message linting
Pre-commit hooks
PR template
Code review checklist
Branch protection rules
Automated changelog
Semantic versioning
GPG commit signing

Reference Documentation

Rebasing
Merge Strategies

git-workflow

Safety Notice

Copy this and send it to your AI assistant to learn