Managing Git

Best practices for version control, branching strategies, and collaborative development.

When to Use This Skill

• Setting up branching strategies
• Writing commit messages
• Handling merges and conflicts
• Managing releases
• Code review workflows
• Maintaining clean history

Branching Strategies

Git Flow

main ─────●─────────────────────●─────────────────●────▶
           \                   /                 /
release     \───────●─────────●                 /
              \                                /
develop ───────●───────●───────●──────●───────●────────▶
                \       \       \      \
feature          \───────●───────●      \───●───●
                          \              \
hotfix                     \              \───●────▶ main

Use when: Scheduled releases, multiple versions supported

GitHub Flow

main ─────●─────●─────●─────●─────●────▶
           \   /       \   /       \   /
feature     ●─●         ●─●         ●─●
            PR          PR          PR

Use when: Continuous deployment, simple workflow

Trunk-Based Development

main ─────●──●──●──●──●──●──●──●──●──●────▶
           │  │  │  │  │  │  │  │  │  │
          ●   ●  ●  ●  ●  ●  ●  ●  ●  ●
          Small, frequent commits (often direct to main)

Use when: High trust teams, strong CI/CD, frequent deploys

Commit Message Conventions

Conventional Commits

<type>(<scope>): <subject>

<body>

<footer>

Types

Good vs Bad Commits

BAD:
  - "fix"
  - "update code"
  - "WIP"
  - "changes"
  - "asdfasdf"

GOOD:
  - "fix(auth): prevent session timeout on idle"
  - "feat(cart): add quantity validation"
  - "refactor(api): extract common error handling"

Commit Body Guidelines

fix(payment): prevent double charge on retry

The payment gateway timeout was causing the retry logic to submit
duplicate charges. Added idempotency key to prevent double-processing.

Closes #1234

• First line: 50 chars max, imperative mood
• Body: Wrap at 72 chars, explain why, not what
• Footer: Reference issues, breaking changes

Branch Naming Conventions

Pattern

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

Examples

Branch Rules

1. Lowercase with hyphens
2. Include ticket number when available
3. Keep short but descriptive
4. Delete after merge

Git Workflow Commands

Daily Workflow

# Start new feature
git checkout main
git pull origin main
git checkout -b feature/AUTH-123-add-login

# Work on feature
git add -p                    # Stage hunks interactively
git commit -m "feat(auth): add login form"

# Keep up to date
git fetch origin
git rebase origin/main        # Preferred: clean history
# OR
git merge origin/main         # Alternative: preserves context

# Push and create PR
git push -u origin feature/AUTH-123-add-login

Useful Commands

Cleanup Commands

# Delete merged branches locally
git branch --merged | grep -v main | xargs git branch -d

# Prune remote tracking branches
git fetch --prune

# Clean untracked files (careful!)
git clean -fd

Handling Conflicts

Conflict Resolution Flow

1. Identify conflicts
   git status

2. Open conflicted files
   <<<<<<< HEAD
   your changes
   =======
   their changes
   >>>>>>> feature-branch

3. Resolve (keep one, combine, or rewrite)

4. Mark resolved
   git add <resolved-file>

5. Continue
   git rebase --continue   # if rebasing
   git commit              # if merging

Prevention Strategies

1. Small, frequent merges - Reduce conflict scope
2. Communication - Coordinate on shared files
3. Feature flags - Reduce long-lived branches
4. Clear ownership - Minimize overlapping work

Pull Request Best Practices

PR Checklist

• Branch is up to date with main
• Tests pass locally
• Linting passes
• Self-review completed
• Documentation updated
• Ticket/issue linked
• Screenshots for UI changes

PR Size Guidelines

PR Description Template

## Summary
Brief description of changes

## Changes
- Added X
- Modified Y
- Removed Z

## Testing
- [ ] Unit tests added
- [ ] Manual testing done

## Screenshots (if applicable)
[Before/After images]

## Related Issues
Closes #123

Release Management

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backward compatible)
  │     └── New features (backward compatible)
  └── Breaking changes

Release Process

# Create release branch
git checkout -b release/v1.2.0 develop

# Bump version, update changelog
# ... make changes ...

# Merge to main and tag
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# Merge back to develop
git checkout develop
git merge release/v1.2.0

Changelog Format

# Changelog

## [1.2.0] - 2024-01-15
### Added
- OAuth2 authentication support

### Changed
- Improved error messages

### Fixed
- Memory leak in cache handler

### Deprecated
- Old authentication method (use OAuth2)

### Removed
- Legacy API v1 endpoints

Git Hooks

Common Hooks

Example pre-commit

#!/bin/sh
# .git/hooks/pre-commit

# Run linter
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Please fix errors."
  exit 1
fi

# Run tests
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Please fix before committing."
  exit 1
fi

Using Husky (Node.js)

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

Troubleshooting

Common Issues

Recovery Commands

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Recover deleted branch
git reflog
git checkout -b recovered-branch <sha>

# Undo a pushed commit (safe)
git revert <sha>

Anti-Patterns to Avoid

1. Force pushing to shared branches - Breaks others' history
2. Giant commits - Hard to review, hard to bisect
3. Vague commit messages - "fix" tells nothing
4. Long-lived branches - Merge conflict hell
5. Committing generated files - Bloats repo, causes conflicts
6. Committing secrets - Security risk (even after removal)
7. Rebasing public history - Breaks collaborators
8. Ignoring CI failures - Broken windows effect

Quick Reference

BRANCHES:
  main       → Production (protected)
  develop    → Integration (Git Flow)
  feature/*  → New work
  fix/*      → Bug fixes
  hotfix/*   → Production emergencies

COMMITS:
  feat(scope): add feature
  fix(scope): fix bug
  docs(scope): update docs
  refactor(scope): restructure code

DAILY FLOW:
  git checkout -b feature/ticket-desc
  git add -p && git commit
  git rebase origin/main
  git push -u origin feature/ticket-desc

VERSIONING:
  MAJOR.MINOR.PATCH
  Breaking.Feature.Bugfix