/managing-git

name: managing-git
description: Guides git workflows, branching strategies, commit conventions, and version control best practices. Use when managing repositories, creating branches, or handling merges.
license: MIT
compatibility: opencode
metadata:
  category: workflow
  audience: developers

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

| Branch | Purpose | Branches From | Merges Into | |--------|---------|---------------|-------------| | `main` | Production code | - | - | | `develop` | Integration | main | release | | `feature/*` | New features | develop | develop | | `release/*` | Release prep | develop | main, develop | | `hotfix/*` | Production fixes | main | main, develop |

**Use when**: Scheduled releases, multiple versions supported

GitHub Flow

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

| Branch | Purpose | |--------|---------| | `main` | Always deployable | | `feature/*` | All changes (features, fixes) |

**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

| Type | Description | Example | |------|-------------|---------| | `feat` | New feature | `feat(auth): add OAuth2 login` | | `fix` | Bug fix | `fix(api): handle null response` | | `docs` | Documentation | `docs(readme): update setup steps` | | `style` | Formatting | `style: fix indentation` | | `refactor` | Code restructuring | `refactor(db): simplify query builder` | | `test` | Adding tests | `test(user): add registration tests` | | `chore` | Maintenance | `chore(deps): update lodash` | | `perf` | Performance | `perf(search): add index on email` | | `ci` | CI/CD changes | `ci: add Node 18 to matrix` |

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

| Type | Example | |------|---------| | Feature | `feature/AUTH-123-add-oauth-login` | | Bugfix | `fix/CART-456-quantity-validation` | | Hotfix | `hotfix/PROD-789-memory-leak` | | Chore | `chore/update-dependencies` | | Docs | `docs/api-documentation` |

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

| Command | Purpose | |---------|---------| | `git stash` | Save uncommitted changes temporarily | | `git stash pop` | Restore stashed changes | | `git commit --amend` | Modify last commit | | `git rebase -i HEAD~3` | Interactive rebase (squash, reorder) | | `git cherry-pick <sha>` | Apply specific commit | | `git bisect` | Binary search for bug introduction | | `git reflog` | View all HEAD movements (recovery) |

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-revie