Git Workflow Branching

---
name: git-workflow-branching
description: When creating, updating, and merging code in a collaborative version control environment.
version: 2.0.0
category: dev-tools
tags: [dev-tools, git, collaboration, version-control]
skill_type: workflow
author: skiLLM
license: MIT
compatible_agents: [claude-code, cursor, copilot, codex]
estimated_context_tokens: 1500
dangerous: false
requires_review: false
security_level: safe
dependencies: []
triggers: [git, branch, merge, commit, pull request]
permissions:
  filesystem: { read: true, write: true }
  network: { outbound: true }
  shell: { execute: true }
input_requirements: [git repository, remote configured]
output_contract: [linear git history, conventional commits, no WIP commits on main]
failure_conditions: [direct push to main, merge conflicts unresolved, broken CI on main]
last_updated: 2026-05-15
---

# Git Workflow & Branching

## Purpose
Clean git history is essential for debugging (`git bisect`), code review, and team collaboration. This skill standardizes branch naming, commit formatting, and merging to maintain a readable, revertible, and bisect-able history.

## When to use
- Starting a new feature or bugfix ticket
- Reviewing PRs and merging code into mainline
- Hotfixing production environments
- Onboarding new team members

## When NOT to use
- Dealing with complex merge conflicts (use git documentation)
- Repository history rewrites (different concern)
- CI/CD trigger configuration (separate skill)

## Inputs required
- Git repository with `main` branch
- Remote repository (GitHub, GitLab, Gitea)
- Team agreement on branch naming and commit conventions

## Workflow
1. **Sync Main**: ALWAYS fetch and pull latest from `main` before creating branch
2. **Create Branch**: Use convention `type/ticket-id-short-description` (e.g., `feat/PROJ-123-add-login`)
3. **Commit Atomically**: Commit in small logical chunks. MUST use Conventional Commits format
4. **Keep Branch Synced**: Rebase against `main` frequently to avoid merge conflicts
5. **Push Regularly**: Push to remote regularly (enables collaboration, backup)
6. **Rebase Before PR**: Interactive rebase to clean up WIP commits before opening PR
7. **Squash Merge**: Merge PR using squash-merge to keep main history clean
8. **Delete Branch**: Delete feature branch after merging (cleanup)

## Rules
- MUST NEVER push directly to `main` (always use PRs)
- MUST use Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
- MUST rebase before opening PR (no merge commits from main)
- MUST delete feature branches after merging
- MUST NOT commit with messages like "wip", "fixed typo", "trying again"
- MUST resolve conflicts locally before pushing
- MUST NOT force-push to shared branches
- MUST keep feature branches <5 days old before merging

## Anti-patterns
- **WIP Commits**: Pushing commits like "wip", "fixed typo", "let me try again" to main
- **Long-lived Branches**: Keeping branches active for weeks without syncing with main
- **Merge Commits**: Allowing merge commits from main to pollute history (use rebase)
- **Squashing Too Early**: Squashing before PR review (makes feedback hard to track)
- **Force Pushing to Shared**: `git push -f` on branches other developers are using
- **Vague Messages**: "Update stuff", "fix bug" (impossible to bisect later)

## Failure conditions
- Direct push to `main` detected
- Merge conflicts exist when opening PR
- Broken tests or CI failures on main
- WIP commits in main history
- Feature branches never deleted after merge

## Validation checklist
- [ ] Branch created from latest main
- [ ] Branch name follows `type/ticket-id-description` format
- [ ] All commits use Conventional Commits format
- [ ] No "wip", "fixed typo", or vague commit messages
- [ ] Commits are atomic (each solves one thing)
- [ ] Rebase completed, no merge commits from main
- [ ] All conflicts resolved locally
- [ ] CI passes before PR merge
- [ ] PR description links ticket
- [ ] Branch deleted after merging

## Output format
- **Branch naming**: `type/ticket-id-short-desc` (e.g., `feat/AUTH-42-oauth-integration`)
- **Commit format**: `type(scope): description\n\nbody\n\nfooter`
- **History**: Linear commits on main (no merge commits)
- **Merge strategy**: Squash-merge to single conventional commit

## Security considerations
- NEVER commit secrets (use `.gitignore`, environment variables)
- Code review MUST happen before main (enforce via PR requirements)
- Force-push MUST be disabled on main branch
- Branch protection rules MUST require passing CI

## Agent execution notes
- Agent MAY: Create branches, make commits, rebase branches, resolve conflicts, open PRs
- Agent MUST NEVER: Push directly to main, create WIP commits, force-push shared branches
- Agent MUST ASK: Before force-pushing, before deleting branches, before modifying main history
- Agent MUST VALIDATE: Branch follows naming convention, commits are conventional, CI passes

## Example

**❌ Anti-pattern (WIP commits, vague messages, no rebasing):**
```bash
git checkout main
# Forgot to pull - out of sync
git checkout -b feature-branch
git commit -m "wip"
git commit -m "fixed typo"
git commit -m "let me try again"
git commit -m "update stuff"
git push origin feature-branch
# Merge directly to main without PR
```

**✅ Correct pattern (Atomic commits, conventional, rebased, squashed):**
```bash
git fetch origin
git checkout -b feat/PROJ-123-add-oauth

# Make atomic commits with conventional format
git commit -m "feat(auth): add oauth service initialization"
git commit -m "feat(auth): implement oauth callback handler"
git commit -m "test(auth): add oauth flow tests"

git push origin feat/PROJ-123-add-oauth

# Before PR: rebase and squash if needed
git fetch origin
git rebase origin/main

# Squash merge via PR (git will handle this)
# After merge:
git checkout main
git pull origin main
git branch -d feat/PROJ-123-add-oauth
git push origin --delete feat/PROJ-123-add-oauth
```