git-workflow

name

git-workflow

description

Git version control workflows for AI coding agents. Use when tasks involve committing changes, creating branches, opening pull requests, resolving merge conflicts, writing commit messages, reviewing diffs, rebasing, stashing, cherry-picking, tagging releases, or any git-related operation. Triggers on: 'commit my changes', 'create a PR', 'push this branch', 'fix merge conflict', 'git status', 'review changes', 'squash commits', 'tag a release', 'revert a commit', or any git/GitHub/GitLab CLI workflow.

Git Workflow Skill

Structured git workflows for AI coding agents. Follow these procedures instead of ad-hoc bash commands.

Pre-flight: Assess State

Before any git operation, gather context:

git status --short --branch
git log --oneline -5
git remote -v

Check for uncommitted changes, current branch, and remote configuration before proceeding.

Commit Workflow

1. Stage changes intentionally

Never use git add . blindly. Review what changed first:

git diff --stat
git diff              # unstaged changes
git diff --cached     # staged changes

Stage related changes together. Use git add -p for partial staging when a file contains unrelated changes.

2. Write Conventional Commits

Follow Conventional Commits format:

<type>(<scope>): <short summary>

<optional body — explain WHY, not WHAT>

<optional footer — references, breaking changes>

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

Examples:

feat(auth): add OAuth2 token refresh with exponential backoff

fix(parser): handle nested quotes in CSV fields

docs(api): add rate limiting section to REST reference

refactor(db): extract connection pooling into shared module

test(auth): add integration tests for token expiry edge cases

Rules:

• Subject line ≤ 72 characters, imperative mood ("add" not "added")
• Scope is optional but preferred for non-trivial repos
• Body wraps at 72 characters, separated by blank line
• Reference issues with Closes #123 or Refs #456

3. Commit command

git commit -m "type(scope): summary" -m "Optional body explaining why."

For multi-line messages, use a temp file:

cat > /tmp/commit-msg.txt << 'EOF'
feat(session): add token usage and cost tracking

Track per-turn and cumulative token usage with estimated costs.
Supports budget alerts (warn + hard-stop thresholds) and
per-model cost breakdown.

Closes #42
EOF
git commit -F /tmp/commit-msg.txt

Branch Workflow

Naming convention

<type>/<short-description>

Examples: feat/cost-tracking, fix/oauth-refresh, docs/api-reference, refactor/db-pooling

Create and switch

git checkout -b feat/my-feature           # from current branch
git checkout -b feat/my-feature origin/main  # from remote main

Keep branch updated

git fetch origin
git rebase origin/main    # preferred: linear history
# OR
git merge origin/main     # if rebase would be destructive

If rebase conflicts arise, resolve each file, then:

git add <resolved-file>
git rebase --continue

To abort a bad rebase: git rebase --abort

Pull Request Workflow

Pre-PR checklist

1. Ensure tests pass locally
2. Ensure branch is up-to-date with target
3. Review own diff: git diff origin/main...HEAD --stat

Using GitHub CLI (gh)

# Create PR
gh pr create --title "feat(scope): summary" \
  --body "## What\nDescription of changes.\n\n## Why\nMotivation.\n\n## Testing\nHow it was tested." \
  --base main

# Create draft PR
gh pr create --draft --title "wip: exploration" --body "Early draft."

# List open PRs
gh pr list

# View PR details
gh pr view <number>

# Merge PR (squash preferred for clean history)
gh pr merge <number> --squash --delete-branch

PR description template

## What
Brief description of the change.

## Why
Motivation and context.

## How
Implementation approach (optional, for complex changes).

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] CI passes

## Related
Closes #<issue>

Merge Conflict Resolution

Identify conflicts

git status                    # shows conflicted files
git diff --name-only --diff-filter=U  # only conflicted files

Resolution strategy

1. Open each conflicted file
2. Look for conflict markers: <<<<<<<, =======, >>>>>>>
3. Decide: keep ours, keep theirs, or merge manually
4. Remove ALL conflict markers
5. Stage resolved files: git add <file>
6. Continue the operation:
   • Merge: git commit (auto-generated message is fine)
   • Rebase: git rebase --continue
   • Cherry-pick: git cherry-pick --continue

Quick resolution commands

git checkout --ours <file>    # keep current branch version
git checkout --theirs <file>  # keep incoming version

Stash Workflow

Save work-in-progress without committing:

git stash push -m "wip: description"   # always name stashes
git stash list                          # see all stashes
git stash pop                           # apply and remove latest
git stash apply stash@{1}              # apply specific stash
git stash drop stash@{0}               # remove specific stash

History Management

Interactive rebase (squash, reword, reorder)

git rebase -i HEAD~3          # last 3 commits
git rebase -i origin/main     # all commits since main

In the editor: pick, squash (or s), reword (or r), drop (or d), edit (or e)

Undo operations

git revert <sha>              # safe: creates new undo commit
git reset --soft HEAD~1       # undo commit, keep changes staged
git reset --mixed HEAD~1      # undo commit, unstage changes
git reset --hard HEAD~1       # DESTRUCTIVE: discard commit + changes

Prefer git revert on shared branches. Use git reset only on local/personal branches.

Cherry-pick

git cherry-pick <sha>                      # single commit
git cherry-pick <sha1> <sha2>              # multiple commits
git cherry-pick <sha> --no-commit          # apply without committing

Tagging Releases

git tag -a v1.2.0 -m "Release v1.2.0: cost tracking feature"
git push origin v1.2.0
git push origin --tags        # push all tags

Use semantic versioning: vMAJOR.MINOR.PATCH

Safety Rules

1. Never force-push shared branches (main, develop, release/*)
2. Never git reset --hard on shared branches — use git revert
3. Always fetch before rebase — git fetch origin && git rebase origin/main
4. Check branch before destructive ops — git branch --show-current
5. Back up before risky operations — git stash or create a temp branch
6. When unsure, ask the user before: force-pushing, resetting, or deleting branches

Git Configuration Tips

git config --global init.defaultBranch main
git config --global pull.rebase true
git config --global rerere.enabled true     # remember conflict resolutions
git config --global core.autocrlf input     # normalize line endings