Git Workflow

Git Workflow

Automate the development cycle: branch, commit, PR, review, merge, cleanup. Follows conventional commits and trunk-based development.

Workflow

Step 1: Create a feature branch

scripts/create-feature-branch.ps1 -Name "add-user-auth" -Type feat

This:

1. Detects default branch (main/master)
2. Fetches and pulls latest
3. Creates feat/add-user-auth from base
4. Pushes upstream with tracking

Branch naming: | Type | Prefix | Example | |------|--------|---------| | Feature | feat/ | feat/add-user-auth | | Fix | fix/ | fix/login-redirect | | Docs | docs/ | docs/api-readme | | Refactor | refactor/ | refactor/auth-middleware | | Chore | chore/ | chore/update-deps |

Step 2: Make atomic commits

scripts/auto-commit.ps1 -Scope "auth" -DryRun  # Preview first
scripts/auto-commit.ps1 -Scope "auth"           # Commit

The script analyses changed files, generates a conventional commit message, and stages+commits.

Conventional commit format:

(): 

[optional body]

[optional footer]

Rules:

• One logical change per commit
• Description: imperative mood, lowercase, max 72 chars
• Scope: the module/area affected
• Footer: BREAKING CHANGE:, Closes #123, Co-authored-by:

Step 3: Prepare for PR

# Interactive rebase (squash WIP commits)
git rebase -i main

# Generate PR body from commit history
scripts/pr-body.ps1 -Clipboard

The PR body script:

1. Detects base branch
2. Extracts commits since fork
3. Groups by conventional commit type
4. Generates ## Summary, ## Changes, ## Testing sections
5. Copies to clipboard

Squash rules:

• Squash fixup! and wip commits
• Keep meaningful commit history
• Never squash if commits have different scopes
• Use git rebase -i main with fixup (f) for WIP commits

Step 4: Create PR

# Create PR with generated body
gh pr create --title "feat(auth): add user authentication" --body "$(Get-Clipboard)"

# Or use the file
gh pr create --title "feat(auth): add user authentication" --body-file .pr-body.md

PR guidelines: | Aspect | Rule | |--------|------| | Size | Max 400 lines changed | | Title | Same as conventional commit | | Description | What + Why + How to test | | Reviewers | 1-2 relevant team members | | Labels | Type (feat/fix/docs) + priority | | Draft | Use for Work-in-Progress |

Step 5: Clean up after merge

scripts/cleanup-branches.ps1

This lists merged branches (excluding protected ones), asks for confirmation, deletes locally and remotely, and prunes remote tracking refs.

Workflow by strategy

See [references/git-workflows.md](references/git-workflows.md) for full reference.

| Strategy | Best for | Branch model | Pros | Cons | Guidance | |----------|----------|--------------|------|------|----------| | Trunk-based | CI/CD, deploys multiple times/day, feature flags | Short-lived feature branches → main (hours, not days) | Fast integration, no merge hell, simple CI | Requires feature flags + high test coverage | Keep branches under 24h. Use branch by abstraction for large changes. | | GitHub Flow | Standard SaaS, team of 2-10 | feature → main (PR + squash merge) | Simple, review-friendly, clean history | Can't manage multiple releases | Use for most projects. Squash-merge keeps main linear. Tag releases from main. | | GitFlow | Release management, multiple supported versions, regulated industries | feature → develop → release → main + hotfix branches | Full version tracking, parallel releases | High complexity, slow to release | Only use if you support 2+ release versions simultaneously. Overkill for single-version SaaS. | | GitLab Flow | Environment-based deployments, staging → production gating | feature → main → staging → production (branch per env) | Environment isolation, easy rollback | Duplicate merge overhead per env | Use when environments need different merge cadences. Pair with CI/CD environment protection. |

Default recommendation: GitHub Flow for simplicity. Trunk-based if CI/CD is mature and deploying multiple times/day.

Error Handling

