Commit Message Skill

Purpose

Stage all relevant changes and create a git commit whose message matches the format already established in this repository: a conventional-commit subject line followed by a structured body that groups changes by category.

This skill is intentionally written in plain, agent-agnostic language so it can be followed by Claude Code, Gemini CLI, Codex, Qwen, opencode, or any other LLM-based coding agent.

---

Step 1 — Gather context

Run the following commands and keep their output in mind for the rest of the process. Do not skip any of them.

# Learn the repo's commit message format and subject-line style
git log --oneline -10

# Identify every file that has changed since the last commit
git diff --stat HEAD

# See the full diff for changed files that need to be understood
git diff HEAD

# Confirm which branch you are on
git branch --show-current

---

Step 2 — Determine the commit type

Inspect the nature of the changes and pick exactly one conventional-commit type prefix that fits:

Prefix	Use when
feat	A new feature or capability is added
fix	A bug, warning, or incorrect behavior is corrected
chore	Build system, dependencies, CI, or tooling changes
refactor	Code restructuring with no functional change
test	Tests added or updated
docs	Documentation only
perf	Performance improvements
style	Formatting/whitespace with no logic change

If the changes span multiple types but share a single theme (e.g., fixing many warnings across many files), use the dominant type (fix) and document the breadth in the body.

---

Step 3 — Write the subject line

Format: <type>: <short imperative summary>

Rules:

• 72 characters maximum.
• Imperative mood ("fix", "add", "remove" — not "fixed", "adds", "removes").
• No trailing period.
• Specific enough to distinguish this commit from adjacent commits in git log --oneline.

Examples from this repo:

fix: silence compiler warnings across GCC and Clang
fix: silence compiler warnings in RI pipeline
fix: clang warnings and thread linkage
chore: add project identity macros and use them
test: split teapot motion for raytrace and REYES

---

Step 4 — Write the body

The body follows the subject line after one blank line. It must:

1. Open with a one-sentence description of the overall goal or motivation (the "why", not the "what").

2. Group individual changes by category, each group introduced with a short heading followed by bullet points. Category examples:

   • Warning class (e.g., -Wsequence-point, -Wunused-result)
   • Subsystem (e.g., CMake / Clang alignment, Build system)
   • Feature area (e.g., Shader pipeline, Network layer)

3. List files or modules affected within each bullet, concisely. Prefer naming patterns over individual filenames when many files share the same fix (e.g., "brickmap.cpp, debug.cpp, texture.cpp" or "all fread() callers in the RI pipeline").

Body line width: 72 characters maximum (wrap prose, but keep code snippets on one line even if longer).

---

Step 5 — Stage files

Stage specific files by name. Do not use git add -A or git add . unless you have verified that every untracked file in the working tree should be committed.

Never stage:

• .env files or any file that may contain credentials or secrets
• Binary build artifacts (*.o, *.a, *.so, *.dylib)
• IDE workspace files (.vscode/, .idea/, *.swp)
• CMake build directory contents (build/, CMakeCache.txt, etc.)

Inspect git status and git diff --stat HEAD to identify exactly which files belong to this commit.

---

Step 6 — Create the commit

Use a HEREDOC to pass the message so multi-line formatting is preserved exactly as written. Replace <Agent Name> and <agent@email> with the appropriate attribution for the agent performing the commit.

git commit -m "$(cat <<'EOF'
<type>: <subject line>

<one-sentence motivation / overall goal>

<Category heading 1>:
  - <change description, files affected>
  - <change description, files affected>

<Category heading 2>:
  - <change description, files affected>
EOF
)"

---

Step 7 — Verify

After the commit succeeds, run:

git log --oneline -3

Confirm the new commit appears at the top with the correct subject line and that git status shows a clean working tree (or only intentionally unstaged files).

---

Complete example

This is the exact commit produced for the warning-fixes batch in this repository. Use it as a reference for tone, level of detail, and grouping structure:

fix: silence compiler warnings across GCC and Clang

Systematically eliminate all -Wall/-Wextra/-Wpedantic warnings produced
by GCC 13 on Linux and align Clang/AppleClang flag coverage to surface
the same diagnostics on macOS builds.

Warning categories addressed:

- -Wsequence-point / -Wunsequenced: fix *ptr++ = (*ptr) * k UB pattern
  in renderer.h, curves.cpp, bsplinePatchgrid.cpp, patches.cpp,
  subdivision.cpp; replace with local capture before increment

- -Wunused-result (fread): wrap all discarded fread() calls in if()
  checks with /* read error */ body across brickmap.cpp, debug.cpp,
  precomp.cpp, texture.cpp, texmake.cpp, fileResource.cpp,
  irradiance.cpp, remoteChannel.cpp, rendererNetwork.cpp, show.cpp,
  map.h (template — fixes all instantiation sites at once)

- -Wmaybe-uninitialized / -Wuninitialized: add = nullptr / = 0 / = {}
  initializers to variables in execute.cpp, executeMisc.cpp,
  shaderOpcodes.h, shaderFunctions.h, giFunctions.h, surface.cpp,
  linsys.cpp, occlusion.cpp, polygons.cpp, pointHierarchy.cpp,
  stochasticQuad.h

- -Wdeprecated-declarations: replace libtiff uint32/uint16 typedef
  aliases with uint32_t/uint16_t in texture.cpp and texmake.cpp

- -Wformat-truncation: resize buffers in sdr.y (tmp[]) and
  rendererFiles.cpp (tmp[OS_MAX_PATH_LENGTH+1])

- -Wimplicit-fallthrough: add __attribute__((fallthrough)) in fbx.cpp,
  pp1.c, pp2.c; fix sl.y null-pointer init

- -Wempty-body: wrap assert(FALSE) else-branches in braces in
  rendererDeclerations.cpp

- -Wsign-compare: cast fread return comparison to size_t in texture.cpp

- -Wsizeof-pointer-memaccess: replace sizeof(scratch) with
  ribOutScratchSize in ribOut.h; add extern declaration

- -Wunknown-pragmas: guard #pragma clang diagnostic in ri.cpp with
  #ifdef __clang__

- -Wunused-variable: move invBezier/dinvBezier from patchUtils.h into
  the single .cpp that uses each; fixes a real copy-paste bug in
  quadrics.cpp (Pstart written instead of Pend for motion blur)

CMake / Clang alignment (CMakeLists.txt, src/oshader/CMakeLists.txt):
  add -Wunused-but-set-variable, -Wunsequenced, -Wimplicit-fallthrough
  for Clang/AppleClang so the same diagnostic categories surface on
  macOS builds without loosening any existing flags

---

Quick-reference checklist

Before running git commit, confirm:

• git log --oneline -10 reviewed — subject style matches repo conventions
• Subject line ≤ 72 chars, imperative mood, correct type: prefix
• Body opens with a motivation sentence
• Changes grouped by category with bullet points
• No secrets, binaries, or build artifacts staged
• HEREDOC used to pass the message (preserves newlines)