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

<type>(<scope>): <description>

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