git-workflow v1.0.0B

Immutable. This exact content is served forever at /api/v1/blob/f4863c55ff07d186.

---
description: >
name: git-workflow
version: 1.0.0
tags:
  - git
  - version-control
  - conventional-commits
  - branching
  - pull-request
metadata:
  skill-author: 'Marie-Lynne Block'
---

## What this skill does

Covers the full git workflow for a software project: branch naming conventions, commit message authoring (Conventional Commits standard), PR description templates, and merge strategy advice. It produces ready-to-use git artefacts, not generic advice.

## When to use it

- User wants to write a commit message for a set of changes.
- User asks about branch naming, PR conventions, or merge strategy.
- User wants to set up or document a git workflow for a project.
- User wants a PR description written from a diff or change summary.

## Key concepts

### Conventional Commits

Format: `<type>(<scope>): <description>`

| Type | When to use |
| --- | --- |
| `feat` | A new feature visible to users or consumers |
| `fix` | A bug fix |
| `docs` | Documentation only |
| `style` | Formatting, whitespace — no logic change |
| `refactor` | Code restructure with no behaviour change |
| `perf` | Performance improvement |
| `test` | Adding or fixing tests |
| `chore` | Build, tooling, dependency updates |
| `ci` | CI/CD pipeline changes |
| `revert` | Reverts a previous commit |

Rules:
- Description is lowercase, imperative mood, no trailing period: `fix: handle null session token` not `Fixed the null session token issue.`
- Scope is optional but recommended for multi-module repos: `feat(auth): add OAuth2 login`
- Breaking changes: append `!` after type/scope and add `BREAKING CHANGE:` footer: `feat(api)!: remove v1 endpoint`
- Body and footer are separated from subject by a blank line.

### Branch naming

Pattern: `<type>/<short-description>` using the same type vocabulary as Conventional Commits.

Examples: `feat/guest-checkout`, `fix/null-session-token`, `chore/upgrade-dependencies`, `docs/api-reference`

Rules:
- Use hyphens, not underscores or slashes within the description.
- Keep it short enough to read in a terminal (under 50 characters total).
- Include a ticket reference if the team uses one: `feat/PROJ-123-guest-checkout`.

### Merge strategies

| Strategy | When to use |
| --- | --- |
| **Merge commit** | Preserves full branch history; good for long-lived feature branches |
| **Squash and merge** | Clean linear history; good for small features or fix PRs |
| **Rebase and merge** | Linear history without squashing; good when individual commits are meaningful |

## Instructions

### Writing a commit message

1. Identify the type from the change description.
2. Identify the scope if the repo has modules or packages.
3. Write the subject line: `<type>(<scope>): <imperative description>`.
4. If the change needs explanation (why, not what), add a body paragraph.
5. Add a footer for breaking changes, issue references (`Closes #123`), or co-authors.

### Writing a PR description

1. State what the PR does in one sentence (mirrors the commit subject if squashing).
2. Add a "Why" section if the motivation is not obvious from the title.
3. List the key changes as bullet points.
4. Add a test plan: what was tested and how.
5. Note any follow-up work or known limitations.

### Advising on workflow setup

1. Recommend a branching model based on team size and release cadence:
   - Small team / continuous deployment → trunk-based development with short-lived feature branches.
   - Larger team / scheduled releases → Gitflow or a simplified variant.
2. Recommend a merge strategy consistent with the model.
3. Suggest protected branch rules (require PR, require review, require CI pass).

## Output format

### Commit message

```
<type>(<scope>): <description>

[optional body — explain why, not what]

[optional footer — BREAKING CHANGE, Closes #NNN, Co-authored-by]
```

### PR description

```markdown
## What

[One sentence: what this PR does.]

## Why

[Why this change is needed — link to issue or ticket if applicable.]

## Changes

- [Key change 1]
- [Key change 2]

## Test plan

- [ ] [What was tested and how]
- [ ] [Edge case verified]

## Notes

- [Follow-up work, known limitations, or deployment considerations]
```

### Branch name

```
<type>/<short-description>
```

## Examples

### Example 1 — Commit message from a change description

**Input:** "I added a price filter to the search results page. It filters by min and max price and preserves the filter when navigating back."

**Expected output:**
```
feat(search): add price range filter to results page

Preserves min/max values on browser back navigation so users
do not lose their filter context between page visits.
```

### Example 2 — PR description from a diff summary

**Input:** "Fixed a bug where the session token was not cleared on logout, leaving users authenticated after clicking sign out."

**Expected output:**
```markdown
## What
Fix session token not cleared on logout.

## Why
Users remained authenticated after signing out because the token cookie
was not explicitly expired. Closes #412.

## Changes
- Expire session cookie with `Max-Age=0` on logout handler
- Add integration test for post-logout authenticated request

## Test plan
- [ ] Log in, click sign out, attempt to access protected route — expect 401
- [ ] Verify cookie is absent in browser DevTools after logout
```

## Notes

- Commit messages are read by humans in `git log` and by tools (changelogs, release notes, semantic versioning). Write for both audiences.
- Never include "WIP" or "temp" in a commit that will land on the main branch.
- If the user's repo has an existing commit style, match it — do not impose Conventional Commits without noting the deviation.
- For monorepos, the scope is the package or service name, not a file path.