Git Workflow Management

Help teams establish and follow effective Git workflows. Covers branching strategies, commit conventions, merge conflict resolution, interactive rebase, and cherry-picking across branches.

Workflow

Step 1: Assess the Current Situation

Determine what Git help is needed and gather context:

• Branch strategy request: Check the repo structure with git branch -a, look at existing branches, and review the team size and release cadence.
• Commit convention: Read recent commit history with git log --oneline -20 to understand current patterns.
• Merge conflict: Run git status to identify conflicted files, then git diff to see the conflict markers.
• Rebase request: Check the current branch with git branch --show-current, its upstream with git log --oneline HEAD..origin/main, and divergence point.
• Cherry-pick: Identify the source commit with git log --oneline <branch> and the target branch.

Also check for existing configuration:

• Look for .gitconfig, .gitattributes, and .gitignore at repo root.
• Check for branch protection rules in .github/ settings or CI config.
• Look for commit message templates in .gitmessage or hook scripts in .husky/ or .git/hooks/.

Step 2: Branching Strategy

Recommend a branching strategy based on the team's needs:

Git Flow (best for versioned releases, larger teams)

• main — production-ready code, tagged releases
• develop — integration branch for features
• feature/<name> — individual feature work
• release/<version> — release stabilization
• hotfix/<name> — urgent production fixes

GitHub Flow (best for continuous deployment, smaller teams)

• main — always deployable
• feature/<name> — short-lived branches, merged via PR
• No develop branch; deploy directly from main after merge

Trunk-Based Development (best for CI/CD-heavy teams)

• main — single source of truth
• Short-lived feature branches (< 2 days)
• Feature flags for incomplete work
• Release branches cut from main only when needed

Release Branch Model (best for supporting multiple versions)

• main — latest development
• release/v1.x, release/v2.x — long-lived release branches
• Fixes cherry-picked from main to release branches

Step 3: Commit Conventions

Recommend and enforce commit message standards:

Conventional Commits Format:

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

<body>

<footer>

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Examples:

feat(auth): add OAuth2 login with Google provider

Implements Google OAuth2 flow using passport-google-oauth20.
Adds session persistence and token refresh logic.

Closes #142

fix(api): prevent race condition in order processing

Multiple concurrent requests could create duplicate orders
when the idempotency check used a non-atomic read-then-write.
Switched to database-level unique constraint on idempotency_key.

Fixes #287

Enforcing conventions:

• Suggest installing commitlint with @commitlint/config-conventional.
• Set up a commit-msg hook via Husky: npx husky add .husky/commit-msg 'npx commitlint --edit $1'.
• Add a commitlint.config.js to the repo root.

Step 4: Merge Conflict Resolution

When the user has a merge conflict:

1. Identify conflicts: Run git status and list all files with UU (both modified) status.
2. Read each conflict: Open each conflicted file and locate <<<<<<<, =======, >>>>>>> markers.
3. Understand both sides: Explain what the current branch changed vs. what the incoming branch changed.
4. Resolve: Suggest the correct resolution based on intent. Options:
   • Accept current (ours): git checkout --ours <file>
   • Accept incoming (theirs): git checkout --theirs <file>
   • Manual merge: Edit the file to combine both changes logically.
5. Mark resolved: git add <file> for each resolved file.
6. Complete: git merge --continue or git rebase --continue depending on the operation.

For complex conflicts, use git log --merge -p <file> to see the full change history on both sides.

Step 5: Rebase Workflows

Simple rebase onto main:

git fetch origin
git rebase origin/main
# Resolve any conflicts, then:
git rebase --continue

Interactive rebase to clean up history:

git rebase -i HEAD~<n>

• pick — keep the commit as-is
• squash — combine with the previous commit
• fixup — like squash but discard the commit message
• reword — change the commit message
• edit — pause to amend the commit
• drop — remove the commit entirely

When to rebase vs. merge:

• Rebase for a clean, linear history on feature branches before merging to main.
• Merge (with merge commit) to preserve the feature branch history.
• Never rebase commits that have been pushed and shared with others.

Step 6: Cherry-Picking

Basic cherry-pick:

git cherry-pick <commit-hash>

Cherry-pick without committing (to review first):

git cherry-pick --no-commit <commit-hash>

Cherry-pick a range:

git cherry-pick <start-hash>^..<end-hash>

Best practices for cherry-picking:

• Always reference the original commit in the cherry-picked message.
• Use -x flag to append the original commit hash: git cherry-pick -x <hash>.
• Prefer cherry-picking to release branches, not the other way around.
• If a cherry-pick conflicts, resolve carefully since the surrounding code may differ between branches.

Output Format

## Git Workflow Recommendation

### Branching Strategy: <strategy name>

**Why this fits your team**: <rationale based on team size, release cadence, deployment model>

### Branch Naming Convention
- Feature: `feature/<ticket-id>-<short-description>`
- Bugfix: `fix/<ticket-id>-<short-description>`
- Release: `release/v<major>.<minor>`
- Hotfix: `hotfix/<ticket-id>-<short-description>`

### Commit Convention
<format with examples>

### Merge Policy
- [ ] Require PR reviews (minimum <n> approvers)
- [ ] Require CI passing before merge
- [ ] Squash merge for feature branches / merge commit for releases
- [ ] Delete branch after merge

### Setup Commands
<exact commands to configure hooks, tools, branch protections>

Examples

User: "We're a team of 5, deploying multiple times a day. What Git workflow should we use?" Action: Recommend GitHub Flow or Trunk-Based Development. Provide branch naming, commit conventions, and CI/CD integration guidance.

User: "I have a merge conflict in src/api/users.ts" Action: Run git status, read the conflicted file, explain both sides of the conflict, suggest the correct resolution, and walk through completing the merge.

User: "Clean up my last 4 commits before I open a PR" Action: Guide through git rebase -i HEAD~4, suggest squashing related commits, reword messages to follow conventions.

User: "Cherry-pick commit abc123 from main into release/v2.1" Action: Check out the release branch, cherry-pick with -x, resolve any conflicts, verify the result.

Best Practices

• Always fetch before rebasing or merging to work with the latest remote state.
• Use git stash before switching branches if you have uncommitted work.
• Prefer --no-ff merges for feature branches to preserve branch topology in history.
• Set pull.rebase = true in git config for teams using rebase workflows.
• Use git reflog to recover from mistakes — it tracks all HEAD movements for 90 days.
• Never force-push to shared branches without coordinating with the team.
• When in doubt about a destructive operation, create a backup branch first: git branch backup/<name>.
• Configure .gitattributes for consistent line endings and merge drivers for lock files.