/ rad-patch.1.adoc
rad-patch.1.adoc
1 = rad-patch(1) 2 The Radicle Team <team@radicle.xyz> 3 :doctype: manpage 4 :revnumber: 1.0.0 5 :revdate: 2024-04-22 6 :mansource: rad {revnumber} 7 :manmanual: Radicle CLI Manual 8 9 == Name 10 11 rad-patch - Manage radicle patches. 12 13 == Synopsis 14 15 *rad patch* [<option>...] + 16 *rad patch* _list_ [--all|--merged|--open|--archived|--draft] [<option>...] + 17 *rad patch* _show_ <patch-id> [<option>...] + 18 *rad patch* _diff_ <patch-id> [--revision <revision-id>] [<option>...] + 19 *rad patch* _archive_ <patch-id> [--undo] [<option>...] + 20 *rad patch* _update_ <patch-id> [<option>...] + 21 *rad patch* _checkout_ <patch-id> [<option>...] + 22 *rad patch* _delete_ <patch-id> [<option>...] + 23 *rad patch* _redact_ <revision-id> [<option>...] + 24 *rad patch* _ready_ <patch-id> [--undo] [<option>...] + 25 *rad patch* _review_ <patch-id> [<option>...] + 26 *rad patch* _edit_ <patch-id> [<option>...] + 27 *rad patch* _set_ <patch-id> [<option>...] + 28 *rad patch* _comment_ <revision-id> [<option>...] + 29 *rad patch* _label_ <patch-id> [<option>...] + 30 31 *git push rad* HEAD:refs/patches + 32 33 == Description 34 35 The Radicle *patch* command is used for managing changesets inside of Radicle 36 repositories. 37 38 Though many actions can be performed using *rad patch*, certain patch-related 39 actions use *git* directly. For example, opening a patch is typically 40 done using *git push*, while merging a patch is done with a combination of 41 *git merge* and *git push*. 42 43 To make this possible, Radicle ships with a helper program, *git-remote-rad* 44 which is invoked by *git* on push and fetch to and from Radicle remotes. 45 46 == Commands 47 48 With no arguments, *rad patch* defaults to the _list_ command, showing the list of 49 open patches for the current repository. 50 51 === show 52 53 Shows information on the given patch. 54 55 *<patch-id>*:: The patch to show 56 *--patch*, *-p*:: Show the patch changes in git patch format 57 *--verbose*, *-v*:: Show additional information about the patch 58 59 === diff 60 61 Outputs the patch diff, using Radicle's diffing tool. 62 63 *<patch-id>*:: The patch to diff 64 *--revision*, *-r <revision-id>*:: The revision to diff (default: latest) 65 66 === edit 67 68 Edits a patch revision comment. To edit the patch title or description, pass 69 in the *<patch-id>*. To edit a revision comment, pass that revision's 70 *<revision-id>*. 71 72 *<revision-id>*:: 73 The revision to edit. 74 75 *--message*, *-m [<string>]*:: 76 Comment message to the patch or revision. If omitted, Radicle will prompt for 77 a comment string via *$EDITOR*. 78 79 === list 80 81 List patches in the current repository. The default is *--open*. 82 83 *--all*:: List all patches, including merged and archived patches 84 *--archived*:: List only archived patches 85 *--merged*:: List only merged patches 86 *--open*:: List only open patches 87 *--draft*:: List only draft patches 88 *--authored*:: Show only patches that you have authored 89 *--author <did>*:: Show only patched where the given user is an author 90 (may be specified multiple times) 91 92 === ready 93 94 Mark a patch as ready to review. This changes the state of a patch from *draft* 95 to *open*. 96 97 *--undo*:: Change a patch back to *draft* 98 99 === review 100 101 Review a patch. Indicate acceptance or rejection of a patch revision along 102 with a comment. 103 104 *--revision*, *-r <revision-id>*:: The revision to diff (default: latest) 105 *--patch*, *--p*:: Review by patch hunks 106 *--hunk <index>*:: Only review a specific hunk 107 *--accept*:: Accept a patch or set of hunks 108 *--reject*:: Reject a patch or set of hunks 109 *--unified*, *-U <n>*:: Generate diffs with *<n>* lines of context instead of the usual three 110 *--delete*, *-d*:: Delete a review draft 111 *--message*, *-m [<string>]*:: Provide a comment with the review (default: prompt) 112 113 === archive 114 115 Archive a patch. 116 117 *--undo*:: Unarchive a patch 118 119 === set 120 121 Set the current branch upstream to a patch reference. This configures your 122 branch such that pushing will update the specified patch. 123 124 *<patch-id>*:: The patch to set this branch's upstream to 125 126 === update 127 128 Updates a patch to the current repository *HEAD*. This is a low-level command 129 that should only be used when using *git push rad* is not possible. 130 131 *--message*, *-m [<string>]*:: Provide a comment message to the revision 132 *--no-message*:: Leave the revision comment message blank 133 134 === checkout 135 136 Switch to a given patch, by creating a branch that points to the patch head. 137 This is essentially equivalent to *git checkout -b <name>* followed by 138 *rad patch set <patch-id>*. By default, the branch name includes the Patch ID. 139 140 *--revision <id>*:: Checkout the given revision of the patch 141 *--name <string>*:: Provide a name for the new branch 142 *--force*, *-f*:: If the checkout already exists, update its head 143 144 === comment 145 146 Comment on a patch revision, optionally replying to an existing comment. 147 148 *<revision-id>*:: 149 The patch revision to comment on. The Patch ID is also a Revision ID, 150 and can be used for commenting on the initial revision of the patch. 151 Any other Revision ID will comment on the revision specified. 152 153 *--message*, *-m <string>*:: 154 Comment message. If omitted, Radicle will prompt for a comment string via 155 *$EDITOR*. Multiple messages will be concatenated with a blank line in between. 156 157 *--reply-to <comment-id>*:: 158 Optional comment to reply to. If omitted, the comment is a top-level comment 159 on the given revision. 160 161 == Opening a patch 162 163 To open a patch, we start by making changes to our working copy, typically on 164 a feature branch. For example: 165 166 $ git checkout -b fix/option-parsing 167 ... edit some files ... 168 $ git commit -a -m "Fix option parsing" 169 170 Once our changes are ready to be proposed as a patch, we push them via *git* 171 to a special reference on the *rad* remote, that is used for opening patches 172 (*refs/patches*): 173 174 $ git push rad HEAD:refs/patches 175 ✓ Patch 90c77f2c33b7e472e058de4a586156f8a7fec7d6 opened 176 ... 177 178 Radicle will then open your editor, where you can edit the patch title and 179 description. Make sure either *EDITOR* or *VISUAL* is set in your environment 180 (See *environ(7)* for more details). Once you're done, simply save and exit your 181 editor. If successful, the patch is opened and its identifier is printed out. 182 You can then display the patch metadata using the *show* sub-command: 183 184 $ rad patch show 90c77f2 185 186 Note that you don't have to use the full patch identifier. An unambiguous 187 prefix of it also works. 188 189 Radicle can create a patch from any Git commit. Simply substitute *HEAD* with 190 the branch name or commit hash you wish to propose a patch for. For example: 191 192 $ git push rad d39fe32387496876fae6446daf3762aacf69d83b:refs/patches 193 194 After the patch is opened, you may notice that Radicle has set your branch 195 upstream to something like *rad/patches/90c77f2c33b7e472e058de4a586156f8a7fec7d6*. 196 This means your branch is now associated with the newly opened patch, and any 197 push from this branch will result in the patch being updated. See the next 198 section on updating a patch for more information. 199 200 Note that it's also possible to create a *draft* patch, by using the *-o 201 patch.draft* push option when opening a patch. See the *ready* patch 202 sub-command for more options. 203 204 === Options 205 206 When opening a patch, various options can be specified using git push options. 207 This is done via the *-o* or *--push-option* flag. For example, *-o patch.draft*. 208 The full list of options follows: 209 210 *sync*, *no-sync*:: 211 Whether or not to sync with the network after the patch is opened. Defaults 212 to _sync_. 213 214 *sync.debug*:: 215 Show debug information about the syncing process. 216 217 *patch.draft*:: 218 Open the patch as a _draft_. Turned off by default. 219 220 *patch.branch[=<name>]*:: 221 Create a branch when opening a patch. Turned off by default. 222 If a custom *name* is provided, this name is used. Otherwise 223 the branch name defaults to *patches/<patch id>*. 224 225 *patch.message*=_<message>_:: 226 To prevent the editor from opening, you can specify the patch message via this 227 option. Multiple *patch.message* options are concatenated with a blank line 228 in between. 229 230 *patch.base*=_<oid>_:: 231 The base commit onto which this patch should be merged. By default, this is 232 your "master" branch. When building stacked patches, it may be useful to 233 set this to the head of a previous patch. 234 235 For more information on push options, see *git-push(1)*. 236 237 == Updating a patch 238 239 To update a patch, we simply make our changes locally and push: 240 241 $ git commit --amend 242 $ git push --force 243 ✓ Patch 90c77f2 updated to revision d0018fcc21d87c91a1ff9155aed6b4e57535566b 244 ... 245 246 Note that this will only work if the current branch upstream is set correctly. 247 This happens automatically when a patch is opened from a branch without an 248 upstream set. In the above example, we used the *--force* option, since the 249 commit was amended. This is common practice when a patch has been reworked 250 after receiving a review. 251 252 If the branch upstream is not set to the patch reference, ie. *rad/patches/<id>*, 253 you can do so using `rad patch set <id>`. 254 255 As with opening a patch, you will be asked to enter a reason for updating the 256 patch, via your editor. Simply save and exit when you're done; or leave it 257 blank to skip this step. 258 259 It's also possible to change the patch _base_ during an update. Simply use the 260 *patch.base* push option as described in _Opening a patch_. 261 262 == Checking out a patch 263 264 When working with patches opened by peers, it's often useful to be able to 265 checkout the code in its own branch. With a patch checkout, you can browse the 266 code, run tests and even propose your own update to the patch. The *checkout* 267 sub-command is used to that effect: 268 269 $ rad patch checkout 90c77f2 270 271 Radicle will create a new branch if necessary and checkout the patch head. From 272 there, you can *git-push* to publish a patch update, or simply browse the code. 273 274 == Merging a patch 275 276 Once a patch is ready to merge, the repository maintainer simply has to use the 277 *git-merge(1)* command from the "master" branch and push via *git*. For 278 example, if some patch *26e3e56* is ready to merge, the steps would be: 279 280 $ rad patch checkout 26e3e56 281 ✓ Switched to branch patch/26e3e56 282 $ git checkout master 283 $ git merge patch/26e3e56 284 $ git push rad 285 ✓ Patch 26e3e563ddc7df8dd0c9f81274c0b3cb1b764568 merged 286 To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi 287 f2de534..d6399c7 master -> master 288 289 In the above, we created a checkout for the patch, and merged that branch into 290 our master branch. Then we pushed to our *rad* remote. 291 292 == Listing patches 293 294 To list patches, run *rad patch*. By default, this will only show open patches. 295 To list all patches, including ones that have been merged or archived, add the 296 *--all* option.