ctdd/.agents/skills/git/SKILL.md

---
name: git
description: Git workflow for the ctdd C/C++ starter template. Use when
  committing template or example changes, creating release tags, or following
  the branching and commit message conventions.
---

# Git Skill

This repository is a reusable starter template for C and C++ projects.
Treat its checked-in code as examples demonstrating the build and test
setup, not as a required application API. Template releases should keep
the starter structure and Unity/CMock workflows useful to derived projects.

## Commit Messages

Follow [Conventional Commits v1.0.0][cc] with the 50/72 rule.

[cc]: https://www.conventionalcommits.org/en/v1.0.0/

### Format

```
<type>[optional scope][!]: <subject>

<body>

[BREAKING CHANGE: <description>]
Co-authored-by: <Name> <email>
```

- Subject: max 50 characters; use imperative mood and no period.
- Wrap body lines at 72 characters. Keep the message concise.
- Separate the subject from the body with a blank line.
- Use Conventional Commit types such as `feat`, `fix`, `docs`, `chore`,
  and `ci`; scopes are optional.
- Mark breaking changes with `!` and/or a `BREAKING CHANGE:` footer.
- No em dashes (`—`). Use a colon or rewrite the sentence.

Always include one `Co-authored-by:` trailer per contributing agent or
model, using `<Name> <email>`:

- Name: human-readable model name, e.g. `Qwen 3.8 27B`.
- Email local part: lowercase model identifier, replacing invalid
  characters with dots. If the model is unknown, use the product name.
- Email domain: the service that ran the model, using its real domain.
  For self-hosted services, use your own domain. Use
  `<runtime>.local` only for local inference with no service domain.

Examples:

```
Co-authored-by: Qwen 3.8 27B <qwen3.8.q3_k_xl@lmstudio.local>
Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
Co-authored-by: Claude Sonnet 4.5 <claude.sonnet4.5@github.com>
```

The corporate commit-msg hook rejects these trailers, agent email
addresses, `.local` domains, and free-text descriptions. Skip the hook
with `--no-verify` when committing.

### Types

| Type       | Use                                |
| ---------- | ---------------------------------- |
| `feat`     | New feature or module              |
| `fix`      | Bug fix                            |
| `docs`     | Documentation only                 |
| `chore`    | Build, deps, config, housekeeping  |
| `ci`       | CI/CD changes                      |
| `refactor` | Code change without feature or fix |
| `test`     | Adding or changing tests           |
| `style`    | Formatting, whitespace, semicolons |

### Examples

Good:

```
feat: add stopwatch timer

Replace Hello World with a live stopwatch that prints elapsed time
in HH:MM:SS.mmm format, updating every 10ms with color output.

Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
```

```
fix: clear Unity INTERFACE_SYSTEM_INCLUDE_DIRECTORIES

CMake rejects the path inside the build tree on newer versions.

Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
```

```
chore: bump CMock to v2.6.0

Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
```

Bad:

```
added a new thing              # no type, lowercase, vague
feat: add stopwatch             # no body for a significant change
feat: add stopwatch timer.      # trailing period
feat: add timer — it's fast     # em dash not allowed
```

## Committing

Stage changes:

```sh
git add -A
```

Write the complete message, including co-author trailers, to a message
file, then commit while skipping the rejecting hook:

```sh
git commit --no-verify -F <message-file>
```

## Tagging

This project uses semantic versioning for template releases.

### Creating a tag

Create the tag:

```sh
git tag -a v0.1.0 -m "Release v0.1.0"
```

Push the tag:

```sh
git push origin v0.1.0
```

Tag messages follow the same rules as commit messages: no em dashes,
wrapped at 72 characters.

### Tag naming

| Version  | Meaning                              |
| -------- | ------------------------------------ |
| `v0.x.0` | Minor changes, breaking template API |
| `v0.x.y` | Patch changes, backward-compatible   |
| `v1.x.0` | Major release                        |

### When to tag

- After merging a feature branch that changes the template structure
- Before sharing the template with others
- When CMakeLists.txt, deps/, or build system changes could affect
  projects using this template

### Listing tags

```sh
git tag -l
```

### Deleting a tag

Delete the local tag:

```sh
git tag -d v0.1.0
```

Remove the remote tag:

```sh
git push origin --delete v0.1.0
```

## Branching

For local development:

```sh
git checkout -b feat/add-counter
```

Branch naming:

| Prefix   | Use           |
| -------- | ------------- |
| `feat/`  | New feature   |
| `fix/`   | Bug fix       |
| `chore/` | Housekeeping  |
| `docs/`  | Documentation |

## Common Commands

| Command                 | Use                               |
| ----------------------- | --------------------------------- |
| `git log --oneline -10` | Recent history                    |
| `git diff --staged`     | Check staged changes              |
| `git status`            | Current state                     |
| `git reset HEAD~1`      | Undo last commit (keep changes)   |
| `git rebase -i HEAD~3`  | Interactive rebase last 3 commits |

## Checklist Before Committing

- [ ] Tests pass: `ninja -C build check`
- [ ] Commit message follows 50/72 rule
- [ ] Conventional commit type used
- [ ] Co-author trailer for every contributing agent or model
- [ ] No em dashes
- [ ] No large unchanged regions reformatted
- [ ] No speculative code or unused imports