git-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Workflow

## Conventional Commit Format

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

[optional body]

[optional footer(s)]
```

### Commit Types

| Type       | Purpose                                      | Example                                      |
|------------|----------------------------------------------|----------------------------------------------|
| `feat`     | New feature for the user                     | `feat(auth): add OAuth2 login flow`          |
| `fix`      | Bug fix for the user                         | `fix(cart): correct quantity calculation`     |
| `refactor` | Code change that neither fixes nor adds      | `refactor(api): simplify request middleware`  |
| `docs`     | Documentation only changes                   | `docs(readme): add setup instructions`       |
| `test`     | Adding or correcting tests                   | `test(auth): add login failure scenarios`    |
| `chore`    | Maintenance tasks, dependencies              | `chore(deps): upgrade lodash to 4.17.21`    |
| `perf`     | Performance improvement                      | `perf(query): add index for user lookup`     |
| `style`    | Formatting, whitespace, semicolons           | `style(lint): fix indentation in models`     |
| `ci`       | CI configuration and scripts                 | `ci(actions): add Node 20 to test matrix`    |
| `revert`   | Reverts a previous commit                    | `revert: revert feat(auth) commit abc123`    |

### Commit Message Rules

- Subject line: max 72 characters, imperative mood, no trailing period
- Body: wrap at 80 characters, explain what and why (not how)
- Footer: reference issues with `Closes #123` or `Refs #456`
- Breaking changes: add `BREAKING CHANGE:` in the footer or `!` after type

```
feat(api)!: change authentication endpoint response shape

The /auth/login endpoint now returns a nested token object instead
of a flat structure. This aligns with our OAuth2 token standard.

BREAKING CHANGE: response.token is now response.auth.access_token
Closes #892
```

## Commit Atomicity

Each commit must represent exactly one logical change.

- [ ] Address a single concern (one bug fix, one feature slice, one refactor)
- [ ] Leave the codebase in a working state (tests pass, code compiles)
- [ ] Be revertable without side effects on unrelated code
- [ ] Include related test changes alongside the code change
- [ ] Never mix formatting with logic changes
- [ ] Never bundle unrelated bug fixes together

```bash
# Stage specific hunks, specific files, then verify
git add -p
git add src/auth/login.ts src/auth/login.test.ts
git diff --cached
```

## Interactive Rebase

```bash
git rebase -i HEAD~5      # Rebase last N commits
git rebase -i main        # Rebase onto a branch
```

### Rebase Commands

| Command    | Short | Effect                                          |
|------------|-------|-------------------------------------------------|
| `pick`     | `p`   | Keep the commit as-is                           |
| `reword`   | `r`   | Keep the commit but edit the message            |
| `edit`     | `e`   | Pause to amend the commit (add files, split)    |
| `squash`   | `s`   | Merge into the previous commit, keep message    |
| `fixup`    | `f`   | Merge into previous commit, discard message     |
| `drop`     | `d`   | Remove the commit entirely                      |

**Squash WIP commits:**
```
pick   a1b2c3d feat(auth): add login endpoint
fixup  e4f5g6h wip
fixup  i7j8k9l fix tests
```

**Fixup a commit further back:**
```bash
git commit --fixup=<target-sha>
git rebase -i --autosquash main
```

**Split a commit (mark as "edit"):**
```bash
git reset HEAD~1
git add src/models/user.ts
git commit -m "refactor(models): extract user validation"
git add src/routes/auth.ts
git commit -m "feat(auth): add login route"
git rebase --continue
```

## Merge vs Rebase

| Use Rebase                                   | Use Merge                                         |
|----------------------------------------------|---------------------------------------------------|
| Updating feature branch from main            | Integrating feature branch into main (`--no-ff`)  |
| Cleaning up local commits before pushing     | Shared branches others have based work on         |
| Maintaining linear history on personal branch | Preserving context of parallel development        |

- Never rebase commits pushed to a shared branch
- Always rebase local work before pushing
- Use `git pull --rebase` to avoid unnecessary merge commits

```bash
git checkout feature/login && git rebase main          # Update feature
git checkout main && git merge --no-ff feature/login   # Merge feature
```

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources