commit 487719d77dd6a53408e8eeca15825f0cc2d231f2 equwal <13551856+equwal@users.noreply.github.com> 2026-10-04 07:13:22 -0700 Patches rule: show applied diffs inline; only unapplied patches as a runnable command
rules/patches.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/rules/patches.md b/rules/patches.md index 79781c3..54017d8 100644 --- a/rules/patches.md +++ b/rules/patches.md @@ -1,10 +1,12 @@ -## MANDATORY: Give changes as patches the user can run +## MANDATORY: Show changes as readable diffs; give unapplied patches as a runnable command -When you show the user a change to a file, give it as a unified diff inside a command that applies it. The user runs it with one click. Never show a bare diff the user cannot execute, and never give loose code lines or whole files. +Two cases. Never give loose code lines or whole files. -- Put the whole patch in one fenced block tagged `bash` (the desktop app adds a Run button only to `bash` blocks). Never tag it `diff`, `text`, or leave it untagged. -- The block is one complete command: `cd DIR && patch -p1 <<'EOF'` ... `EOF`, with the correct `-p` level and an absolute `DIR`. For a file on another host: `ssh HOST 'cd DIR && patch -p1' <<'EOF'` ... `EOF`. -- Make the diff with `diff -u` or `git diff`, so each hunk has context lines and a `@@` header with line numbers. Check it applies (`patch --dry-run`) before you show it. -- Already applied? Do not show a diff the user would re-apply. Give a runnable command that shows the change in color instead, for example `ssh HOST 'git -C DIR --no-pager show --color COMMIT'`. -- Give a whole file only when the file is new or the user asks for the whole file; then give a runnable command that writes it. -- This rule is for changes you show the user. When you edit files yourself, use your edit tools as usual. +**Change you already made (applied).** Show the diff inline, in a fenced block tagged `diff`, so the user reads it with color and no command. Do not make him run a command (`git show`, `diff -u`, `cat`) just to see a change. + +**Change the user must apply** (you could not apply it: denied, blocked, needs his hands or another host). Give one fenced block tagged `bash` (the desktop app adds a Run button only to `bash` blocks) that applies it: `cd DIR && patch -p1 <<'EOF'` ... `EOF`, or `ssh HOST 'cd DIR && patch -p1' <<'EOF'` ... `EOF` for another host. Use an absolute `DIR` and the correct `-p` level. The patch text inside is the diff, so he can read it before he runs it. + +- Make diffs with `diff -u` or `git diff`, with context lines and `@@` headers with line numbers. Check an unapplied patch with `patch --dry-run` before you show it. +- Long diffs: show the relevant hunks inline and say how many lines/files you left out. +- Give a whole file only when the file is new or the user asks for the whole file. +- When you edit files yourself, use your edit tools as usual; this rule is about what you show the user.