engineering
Git Workflow Guide
Git workflow reference covering branch naming, commit message conventions, PR templates, merge strategies, and common operations — for consistent team collaboration.
gitversion-controlworkflowpull-requestsbranching
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill git-workflow-guidegit-workflow-guide/
SKILL.md
Markdown
| 1 | |
| 2 | # Git Workflow Guide |
| 3 | |
| 4 | ## Before you start |
| 5 | |
| 6 | Confirm the following for the project: |
| 7 | |
| 8 | 1. **What is the branching model?** — Trunk-based, GitFlow, or GitHub Flow |
| 9 | 2. **What is the main branch name?** — `main` or `master` |
| 10 | 3. **Are there branch protection rules?** — Required reviews, CI checks, linear history |
| 11 | 4. **What is the merge strategy?** — Squash, rebase, or merge commit |
| 12 | 5. **Is there a commit message convention?** — Conventional Commits, Angular, or custom |
| 13 | |
| 14 | If these are not documented, ask the team lead before establishing your own pattern. Inconsistency in git workflows creates merge conflicts and confusion. |
| 15 | |
| 16 | ## Branch naming |
| 17 | |
| 18 | Use this format: |
| 19 | |
| 20 | ``` |
| 21 | <type>/<ticket-id>-<short-description> |
| 22 | ``` |
| 23 | |
| 24 | Types: |
| 25 | - `feat/` — New feature |
| 26 | - `fix/` — Bug fix |
| 27 | - `refactor/` — Code restructuring without behavior change |
| 28 | - `docs/` — Documentation only |
| 29 | - `test/` — Adding or updating tests |
| 30 | - `chore/` — Build, CI, dependency updates |
| 31 | |
| 32 | Examples: |
| 33 | ``` |
| 34 | feat/PROJ-123-add-user-search |
| 35 | fix/PROJ-456-null-check-login |
| 36 | refactor/PROJ-789-extract-auth-module |
| 37 | chore/update-eslint-config |
| 38 | ``` |
| 39 | |
| 40 | Rules: |
| 41 | - Lowercase only |
| 42 | - Hyphens between words, not underscores |
| 43 | - Include ticket ID when one exists |
| 44 | - Keep the description under 5 words |
| 45 | - Delete branches after merging |
| 46 | |
| 47 | ## Commit messages |
| 48 | |
| 49 | ### Format |
| 50 | |
| 51 | ``` |
| 52 | <type>(<scope>): <subject> |
| 53 | |
| 54 | <body> |
| 55 | |
| 56 | <footer> |
| 57 | ``` |
| 58 | |
| 59 | ### Type (required) |
| 60 | |
| 61 | `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `style` |
| 62 | |
| 63 | ### Scope (optional) |
| 64 | |
| 65 | The module, component, or area affected: `auth`, `api`, `ui`, `db`, `ci` |
| 66 | |
| 67 | ### Subject (required) |
| 68 | |
| 69 | - Imperative mood: "add" not "added" or "adds" |
| 70 | - Lowercase first letter |
| 71 | - No period at the end |
| 72 | - Max 72 characters |
| 73 | |
| 74 | ### Examples |
| 75 | |
| 76 | ``` |
| 77 | feat(auth): add password reset flow ← feature with scope |
| 78 | fix(api): handle null user ID in session ← bug fix with scope |
| 79 | chore: update TypeScript to 5.4 ← chore, no scope needed |
| 80 | refactor(db): extract query builder module ← refactor with scope |
| 81 | ``` |
| 82 | |
| 83 | Add a body for non-trivial changes explaining WHY, not HOW. Reference tickets in the footer: `Closes #234`. |
| 84 | |
| 85 | ## Pull request template |
| 86 | |
| 87 | Use this structure for PR descriptions: |
| 88 | |
| 89 | ```markdown |
| 90 | ## What |
| 91 | [1-2 sentences: what this PR does] |
| 92 | |
| 93 | ## Why |
| 94 | [Why this change is needed — link to ticket] |
| 95 | |
| 96 | ## Testing |
| 97 | - [ ] Unit tests added/updated |
| 98 | - [ ] Manual testing performed |
| 99 | |
| 100 | ## Notes for reviewers |
| 101 | [Anything the reviewer should pay attention to] |
| 102 | ``` |
| 103 | |
| 104 | ## Merge strategies |
| 105 | |
| 106 | | Strategy | When to use | Command | |
| 107 | |----------|------------|---------| |
| 108 | | **Squash merge** | Messy branch history, want clean main | `git merge --squash branch` then commit | |
| 109 | | **Rebase merge** | Each commit is meaningful and clean | `git rebase main` then `git merge --ff-only` | |
| 110 | | **Merge commit** | Long-lived branches, need diverge/converge history | `git merge --no-ff branch` | |
| 111 | |
| 112 | Squash is the safest default for feature branches. Use rebase when commits are well-structured. Use merge commits for release branches. |
| 113 | |
| 114 | ## Key operations |
| 115 | |
| 116 | ```bash |
| 117 | # Sync branch with main (use --force-with-lease, never --force) |
| 118 | git checkout main && git pull && git checkout feat/my-branch && git rebase main |
| 119 | |
| 120 | # Undo last commit, keep changes |
| 121 | git reset --soft HEAD~1 |
| 122 | |
| 123 | # Stash work in progress |
| 124 | git stash push -m "description" |
| 125 | ``` |
| 126 | |
| 127 | ## Quality checklist |
| 128 | |
| 129 | Before opening a PR, verify: |
| 130 | |
| 131 | - [ ] Branch name follows the naming convention |
| 132 | - [ ] Commits are meaningful — no WIP, fixup, or "oops" messages left |
| 133 | - [ ] PR description follows the template with What/Why/Testing/Notes |
| 134 | - [ ] Branch is rebased on the latest main (no unnecessary merge commits) |
| 135 | - [ ] CI passes on the branch |
| 136 | - [ ] The diff contains only changes related to the stated purpose |
| 137 | |
| 138 | ## Common mistakes |
| 139 | |
| 140 | - **Committing to main directly.** Always work on a branch, even for small changes. Direct commits bypass review and CI. |
| 141 | - **Writing vague commit messages.** "Fix bug" and "Update code" tell reviewers nothing. State what changed and why. |
| 142 | - **Using force push on shared branches.** Force push overwrites remote history. Use `--force-with-lease` and never force push to main. |
| 143 | - **Letting branches go stale.** Rebase on main regularly. A branch that diverges for weeks will have painful merge conflicts. |
| 144 | - **Including unrelated changes in a PR.** One PR should do one thing. Refactoring plus a bug fix plus a new feature in one PR is unreviewable. |
| 145 | - **Not deleting merged branches.** Stale branches clutter the repository. Delete branches after they are merged. |
| 146 |