1  .TH "RAD\-PATCH" "1" "2025-09-23" "rad 1.0.0" "Radicle CLI Manual"
  2  .ie \n(.g .ds Aq \(aq
  3  .el       .ds Aq '
  4  .ss \n[.ss] 0
  5  .nh
  6  .ad l
  7  .de URL
  8  \fI\\$2\fP <\\$1>\\$3
  9  ..
 10  .als MTO URL
 11  .if \n[.g] \{\
 12  .  mso www.tmac
 13  .  am URL
 14  .    ad l
 15  .  .
 16  .  am MTO
 17  .    ad l
 18  .  .
 19  .  LINKSTYLE blue R < >
 20  .\}
 21  .SH "NAME"
 22  rad-patch \- Manage radicle patches.
 23  .SH "SYNOPSIS"
 24  .sp
 25  \fBrad patch\fP [<option>...]
 26  .br
 27  \fBrad patch\fP \fIlist\fP [\-\-all|\-\-merged|\-\-open|\-\-archived|\-\-draft] [<option>...]
 28  .br
 29  \fBrad patch\fP \fIshow\fP <patch\-id> [<option>...]
 30  .br
 31  \fBrad patch\fP \fIdiff\fP <patch\-id> [\-\-revision <revision\-id>] [<option>...]
 32  .br
 33  \fBrad patch\fP \fIarchive\fP <patch\-id> [\-\-undo] [<option>...]
 34  .br
 35  \fBrad patch\fP \fIupdate\fP <patch\-id> [<option>...]
 36  .br
 37  \fBrad patch\fP \fIcheckout\fP <patch\-id> [<option>...]
 38  .br
 39  \fBrad patch\fP \fIdelete\fP <patch\-id> [<option>...]
 40  .br
 41  \fBrad patch\fP \fIredact\fP <revision\-id> [<option>...]
 42  .br
 43  \fBrad patch\fP \fIready\fP <patch\-id> [\-\-undo] [<option>...]
 44  .br
 45  \fBrad patch\fP \fIreview\fP <patch\-id> [<option>...]
 46  .br
 47  \fBrad patch\fP \fIedit\fP <patch\-id> [<option>...]
 48  .br
 49  \fBrad patch\fP \fIset\fP <patch\-id> [<option>...]
 50  .br
 51  \fBrad patch\fP \fIcomment\fP <revision\-id> [<option>...]
 52  .br
 53  \fBrad patch\fP \fIlabel\fP <patch\-id> [<option>...]
 54  .br
 55  .sp
 56  \fBgit push rad\fP HEAD:refs/patches
 57  .br
 58  .SH "DESCRIPTION"
 59  .sp
 60  The Radicle \fBpatch\fP command is used for managing changesets inside of Radicle
 61  repositories.
 62  .sp
 63  Though many actions can be performed using \fBrad patch\fP, certain patch\-related
 64  actions use \fBgit\fP directly. For example, opening a patch is typically
 65  done using \fBgit push\fP, while merging a patch is done with a combination of
 66  \fBgit merge\fP and \fBgit push\fP.
 67  .sp
 68  To make this possible, Radicle ships with a helper program, \fBgit\-remote\-rad\fP
 69  which is invoked by \fBgit\fP on push and fetch to and from Radicle remotes.
 70  .SH "COMMANDS"
 71  .sp
 72  With no arguments, \fBrad patch\fP defaults to the \fIlist\fP command, showing the list of
 73  open patches for the current repository.
 74  .SS "show"
 75  .sp
 76  Shows information on the given patch.
 77  .sp
 78  \fB<patch\-id>\fP
 79  .RS 4
 80  The patch to show
 81  .RE
 82  .sp
 83  \fB\-\-patch\fP, \fB\-p\fP
 84  .RS 4
 85  Show the patch changes in git patch format
 86  .RE
 87  .sp
 88  \fB\-\-verbose\fP, \fB\-v\fP
 89  .RS 4
 90  Show additional information about the patch
 91  .RE
 92  .SS "diff"
 93  .sp
 94  Outputs the patch diff, using Radicle\(cqs diffing tool.
 95  .sp
 96  \fB<patch\-id>\fP
 97  .RS 4
 98  The patch to diff
 99  .RE
100  .sp
101  \fB\-\-revision\fP, \fB\-r <revision\-id>\fP
102  .RS 4
103  The revision to diff (default: latest)
104  .RE
105  .SS "edit"
106  .sp
107  Edits a patch revision comment. To edit the patch title or description, pass
108  in the \fB<patch\-id>\fP. To edit a revision comment, pass that revision\(cqs
109  \fB<revision\-id>\fP.
110  .sp
111  \fB<revision\-id>\fP
112  .RS 4
113  The revision to edit.
114  .RE
115  .sp
116  \fB\-\-message\fP, \fB\-m [<string>]\fP
117  .RS 4
118  Comment message to the patch or revision. If omitted, Radicle will prompt for
119  a comment string via \fB$EDITOR\fP.
120  .RE
121  .SS "list"
122  .sp
123  List patches in the current repository. The default is \fB\-\-open\fP.
124  .sp
125  \fB\-\-all\fP
126  .RS 4
127  List all patches, including merged and archived patches
128  .RE
129  .sp
130  \fB\-\-archived\fP
131  .RS 4
132  List only archived patches
133  .RE
134  .sp
135  \fB\-\-merged\fP
136  .RS 4
137  List only merged patches
138  .RE
139  .sp
140  \fB\-\-open\fP
141  .RS 4
142  List only open patches
143  .RE
144  .sp
145  \fB\-\-draft\fP
146  .RS 4
147  List only draft patches
148  .RE
149  .sp
150  \fB\-\-authored\fP
151  .RS 4
152  Show only patches that you have authored
153  .RE
154  .sp
155  \fB\-\-author <did>\fP
156  .RS 4
157  Show only patched where the given user is an author
158  (may be specified multiple times)
159  .RE
160  .SS "ready"
161  .sp
162  Mark a patch as ready to review. This changes the state of a patch from \fBdraft\fP
163  to \fBopen\fP.
164  .sp
165  \fB\-\-undo\fP
166  .RS 4
167  Change a patch back to \fBdraft\fP
168  .RE
169  .SS "review"
170  .sp
171  Review a patch. Indicate acceptance or rejection of a patch revision along
172  with a comment.
173  .sp
174  \fB\-\-revision\fP, \fB\-r <revision\-id>\fP
175  .RS 4
176  The revision to diff (default: latest)
177  .RE
178  .sp
179  \fB\-\-patch\fP, \fB\-\-p\fP
180  .RS 4
181  Review by patch hunks
182  .RE
183  .sp
184  \fB\-\-hunk <index>\fP
185  .RS 4
186  Only review a specific hunk
187  .RE
188  .sp
189  \fB\-\-accept\fP
190  .RS 4
191  Accept a patch or set of hunks
192  .RE
193  .sp
194  \fB\-\-reject\fP
195  .RS 4
196  Reject a patch or set of hunks
197  .RE
198  .sp
199  \fB\-\-unified\fP, \fB\-U <n>\fP
200  .RS 4
201  Generate diffs with \fB<n>\fP lines of context instead of the usual three
202  .RE
203  .sp
204  \fB\-\-delete\fP, \fB\-d\fP
205  .RS 4
206  Delete a review draft
207  .RE
208  .sp
209  \fB\-\-message\fP, \fB\-m [<string>]\fP
210  .RS 4
211  Provide a comment with the review (default: prompt)
212  .RE
213  .SS "archive"
214  .sp
215  Archive a patch.
216  .sp
217  \fB\-\-undo\fP
218  .RS 4
219  Unarchive a patch
220  .RE
221  .SS "set"
222  .sp
223  Set the current branch upstream to a patch reference. This configures your
224  branch such that pushing will update the specified patch.
225  .sp
226  \fB<patch\-id>\fP
227  .RS 4
228  The patch to set this branch\(cqs upstream to
229  .RE
230  .SS "update"
231  .sp
232  Updates a patch to the current repository \fBHEAD\fP. This is a low\-level command
233  that should only be used when using \fBgit push rad\fP is not possible.
234  .sp
235  \fB\-\-message\fP, \fB\-m [<string>]\fP
236  .RS 4
237  Provide a comment message to the revision
238  .RE
239  .sp
240  \fB\-\-no\-message\fP
241  .RS 4
242  Leave the revision comment message blank
243  .RE
244  .SS "checkout"
245  .sp
246  Switch to a given patch, by creating a branch that points to the patch head.
247  This is essentially equivalent to \fBgit checkout \-b <name>\fP followed by
248  \fBrad patch set <patch\-id>\fP. By default, the branch name includes the Patch ID.
249  .sp
250  \fB\-\-revision <id>\fP
251  .RS 4
252  Checkout the given revision of the patch
253  .RE
254  .sp
255  \fB\-\-name <string>\fP
256  .RS 4
257  Provide a name for the new branch
258  .RE
259  .sp
260  \fB\-\-force\fP, \fB\-f\fP
261  .RS 4
262  If the checkout already exists, update its head
263  .RE
264  .SS "comment"
265  .sp
266  Comment on a patch revision, optionally replying to an existing comment.
267  .sp
268  \fB<revision\-id>\fP
269  .RS 4
270  The patch revision to comment on. The Patch ID is also a Revision ID,
271  and can be used for commenting on the initial revision of the patch.
272  Any other Revision ID will comment on the revision specified.
273  .RE
274  .sp
275  \fB\-\-message\fP, \fB\-m <string>\fP
276  .RS 4
277  Comment message. If omitted, Radicle will prompt for a comment string via
278  \fB$EDITOR\fP. Multiple messages will be concatinated with a blank line in between.
279  .RE
280  .sp
281  \fB\-\-reply\-to <comment\-id>\fP
282  .RS 4
283  Optional comment to reply to. If ommitted, the comment is a top\-level comment
284  on the given revision.
285  .RE
286  .SH "OPENING A PATCH"
287  .sp
288  To open a patch, we start by making changes to our working copy, typically on
289  a feature branch. For example:
290  .sp
291  .if n .RS 4
292  .nf
293  .fam C
294  $ git checkout \-b fix/option\-parsing
295    ... edit some files ...
296  $ git commit \-a \-m "Fix option parsing"
297  .fam
298  .fi
299  .if n .RE
300  .sp
301  Once our changes are ready to be proposed as a patch, we push them via \fBgit\fP
302  to a special reference on the \fBrad\fP remote, that is used for opening patches
303  (\fBrefs/patches\fP):
304  .sp
305  .if n .RS 4
306  .nf
307  .fam C
308  $ git push rad HEAD:refs/patches
309  ✓ Patch 90c77f2c33b7e472e058de4a586156f8a7fec7d6 opened
310  \&...
311  .fam
312  .fi
313  .if n .RE
314  .sp
315  Radicle will then open your editor, where you can edit the patch title and
316  description. Make sure either \fBEDITOR\fP or \fBVISUAL\fP is set in your environment
317  (See \fBenviron(7)\fP for more details). Once you\(cqre done, simply save and exit your
318  editor. If successful, the patch is opened and its identifier is printed out.
319  You can then display the patch metadata using the \fBshow\fP sub\-command:
320  .sp
321  .if n .RS 4
322  .nf
323  .fam C
324  $ rad patch show 90c77f2
325  .fam
326  .fi
327  .if n .RE
328  .sp
329  Note that you don\(cqt have to use the full patch identifier. An unambiguous
330  prefix of it also works.
331  .sp
332  Radicle can create a patch from any Git commit. Simply substitute \fBHEAD\fP with
333  the branch name or commit hash you wish to propose a patch for. For example:
334  .sp
335  .if n .RS 4
336  .nf
337  .fam C
338  $ git push rad d39fe32387496876fae6446daf3762aacf69d83b:refs/patches
339  .fam
340  .fi
341  .if n .RE
342  .sp
343  After the patch is opened, you may notice that Radicle has set your branch
344  upstream to something like \fBrad/patches/90c77f2c33b7e472e058de4a586156f8a7fec7d6\fP.
345  This means your branch is now associated with the newly opened patch, and any
346  push from this branch will result in the patch being updated. See the next
347  section on updating a patch for more information.
348  .sp
349  Note that it\(cqs also possible to create a \fBdraft\fP patch, by using the \fB\-o
350  patch.draft\fP push option when opening a patch. See the \fBready\fP patch
351  sub\-command for more options.
352  .SS "Options"
353  .sp
354  When opening a patch, various options can be specified using git push options.
355  This is done via the \fB\-o\fP or \fB\-\-push\-option\fP flag. For example, \fB\-o patch.draft\fP.
356  The full list of options follows:
357  .sp
358  \fBsync\fP, \fBno\-sync\fP
359  .RS 4
360  Whether or not to sync with the network after the patch is opened. Defaults
361  to \fIsync\fP.
362  .RE
363  .sp
364  \fBsync.debug\fP
365  .RS 4
366  Show debug information about the syncing process.
367  .RE
368  .sp
369  \fBpatch.draft\fP
370  .RS 4
371  Open the patch as a \fIdraft\fP. Turned off by default.
372  .RE
373  .sp
374  \fBpatch.branch[=<name>]\fP
375  .RS 4
376  Create a branch when opening a patch. Turned off by default.
377  If a custom \fBname\fP is provided, this name is used. Otherwise
378  the branch name defaults to \fBpatches/<patch id>\fP.
379  .RE
380  .sp
381  \fBpatch.message\fP=\fI<message>\fP
382  .RS 4
383  To prevent the editor from opening, you can specify the patch message via this
384  option. Multiple \fBpatch.message\fP options are concatenated with a blank line
385  in between.
386  .RE
387  .sp
388  \fBpatch.base\fP=\fI<oid>\fP
389  .RS 4
390  The base commit onto which this patch should be merged. By default, this is
391  your "master" branch. When building stacked patches, it may be useful to
392  set this to the head of a previous patch.
393  .RE
394  .sp
395  For more information on push options, see \fBgit\-push(1)\fP.
396  .SH "UPDATING A PATCH"
397  .sp
398  To update a patch, we simply make our changes locally and push:
399  .sp
400  .if n .RS 4
401  .nf
402  .fam C
403  $ git commit \-\-amend
404  $ git push \-\-force
405  ✓ Patch 90c77f2 updated to revision d0018fcc21d87c91a1ff9155aed6b4e57535566b
406  \&...
407  .fam
408  .fi
409  .if n .RE
410  .sp
411  Note that this will only work if the current branch upstream is set correctly.
412  This happens automatically when a patch is opened from a branch without an
413  upstream set. In the above example, we used the \fB\-\-force\fP option, since the
414  commit was amended. This is common practice when a patch has been reworked
415  after receiving a review.
416  .sp
417  If the branch upstream is not set to the patch reference, ie. \fBrad/patches/<id>\fP,
418  you can do so using \f(CRrad patch set <id>\fP.
419  .sp
420  As with opening a patch, you will be asked to enter a reason for updating the
421  patch, via your editor. Simply save and exit when you\(cqre done; or leave it
422  blank to skip this step.
423  .sp
424  It\(cqs also possible to change the patch \fIbase\fP during an update. Simply use the
425  \fBpatch.base\fP push option as described in \fIOpening a patch\fP.
426  .SH "CHECKING OUT A PATCH"
427  .sp
428  When working with patches opened by peers, it\(cqs often useful to be able to
429  checkout the code in its own branch. With a patch checkout, you can browse the
430  code, run tests and even propose your own update to the patch. The \fBcheckout\fP
431  sub\-command is used to that effect:
432  .sp
433  .if n .RS 4
434  .nf
435  .fam C
436  $ rad patch checkout 90c77f2
437  .fam
438  .fi
439  .if n .RE
440  .sp
441  Radicle will create a new branch if necessary and checkout the patch head. From
442  there, you can \fBgit\-push\fP to publish a patch update, or simply browse the code.
443  .SH "MERGING A PATCH"
444  .sp
445  Once a patch is ready to merge, the repository maintainer simply has to use the
446  \fBgit\-merge(1)\fP command from the "master" branch and push via \fBgit\fP. For
447  example, if some patch \fB26e3e56\fP is ready to merge, the steps would be:
448  .sp
449  .if n .RS 4
450  .nf
451  .fam C
452  $ rad patch checkout 26e3e56
453  ✓ Switched to branch patch/26e3e56
454  $ git checkout master
455  $ git merge patch/26e3e56
456  $ git push rad
457  ✓ Patch 26e3e563ddc7df8dd0c9f81274c0b3cb1b764568 merged
458  To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
459     f2de534..d6399c7\&  master \-> master
460  .fam
461  .fi
462  .if n .RE
463  .sp
464  In the above, we created a checkout for the patch, and merged that branch into
465  our master branch. Then we pushed to our \fBrad\fP remote.
466  .SH "LISTING PATCHES"
467  .sp
468  To list patches, run \fBrad patch\fP. By default, this will only show open patches.
469  To list all patches, including ones that have been merged or archived, add the
470  \fB\-\-all\fP option.
471  .SH "AUTHOR"
472  .sp
473  The Radicle Team