| Scenario | Cause | Fix | |----------|-------|-----| | Rebase conflicts | Multiple people changed same lines | Resolve conflicts, git rebase --continue. See conflict resolution workflow below. | | Can't push (non-fast-forward) | Branch behind base | Rebase on base first | | Accidental commit on wrong branch | Careless checkout | Cherry-pick to correct branch, reset original | | Detached HEAD | Accidentally checked out a commit | git switch -c | | Lost commits after reset | git reset --hard | git reflog → find SHA → git cherry-pick |

Rebase conflict resolution

# During rebase, conflict arises
git status                          # See conflicted files
# Edit conflicted files → resolve markers (>>>>>)
git add 
git rebase --continue               # Move to next commit

# If the rebase is going poorly and you want to bail:
git rebase --abort                  # Return to pre-rebase state

# If you're mid-rebase, unsure, and want to compare:
git diff                            # Show conflict diff
git mergetool                       # Launch configured merge tool (VS Code: code --wait $MERGED)

# Skip a problematic commit entirely:
git rebase --skip

# After rebase, verify history:
git log --oneline --graph -20

Conflict avoidance:

• Keep branches short-lived (< 3 days). Longer branches accumulate merge debt.
• Pull/rebase daily from main during long features: git fetch origin && git rebase origin/main
• Break large features into stacked PRs (PR 1 → PR 2 → PR 3) instead of one 1000-line PR
• Communicate: if you're refactoring a shared module, tell the team

Parallel work with git worktree

Use git worktree to work on multiple branches simultaneously without stashing or cloning:

# Create a new worktree for a feature
git worktree add ../project-feat-auth feat/add-user-auth

# List all worktrees
git worktree list

# Remove a worktree after branch is merged
git worktree remove ../project-feat-auth
# Then delete the branch normally

When to use:

• Hotfix needs to go out while you're mid-feature on another branch
• Running CI/lint/tests in one worktree while coding in another
• Reviewing a PR branch without switching away from your current work
• Exploring an old commit without detaching HEAD

Branch Protection Rules

| Rule | GitHub setting | Why | |------|---------------|-----| | Require PR before merge | required_pull_request_reviews | Prevents direct pushes | | Require status checks | required_status_checks | CI must pass | | Require linear history | required_linear_history | No merge commits | | Require signed commits | required_signatures | Verify authorship | | Dismiss stale reviews | dismiss_stale_reviews | New pushes need re-review |

Production Checklist

• [ ] Branch named with conventional prefix
• [ ] Commit message follows conventional commits
• [ ] One logical change per commit
• [ ] PR description explains what + why + how to test
• [ ] PR under 400 lines changed
• [ ] CI passes (lint, typecheck, tests)
• [ ] At least 1 reviewer approved
• [ ] Branch deleted after merge
• [ ] No WIP commits in history

Anti-Patterns

| Anti-pattern | Fix | |-------------|-----| | git commit -m "fix bug" | Conventional commit with context | | 1000+ line PRs | Break into smaller, atomic changes | | Merging main into feature branch | Rebase instead (cleaner history) | | Committing directly to main | Branch + PR + review always | | No CI before merge | Block merging without passing checks | | Pushing to main without PR | Use branch protection rules | | Stale branches (older than 2 weeks) | Clean up regularly |

Sources

• Conventional Commits (conventionalcommits.org)
• GitHub Flow (docs.github.com)
• Trunk-Based Development (trunkbaseddevelopment.com)
• Git SCM docs (git-scm.com)
• Keep a Changelog (keepachangelog.com)
• Semantic Versioning (semver.org)

Checklist

• [ ] Skill loads without errors in the AI agent
• [ ] YAML frontmatter is valid (description, compatibility, audience)
• [ ] Workflow section provides clear step-by-step instructions
• [ ] Error handling section covers common failure modes
• [ ] All referenced files (references/, scripts/, assets/) exist
• [ ] Skill triggers correctly for intended use cases
• [ ] No broken links or missing resources

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EliasOulkadi
• Source: EliasOulkadi/shokunin
• License: MIT
• Homepage: https://eliasoulkadi.github.io/shokunin/

Install and usage instructions live in the source repository linked above.