emacs-patch-review
Port of Thunderbird Patch Review to mu4e.
git clone git://mccd.space/emacs-patch-reviewcommit 53b651a74f1f8ddf2b61815710973526d0975366
parent d931179501ec72ed4fd235007c1946c30335dc2f
Author: Pi Agent <agent@pi.local>
Date: Wed, 5 Aug 2026 13:09:47 +0200
Replace README.org with README.html
Match the thunderbird-review-ui style: a hand-written, w3m-renderable
<dl> document instead of Org.
Diffstat:
| A | README.html | | | 125 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | README.org | | | 130 | ------------------------------------------------------------------------------- |
2 files changed, 125 insertions(+), 130 deletions(-)
diff --git a/README.html b/README.html
@@ -0,0 +1,125 @@
+<dl>
+ <!-- You can render this document in a HTML renderer like w3m -->
+ <dt>patch-review.el</dt>
+ <dd>Review git patches from email in Emacs</dd>
+ <dt>Synopsis</dt>
+ <dd>An Emacs port of the <a
+ href="https://git.sr.ht/~marcc/thunderbird-review-ui">Thunderbird
+ Patch Review</a> add-on. Open a patch email, type review comments
+ directly into the diff, send the review as an interleaved
+ mailing-list reply, and apply the patch to a local repository with
+ git-am(1).</dd>
+
+ <dd>Unlike the Thunderbird version, no privileged "host" component
+ is needed: Emacs runs git directly, diff-mode provides the
+ rendering, and message-mode the composition.</dd>
+
+ <dt>Installation</dt>
+ <dd><p>Clone and add to load-path:</p>
+ <pre><kbd>(add-to-list 'load-path "/path/to/emacs-patch-review")
+(require 'patch-review) ; core, diff-mode derived
+(require 'patch-review-mu4e) ; optional mu4e integration</kbd></pre>
+ <p>Requires Emacs 28.1+, git, and diffutils. Requires mu4e only
+ for the mail adapter.</p></dd>
+
+ <dt>Usage from mu4e</dt>
+ <dd><p>In a *mu4e-view* buffer showing a patch:</p>
+ <pre><kbd>(define-key mu4e-view-mode-map (kbd "R") #'patch-review-mu4e-review)</kbd></pre></dd>
+
+ <dt>Usage from a file</dt>
+ <dd>Opening a .patch or .diff file activates patch-review-mode (via
+ auto-mode-alist). <kbd>M-x patch-review-open-message-file</kbd>
+ handles raw .eml messages.</dd>
+
+ <dt>Reviewing</dt>
+ <dd><p>The review buffer is an ordinary, editable diff-mode buffer
+ holding the patch body. There is no "add comment" command: press
+ RET anywhere and type. Text you insert is your commentary; the
+ patch text stays untouched. Text inserted above the first hunk
+ becomes a general remark.</p>
+
+ <p>When you send (<kbd>C-c C-c</kbd>), the buffer is diffed against
+ the pristine original. Your insertions are extracted, anchored to
+ the patch line above them, and formatted as an interleaved reply —
+ quoted hunks with > prefix, comments underneath, kernel
+ style:</p>
+
+ <pre>Looks good overall, two nits.
+
+> diff --git a/src/socket.c b/src/socket.c
+> @@ -1,15 +1,20 @@
+> #include <stdio.h>
+> +#include <errno.h>
+
+Is errno.h needed on all platforms?</pre>
+
+ <p>The outgoing mail is composed from the pristine text, so
+ accidental edits to the patch itself can never corrupt the quote
+ (they are reported before sending). The reply lands in a
+ message-mode buffer; send it with <kbd>C-c C-c</kbd> again.</p></dd>
+
+ <dt>Applying</dt>
+ <dd>The header line shows the target project and whether the patch
+ applies to it (probed by running git-am(1) in a throwaway detached
+ worktree — your repository is never touched by the probe).</dd>
+
+ <dt>Controls</dt>
+ <dd><table>
+ <tr><th>Key</th><th>Action</th></tr>
+ <tr><td><kbd>C-c C-c</kbd></td><td>extract comments, compose review reply</td></tr>
+ <tr><td><kbd>C-c C-a</kbd></td><td>apply patch to the project with git-am(1)</td></tr>
+ <tr><td><kbd>C-u C-c C-a</kbd></td><td>apply with user git hooks suppressed</td></tr>
+ <tr><td><kbd>C-c C-p</kbd></td><td>set/switch the target project</td></tr>
+ <tr><td><kbd>C-c C-r</kbd></td><td>re-run the applicability probe</td></tr>
+ </table>
+
+ <p>Plus all of diff-mode's navigation (<kbd>M-n</kbd> /
+ <kbd>M-p</kbd> between hunks, <kbd>C-c C-b</kbd> word-level
+ refinement, ...).</p>
+
+ <p>Status values: applies cleanly, already applied, worktree dirty,
+ conflicts, am in progress, no project.</p></dd>
+
+ <dt>Design notes</dt>
+ <dd><ul>
+ <li>Comment extraction uses an anchored diff(1) -U0 between the
+ pristine and edited buffer; pure insertions become comments at
+ the original line above them. Deletions/modifications of patch
+ text are counted and confirmed before sending.</li>
+ <li>The applicability probe mirrors the Thunderbird add-on's
+ patchHost: git-diff-index(1) --quiet HEAD for dirtiness, then
+ git-am(1) in a temporary --detach worktree with core.hooksPath
+ pointed at an empty directory (probes must not run user hooks
+ against unreviewed patch content). git-am(1) itself gives the
+ tri-state: "Patch already applied", exit 0, or exit 128.</li>
+ <li>Applying runs the user's hooks (a deliberate act); the
+ prefix argument suppresses them. Applying refuses to run while a
+ previous git-am(1) session is unfinished (rebase-apply/ present)
+ instead of aborting it.</li>
+ </ul></dd>
+
+ <dt>Roadmap</dt>
+ <dd><ul>
+ <li>Series collection: gather [PATCH n/m] siblings of the same
+ thread (mu find), review and apply the whole series at once
+ (concatenated mbox, matching git-am(1) semantics).</li>
+ <li>Sourcehut integration: X-Sourcehut-Patchset-Update header on
+ send.</li>
+ <li>Asynchronous applicability probe.</li>
+ <li>Optional apply via <a
+ href="https://docs.kyleam.com/piem/">piem</a>.</li>
+ </ul></dd>
+
+ <dt>Development</dt>
+ <dd><p>Run the tests:</p>
+ <pre><kbd>make test</kbd></pre>
+ <p>Commits are atomic: one logical change per commit, and make
+ test passes at every commit.</p></dd>
+
+ <dt>License</dt>
+ <dd>GPLv3. See the Thunderbird project for the original
+ implementation.</dd>
+
+ <dt>Author</dt>
+ <dd>Marc Coquand</dd>
+</dl>
diff --git a/README.org b/README.org
@@ -1,130 +0,0 @@
-#+TITLE: patch-review.el — review git patches from email in Emacs
-#+AUTHOR: Marc Coquand
-
-An Emacs port of the [[https://git.sr.ht/~marcc/thunderbird-review-ui][Thunderbird Patch Review]]
-add-on. Open a patch email, type review comments directly into the diff,
-send the review as an interleaved mailing-list reply, and apply the patch
-to a local repository with =git am=.
-
-Unlike the Thunderbird version, no privileged "host" component is needed:
-Emacs runs git directly, =diff-mode= provides the rendering, and
-=message-mode= the composition.
-
-* Installation
-
-Clone and add to =load-path=:
-
-#+begin_src elisp
-(add-to-list 'load-path "/path/to/emacs-patch-review")
-(require 'patch-review) ; core, diff-mode derived
-(require 'patch-review-mu4e) ; optional mu4e integration
-#+end_src
-
-Requires Emacs 28.1+, git, and diffutils. Requires mu4e only for the
-mail adapter.
-
-* Usage
-
-** From mu4e
-
-In a =*mu4e-view*= buffer showing a patch:
-
-#+begin_src elisp
-(define-key mu4e-view-mode-map (kbd "R") #'patch-review-mu4e-review)
-#+end_src
-
-** From a file
-
-Opening a =.patch= or =.diff= file activates =patch-review-mode= (via
-=auto-mode-alist=). =M-x patch-review-open-message-file= handles raw
-=.eml= messages.
-
-** Reviewing
-
-The review buffer is an ordinary, editable =diff-mode= buffer holding the
-patch body. There is no "add comment" command: *press RET anywhere and
-type*. Text you insert is your commentary; the patch text stays
-untouched. Text inserted above the first hunk becomes a general remark.
-
-When you send (=C-c C-c=), the buffer is diffed against the pristine
-original. Your insertions are extracted, anchored to the patch line above
-them, and formatted as an interleaved reply — quoted hunks with =>=
-prefix, comments underneath, kernel style:
-
-#+begin_example
-Looks good overall, two nits.
-
-> diff --git a/src/socket.c b/src/socket.c
-> @@ -1,15 +1,20 @@
-> #include <stdio.h>
-> +#include <errno.h>
-
-Is errno.h needed on all platforms?
-#+end_example
-
-The outgoing mail is composed from the *pristine* text, so accidental
-edits to the patch itself can never corrupt the quote (they are reported
-before sending). The reply lands in a =message-mode= buffer; send it with
-=C-c C-c= again.
-
-** Applying
-
-The header line shows the target project and whether the patch applies to
-it (probed by running =git am= in a throwaway detached worktree — your
-repository is never touched by the probe).
-
-** Controls
-
-| Key | Action |
-|-----------+-----------------------------------------------|
-| =C-c C-c= | extract comments, compose review reply |
-| =C-c C-a= | apply patch to the project with =git am= |
-| =C-u C-c C-a= | apply with user git hooks suppressed |
-| =C-c C-p= | set/switch the target project |
-| =C-c C-r= | re-run the applicability probe |
-
-Plus all of =diff-mode='s navigation (=M-n= / =M-p= between hunks,
-=C-c C-b= word-level refinement, ...).
-
-Status values: =applies cleanly=, =already applied=, =worktree dirty=,
-=conflicts=, =am in progress=, =no project=.
-
-* Design notes
-
-- Comment extraction uses an anchored =diff -U0= between the pristine and
- edited buffer; pure insertions become comments at the original line
- above them. Deletions/modifications of patch text are counted and
- confirmed before sending.
-- The applicability probe mirrors the Thunderbird add-on's patchHost:
- =git diff-index --quiet HEAD= for dirtiness, then =git am= in a
- temporary =--detach= worktree with =core.hooksPath= pointed at an empty
- directory (probes must not run user hooks against unreviewed patch
- content). =git am= itself gives the tri-state: "Patch already applied",
- exit 0, or exit 128.
-- Applying runs the user's hooks (a deliberate act); =C-u= suppresses
- them. Applying refuses to run while a previous =git am= session is
- unfinished (=rebase-apply/= present) instead of aborting it.
-
-* Roadmap
-
-- Series collection: gather =[PATCH n/m]= siblings of the same thread
- (mu find), review and apply the whole series at once (concatenated
- mbox, matching =git am= semantics).
-- Sourcehut integration: =X-Sourcehut-Patchset-Update= header on send.
-- Asynchronous applicability probe.
-- Optional apply via [[https://docs.kyleam.com/piem/][piem]].
-
-* Development
-
-Run the tests:
-
-#+begin_src sh
-make test
-#+end_src
-
-Commits are atomic: one logical change per commit, and =make test=
-passes at every commit.
-
-* License
-
-GPLv3. See the Thunderbird project for the original implementation.