commit-msg

name	commit-msg
description	Generate a commit message for the current changes. Use when committing or when asked to draft a commit message.

Commit Messages

Generate a commit message for the current changes. Follow these steps:

1. Detect the repo type: run sl root (success = Sapling/hg repo), otherwise git.
2. Review the current diff to understand what changed.
3. Draft the commit message using the rules and format below.

Title (subject line)

• Concise and specific. Aim for ~72 characters. Imperative mood ("Fix bug", not "Fixed bug").
• No backticks or Markdown formatting in the title — plain text only. Markdown belongs in the Summary (below).
• In Sapling/hg repos, prefix with [area] bracket tags (see Title tags).

Summary (description)

Keep it proportionate. Most diffs need only a paragraph or two — subheadings and a Changes list are opt-in, for genuinely multi-faceted diffs, not a template to fill. A trivial change needs one line (plus the Changelog: trailer); don't pad.

Front-load the why. The first sentence should let a reader who stops there understand the diff.

Stay high-level. Describe the change at the altitude a reviewer reasons about it — by concern and behavior, not file by file. Group related edits; collapse bulk or mechanical changes into a single bullet with a count (e.g. "Repoint deep type imports to the public root API — 146 files") rather than listing them. If a bullet list is turning into a file inventory, it's too granular — summarize.

Use bold subheadings to organize longer summaries — each **Heading** on its own line with a blank line before and after:

**Motivation**

Why this change is worth making.

**This diff**

What this diff does about it.

Short summaries need no subheadings — don't force structure where a plain paragraph suffices. Choose from these as needed:

Subheading	When to use
Context	Background for follow-up diffs or stacked changes.
Motivation	Why this change is worth making — the user pain or technical driver.
Problem / Root cause / Fix	Bug narratives. Use the subset that fits — all three for complex bugs, just Problem + Fix for straightforward ones.
This diff	What specifically this diff does, when Context sets up a broader effort.
Changes	A short list of distinct changes, grouped by concern; omit if a sentence covers it.
Impact	What this means for users, performance, or downstream consumers.
Notes	Caveats, limitations, or remaining work.

• Do use backticks in the summary — API names, packages, paths, flags, files.
• Use Before/After tables for visual or behavioral comparisons.
• Reference prior work concisely: "Follows D1234" or "Follow-up to #1234".

Title tags (Sapling/hg only)

Prefix the title with one or more [area] bracket tags. Tags are hierarchical — broadest area first, narrowing by sub-area, feature, or platform.

To choose the right tags, check the commit history of the changed files and their parent folders (e.g. sl log -l 10 path/to/file).

• Use the project/repo shorthand as the primary tag (e.g. [RN], [metro]).
• Stack additional tags for sub-area, feature, or platform: [RN][scripts], [RN][Network Inspection][Android].
• Platform tags go last: [Android], [iOS].
• Use lowercase for standalone projects or packages: [react_cdp_tools], [dev-middleware].
• Omit the project tag when obvious from context (e.g. single-project repo).
• Tags don't count toward the ~72-character title target — measure only the text after them.

Examples: [RN] Narrow file set for no-commonjs-exports lint rule, [RN][Network Inspection][Android] Add onCreateRequest compatibility overload.

React Native conventions

• Internal changes: include Changelog: [Internal] in the summary.
• Public changes: use a changelog category, e.g. Changelog: [Android][Fixed] - ....
• Do not include "Differential Revision" lines — those are managed separately.

Committing

Always re-read the current commit or diff message (e.g. git log -1 --format="%B", sl log -r . -T '{desc}', jf sync) before overwriting it. The user may have edited it outside Claude Code.

When asked to commit, use the generated message directly:

# Sapling — with summary:
sl commit -m "<Title>" --message-field "Summary=<Summary>"
# Sapling — without summary:
sl commit -m "<Title>"

# Git — with summary:
git commit -m "<Title>" -m "<Summary>"
# Git — without summary:
git commit -m "<Title>"