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