1---2name: git-workflow-23description: Designs git workflows covering branching strategies, trunk-based development, stacked changes, conventional commits, CI/CD pipelines, and repository hygiene. Use when setting up branching models, writing commit messages, configuring GitHub Actions, managing stacked PRs, cleaning stale branches, creating issue templates, or recovering lost commits.4license: MIT5---6
7# Git Workflow
8
9Covers branching strategies, conventional commits, CI/CD automation, repository hygiene, and git internals. GitHub CLI usage is handled by a separate `github-cli` skill; this skill focuses on git workflow patterns and CI/CD configuration.
10
11## Quick Reference
12
13| Area | Key Practice |
14| ----------- | --------------------------------------------------------- |
15| Branching | Trunk-based development with short-lived feature branches |
16| Commits | Conventional commits with imperative mood |
17| History | Linear history via rebase; squash noisy commits |
18| PRs | Small, stacked changes; no mega PRs |
19| Main branch | Always deployable; broken main is an emergency |
20| CI/CD | Modular GitHub Actions with reusable workflows |
21| Merging | Green CI + review required before merge |
22| Versioning | Semantic Release or Changesets (never manual) |
23| Branches | Max 48 hours lifespan; auto-prune stale/merged |
24| Secrets | OIDC Connect in pipelines; never hardcode tokens |
25| Signing | Sign commits with SSH or GPG keys for verified authorship |
26
27## Branch Naming
28
29| Type | Use For | Example |
30| -------- | ------------------ | ---------------------- |
31| feat | New features | `feat/add-user-auth` |
32| fix | Bug fixes | `fix/login-redirect` |
33| chore | Maintenance | `chore/update-deps` |
34| docs | Documentation | `docs/api-reference` |
35| refactor | Code restructuring | `refactor/auth-module` |
36
37## Conventional Commit Types
38
39| Type | Purpose | Version Bump |
40| ---------- | ------------------------------------- | ------------ |
41| `feat` | New features | Minor |
42| `fix` | Bug fixes | Patch |
43| `docs` | Documentation only | None |
44| `style` | Formatting, no logic changes | None |
45| `refactor` | Neither fix nor feature | None |
46| `perf` | Performance improvements | Patch |
47| `test` | Adding or correcting tests | None |
48| `build` | Build system or external dependencies | None |
49| `ci` | CI configuration changes | None |
50| `chore` | Tooling, maintenance, non-src changes | None |
51| `revert` | Revert a previous commit | Varies |
52
53Append `!` after type/scope for breaking changes (major version bump).
54
55## Pre-Merge Checks
56
57All PRs require before merge:
58
59- Lint
60- Type check
61- Tests
62- Security scan
63- Review approval (human or automated)
64
65Auto-merge is acceptable for low-risk PRs when pipeline succeeds.
66
67## Troubleshooting
68
69| Issue | Resolution |
70| -------------------------------------- | ---------------------------------------------------------------------------------- |
71| Merge conflicts on long-running branch | Rebase onto main frequently; break remaining work into new branch if over 48 hours |
72| Broken main branch | Treat as emergency; revert offending commit, then fix forward on a branch |
73| Lost commits or data recovery | Use git reflog and object inspection (`git cat-file`, `git fsck`) |
74| CI pipeline failures | Check reusable workflow versions; verify OIDC permissions |
75| Stacked PR conflicts after rebase | Restack entire chain from base; Graphite handles automatically with `gt restack` |
76| Large file accidentally committed | Use `git filter-repo` to remove from history (not `git filter-branch`) |
77
78## Common Mistakes
79
80| Mistake | Correct Pattern |
81| ----------------------------------------------------- | ------------------------------------------------------------- |
82| Keeping feature branches alive longer than 48 hours | Merge or rebase daily; break large work into stacked PRs |
83| Committing directly to main without branch protection | Enable branch protection rules requiring CI and review |
84| Using merge commits that clutter history | Rebase and squash to maintain linear history |
85| Hardcoding tokens in GitHub Actions workflows | Use OIDC Connect for authentication in CI/CD pipelines |
86| Creating monolithic CI workflows in a single file | Split into reusable workflows and composite actions |
87| `Fix bug` as commit message | `fix(scope): correct bug description` (conventional) |
88| `feat: Added feature` (past tense) | `feat: add feature` (imperative mood, lowercase) |
89| Using `git filter-branch` for history rewriting | Use `git filter-repo` (faster, safer, officially recommended) |
90| Pushing to main directly | Create feature branch first |
91| Unsigned commits in shared repositories | Configure commit signing with SSH or GPG keys |
92
93## Delegation
94
95- **Audit repository branch hygiene and stale branches**: Use `Explore` agent to list and classify branch age and merge status
96- **Set up CI/CD pipelines with reusable workflows**: Use `Task` agent to create modular GitHub Actions configurations
97- **Design branching strategy for a new project**: Use `Plan` agent to evaluate trunk-based vs Git Flow based on team needs
98
99## References
100
101- [branching-strategies.md](references/branching-strategies.md) -- Git Flow, GitHub Flow, GitLab Flow, One-Flow comparison and selection criteria
102- [trunk-based-development.md](references/trunk-based-development.md) -- Core principles, workflow steps, feature flags, and anti-patterns
103- [stacked-changes.md](references/stacked-changes.md) -- Stacked PRs concept, manual stacking, Graphite automation, best practices
104- [conventional-commits.md](references/conventional-commits.md) -- Commit format, types, scopes, breaking changes, and full workflow
105- [github-actions.md](references/github-actions.md) -- Reusable workflows, matrix testing, deployment environments, security
106- [git-internals.md](references/git-internals.md) -- Object model, SHA hashing, index, references, packfiles, garbage collection
107- [automation-scripts.md](references/automation-scripts.md) -- Branch pruning, semantic release, security scanning, stacked PR helpers
108- [issue-templates.md](references/issue-templates.md) -- Bug report, feature request, task, and minimal issue templates
109- [advanced-operations.md](references/advanced-operations.md) -- Commit signing, interactive rebase, worktrees, bisect, reflog recovery, and --force-with-lease
diegosouzapw