1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2021 Daniel Ebdrup Jensen 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd May 5, 2023 28.Dt GIT-ARC 1 29.Os 30.Sh NAME 31.Nm git arc 32.Nd a wrapper to improve integration between git and arcanist 33.Sh SYNOPSIS 34.Nm 35.Cm create 36.Op Fl l 37.Op Fl r Ar reviewer1 Ns Op Cm \&, Ns Ar reviewer2 ... 38.Op Fl s Ar subscriber1 Ns Op Cm \&, Ns Ar subscriber2 ... 39.Op Fl p Ar parent 40.Op Ar commit ... Ns | Ns Ar commit-range 41.Nm 42.Cm list Ar commit ... Ns | Ns Ar commit-range 43.Nm 44.Cm patch 45.Op Fl c 46.Ar diff1 Ns Op Cm \&, Ns Ar diff2 47.Nm 48.Cm stage 49.Op Fl b Ar branch 50.Op Ar commit ... Ns | Ns Ar commit-range 51.Nm 52.Cm update 53.Op Fl l 54.Op Fl m Ar message 55.Op Ar commit ... Ns | Ns Ar commit-range 56.Sh DESCRIPTION 57The 58.Nm 59utility creates and manages 60.Fx 61Phabricator reviews based on git commits. 62.Pp 63Git 64assumes a one-to-one relationship between git commits and 65Differential Revisions, and the Differential Revision title must match 66the summary line of the corresponding commit. 67In particular, the commit summaries must be unique across all open 68Differential Revisions authored by the submitter. 69.Pp 70The first parameter must be a verb. 71The available verbs are: 72.Bl -tag -width "create" 73.It Cm create 74Create new Differential Revisions from the specified commits. 75Accepts options: 76.Bl -tag -width "-s subscriber" 77.It Fl l 78Before processing commit(s) display list of commits to be processed 79and wait for confirmation. 80.It Fl r Ar reviewer 81Add one or more reviewers, separated by commas, to revision(s) being created. 82Argument(s) must be existing Phabricator user or group. 83.It Fl s Ar subscriber 84Add one or more subscribers, separated by commas, to revision(s) being created. 85Each argument must be an existing Phabricator user or group. 86.It Fl p Ar parent 87Specify the parent of the first commit in the list. 88This is useful when adding more commits on top of the already existing 89stack in Phabricator. 90.El 91.It Cm list 92Print the associated Differential Revisions for the specified commits. 93.It Cm patch 94Try to apply a patch from a Differential Revision to the currently 95checked out tree. 96.It Cm stage 97Prepare a series of commits to be pushed to the upstream 98.Fx 99repository. 100The commits are cherry-picked to a branch (by default the 101.Dq main 102branch), review tags are added to the commit log message, and 103the log message is opened in an editor for any last-minute 104updates. 105The commits need not have associated Differential 106Revisions. 107.It Cm update 108Synchronize the Differential Revisions associated with the 109specified commits. 110Currently only the diff is updated; the review description and other 111metadata are not synchronized. 112If a message is specified with 113.Fl m , 114that message is added as a note to the Differential Revision. 115If no message is supplied, 116the user's editor will be opened to provide an update message for 117each revision. 118If an empty message is supplied via 119.Fl m , 120then no notes will be added when updating Differential Revisions. 121.Pp 122If 123.Fl l 124is used, display list of commits to be updated and wait for confirmation 125of the list rather than prompting for each commit. 126.El 127.Sh CONFIGURATION 128These are manipulated by 129.Nm git-config : 130.Bl -tag -width "arc.assume_yes" 131.It Va arc.assume_yes 132Assume a 133.Dq yes 134answer to all prompts instead of 135prompting the user. 136Equivalent to the 137.Fl y 138flag. 139Defaults to false. 140.It Va arc.browse 141Try to open newly created reviews in a browser tab. 142Defaults to false. 143.It Va arc.list 144Always use 145.Dq list mode 146.Pq Fl l 147with create and update. 148In this mode, the list of git revisions to use 149is listed with a single prompt before creating or updating reviews. 150The diffs for individual commits are not shown. 151Defaults to false. 152.It Va arc.verbose 153Always use verbose output. 154Equivalent to the 155.Fl v 156flag. 157Defaults to false. 158.El 159.Sh EXAMPLES 160The typical end-to-end usage looks something like this. 161.Pp 162Commit changes with a message and create a Differential Review: 163.Bd -literal -offset indent 164$ git commit -m "kern: Rewrite in Rust" 165$ git arc create HEAD 166.Ed 167.Pp 168Make changes to the diff based on review feedback, then amend the 169changes to the existing commit and update the Differential Review: 170.Bd -literal -offset indent 171$ git commit --amend 172$ git arc update HEAD 173.Ed 174.Pp 175Now that all reviewers are happy, it is time to stage the commit and 176push it: 177.Bd -literal -offset indent 178$ git arc stage HEAD 179$ git push freebsd HEAD:main 180.Ed 181.Pp 182Create a Phabricator review using the contents of the most recent 183commit in your git checkout: 184.Bd -literal -offset indent 185$ git arc create -r markj HEAD 186.Ed 187.Pp 188The commit title is used as the review title, the commit log 189message is used as the review description, and 190.Aq Mt markj@FreeBSD.org 191is added as a reviewer. 192.Pp 193Create a series of Phabricator reviews for each of HEAD~2, HEAD~ and 194HEAD: 195.Bd -literal -offset indent 196$ git arc create HEAD~3..HEAD 197.Ed 198.Pp 199Pairs of consecutive commits are linked into a patch stack. 200Note that the first commit in the specified range is excluded. 201.Pp 202Create a series of separate reviews for each of the following commits: 203.Bd -literal -offset indent 204$ git arc create b409afcfedcdda ca03ed1345aff0 205.Ed 206.Pp 207Update the review corresponding to commit b409afcfedcdda: 208.Bd -literal -offset indent 209$ git arc update b409afcfedcdda 210.Ed 211.Pp 212The title of the commit must be the same as it was when the review 213was created. 214Note that the review description is not automatically updated. 215.Pp 216Apply the patch in review D12345 to the currently checked-out tree, 217and stage it: 218.Bd -literal -offset indent 219$ git arc patch D12345 220.Ed 221.Pp 222Apply the patch in review D23456 to the currently checked-out tree, 223and commit it to the tree with the commit message in the review and 224make the best guess for what to use for author. 225If the guess is considered unreliable, the user is prompted to see 226if they wish to use it (or abort). 227.Bd -literal -offset indent 228$ git arc patch -c D23456 229.Ed 230.Pp 231List the status of reviews for all the commits in the branch 232.Dq feature : 233.Bd -literal -offset indent 234$ git arc list main..feature 235.Ed 236.Pp 237Update reviews for all commits in the branch 238.Dq feature 239after rebasing: 240.Bd -literal -offset indent 241$ git arc update -lm "Rebase" main..feature 242.Ed 243.Sh SEE ALSO 244.Xr build 7 , 245.Xr development 7 246.Sh HISTORY 247The 248.Nm 249utility appeared in the src tools collection in 250.Fx 14.0 . 251.Sh AUTHORS 252The 253.Nm 254utility was written by 255.An -nosplit 256.An Mark Johnston Aq Mt markj@FreeBSD.org 257and the manual page was written by 258.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org . 259