Write a description for the current jj commit.
Current commit
jj show --git
Recent descriptions
jj log -r 'ancestors(@-, 10)' --no-graph -T 'description'
Recent descriptions for the changed files
jj log -r "latest(::@- & files($(jj diff -r @ --name-only | sed 's/.*/\"&\"/' | paste -sd'|' -)), 10)" --no-graph -T 'description.first_line() ++ "\n"'
Arguments: $ARGUMENTS
Principles
- Explain why the change was made, because the diff already shows what changed
- Write the summary line so it completes the sentence "If applied, this commit
will ...": 50 characters preferred and 72 at most, no trailing period. Name
the fix rather than the problem it fixes. Avoid a filename or a generic phrase
such as "fix bug", "refactor", or "cleanups"
- Match the prefix style, capitalization, and detail of the previous commits to
the same files, falling back to the recent descriptions above where those
commits disagree. Without a consistent convention, write
<topic>: <summary>,
where the topic is the module, directory, or command the change touches
- Add a body only when the summary leaves something unexplained: the status quo
the change corrects, the motivation, how the change works, a rejected
alternative, a known limitation, or a consequence a reader would miss. Wrap it
at 72 columns, separated from the summary by a blank line
- State the status quo in the present tense and without "Currently", because a
description is read against the code before the change: "the parser stops at
the first error"
- Explain how the change works only where the diff leaves it unclear, in plain
words and at the level of the feature rather than the code
- Mention a rejected alternative only when you tried it, rather than only
considered it, and a reader would ask why you didn't take it
- Back a claim about performance or size with the measurements before and after
the change
- Leave out what the diff shows, such as which files and functions changed and
that the tests were updated
- Leave out how the commit came about, such as what was tried first, what it was
rebased onto, and what happened in the session that wrote it
- Describe the commit's own change, not the stack around it
- Keep the description readable on its own. Summarize an issue or a linked page
rather than pointing at it, and name another commit by its change ID and its
summary line rather than the ID alone
Workflow
- Read the diff above. If the commit is empty, tell the user and stop
- Treat any existing description as the author's intent: keep what it states
and extend it to cover the rest of the diff, unless the arguments ask for a
replacement
- Read the descriptions for the changed files above to see which convention
previous commits to these files followed
- Work out why the change was made. Read the surrounding code when the diff
alone doesn't explain it. Prefer the arguments over your own inference
- Run
/humanize on the planned description in a subagent, passing the text
inline and asking for the revision back. Give the subagent nothing else, so
it reads the draft cold
- Take the revision, restoring anything it dropped and rewriting a summary line
it pushed past 72 characters. Set the description with
jj describe -m '<summary>' -m '<body>', passing a second -m only for a
body. Each -m becomes its own paragraph
- Show the result with
jj log -r @ --no-graph -T 'description'
Fixing mistakes
Rerunning jj describe replaces the whole description. To recover the previous
one, find the describe operation with jj op log and revert it with
jj undo <operation>.
1---2name: jj-describe3description: Write a description for the current `jj` commit.4---56Write a description for the current `jj` commit.78# Current commit910```!11jj show --git12```1314# Recent descriptions1516```!17jj log -r 'ancestors(@-, 10)' --no-graph -T 'description'18```1920# Recent descriptions for the changed files2122```!23jj log -r "latest(::@- & files($(jj diff -r @ --name-only | sed 's/.*/\"&\"/' | paste -sd'|' -)), 10)" --no-graph -T 'description.first_line() ++ "\n"'24```2526Arguments: $ARGUMENTS2728# Principles2930- Explain why the change was made, because the diff already shows what changed31- Write the summary line so it completes the sentence "If applied, this commit32 will ...": 50 characters preferred and 72 at most, no trailing period. Name33 the fix rather than the problem it fixes. Avoid a filename or a generic phrase34 such as "fix bug", "refactor", or "cleanups"35- Match the prefix style, capitalization, and detail of the previous commits to36 the same files, falling back to the recent descriptions above where those37 commits disagree. Without a consistent convention, write `<topic>: <summary>`,38 where the topic is the module, directory, or command the change touches39- Add a body only when the summary leaves something unexplained: the status quo40 the change corrects, the motivation, how the change works, a rejected41 alternative, a known limitation, or a consequence a reader would miss. Wrap it42 at 72 columns, separated from the summary by a blank line43- State the status quo in the present tense and without "Currently", because a44 description is read against the code before the change: "the parser stops at45 the first error"46- Explain how the change works only where the diff leaves it unclear, in plain47 words and at the level of the feature rather than the code48- Mention a rejected alternative only when you tried it, rather than only49 considered it, and a reader would ask why you didn't take it50- Back a claim about performance or size with the measurements before and after51 the change52- Leave out what the diff shows, such as which files and functions changed and53 that the tests were updated54- Leave out how the commit came about, such as what was tried first, what it was55 rebased onto, and what happened in the session that wrote it56- Describe the commit's own change, not the stack around it57- Keep the description readable on its own. Summarize an issue or a linked page58 rather than pointing at it, and name another commit by its change ID and its59 summary line rather than the ID alone6061# Workflow62631. Read the diff above. If the commit is empty, tell the user and stop642. Treat any existing description as the author's intent: keep what it states65 and extend it to cover the rest of the diff, unless the arguments ask for a66 replacement673. Read the descriptions for the changed files above to see which convention68 previous commits to these files followed694. Work out why the change was made. Read the surrounding code when the diff70 alone doesn't explain it. Prefer the arguments over your own inference715. Run `/humanize` on the planned description in a subagent, passing the text72 inline and asking for the revision back. Give the subagent nothing else, so73 it reads the draft cold746. Take the revision, restoring anything it dropped and rewriting a summary line75 it pushed past 72 characters. Set the description with76 `jj describe -m '<summary>' -m '<body>'`, passing a second `-m` only for a77 body. Each `-m` becomes its own paragraph787. Show the result with `jj log -r @ --no-graph -T 'description'`7980# Fixing mistakes8182Rerunning `jj describe` replaces the whole description. To recover the previous83one, find the describe operation with `jj op log` and revert it with84`jj undo <operation>`.
TomerAberbach