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 Ar diff1 Ns Op Cm \&, Ns Ar diff2 45.Nm 46.Cm stage 47.Op Fl b Ar branch 48.Op Ar commit ... Ns | Ns Ar commit-range 49.Nm 50.Cm update 51.Op Fl m Ar message 52.Op Ar commit ... Ns | Ns Ar commit-range 53.Sh DESCRIPTION 54The 55.Nm 56utility creates and manages 57.Fx 58Phabricator reviews based on git commits. 59.Pp 60Git 61assumes a one-to-one relationship between git commits and 62Differential Revisions, and the Differential Revision title must match 63the summary line of the corresponding commit. 64In particular, the commit summaries must be unique across all open 65Differential Revisions authored by the submitter. 66.Pp 67The first parameter must be a verb. 68The available verbs are: 69.Bl -tag -width "create" 70.It Cm create 71Create new Differential Revisions from the specified commits. 72Accepts options: 73.Bl -tag -width subscriber 74.It Fl l 75Before processing commit(s) display list of commits to be processed 76and wait for confirmation. 77.It Fl r Ar reviewer 78Add one or more reviewers, separated by commas, to revision(s) being created. 79Argument(s) must be existing Phabricator user or group. 80.It Fl s Ar subscriber 81Add one or more subscribers, separated by commas, to revision(s) being created. 82Each argument must be an existing Phabricator user or group. 83.It Fl p Ar parent 84Specify the parent of the first commit in the list. 85This is useful when adding more commits on top of the already existing 86stack in Phabricator. 87.El 88.It Cm list 89Print the associated Differential Revisions for the specified commits. 90.It Cm patch 91Try to apply a patch from a Differential Revision to the currently 92checked out tree. 93.It Cm stage 94Prepare a series of commits to be pushed to the upstream 95.Fx 96repository. 97The commits are cherry-picked to a branch (by default the 98.Dq main 99branch), review tags are added to the commit log message, and 100the log message is opened in an editor for any last-minute 101updates. 102The commits need not have associated Differential 103Revisions. 104.It Cm update 105Synchronize the Differential Revisions associated with the 106specified commits. 107Currently only the diff is updated; the review description and other 108metadata are not synchronized. 109If a message is specified with 110.Fl m , 111that message is added as a note to the Differential Revision. 112If no message is supplied, 113the user's editor will be opened to provide an update message for 114each revision. 115If an empty message is supplied via 116.Fl m , 117then no notes will be added when updating Differential Revisions. 118.El 119.Sh CONFIGURATION 120These are manipulated by 121.Nm git-config : 122.Bl -tag -width "arc.assume_yes" 123.It Va arc.assume_yes 124Assume a 125.Dq yes 126answer to all prompts instead of 127prompting the user. 128Equivalent to the 129.Fl y 130flag. 131Defaults to false. 132.It Va arc.browse 133Try to open newly created reviews in a browser tab. 134Defaults to false. 135.It Va arc.list 136Always use 137.Dq list mode 138.Pq Fl l 139with create. 140In this mode, the list of git revisions to create reviews for 141is listed with a single prompt before creating reviews. 142The diffs for individual commits are not shown. 143Defaults to false. 144.It Va arc.verbose 145Always use verbose output. 146Equivalent to the 147.Fl v 148flag. 149Defaults to false. 150.El 151.Sh EXAMPLES 152The typical end-to-end usage looks something like this. 153.Pp 154Commit changes with a message and create a Differential Review: 155.Bd -literal -offset indent 156$ git commit -m "kern: Rewrite in Rust" 157$ git arc create HEAD 158.Ed 159.Pp 160Make changes to the diff based on review feedback, then amend the 161changes to the existing commit and update the Differential Review: 162.Bd -literal -offset indent 163$ git commit --amend 164$ git arc update HEAD 165.Ed 166.Pp 167Now that all reviewers are happy, it is time to stage the commit and 168push it: 169.Bd -literal -offset indent 170$ git arc stage HEAD 171$ git push freebsd HEAD:main 172.Ed 173.Pp 174Create a Phabricator review using the contents of the most recent 175commit in your git checkout: 176.Bd -literal -offset indent 177$ git arc create -r markj HEAD 178.Ed 179.Pp 180The commit title is used as the review title, the commit log 181message is used as the review description, and 182.Aq Mt markj@FreeBSD.org 183is added as a reviewer. 184.Pp 185Create a series of Phabricator reviews for each of HEAD~2, HEAD~ and 186HEAD: 187.Bd -literal -offset indent 188$ git arc create HEAD~3..HEAD 189.Ed 190.Pp 191Pairs of consecutive commits are linked into a patch stack. 192Note that the first commit in the specified range is excluded. 193.Pp 194Create a series of separate reviews for each of the following commits: 195.Bd -literal -offset indent 196$ git arc create b409afcfedcdda ca03ed1345aff0 197.Ed 198.Pp 199Update the review corresponding to commit b409afcfedcdda: 200.Bd -literal -offset indent 201$ git arc update b409afcfedcdda 202.Ed 203.Pp 204The title of the commit must be the same as it was when the review 205was created. 206Note that the review description is not automatically updated. 207.Pp 208Apply the patch in review D12345 to the currently checked-out tree, 209and stage it: 210.Bd -literal -offset indent 211$ git arc patch D12345 212.Ed 213.Pp 214List the status of reviews for all the commits in the branch 215.Dq feature : 216.Bd -literal -offset indent 217$ git arc list main..feature 218.Ed 219.Sh SEE ALSO 220.Xr build 7 , 221.Xr development 7 222.Sh HISTORY 223The 224.Nm 225utility appeared in the src tools collection in 226.Fx 14.0 . 227.Sh AUTHORS 228The 229.Nm 230utility was written by 231.An -nosplit 232.An Mark Johnston Aq Mt markj@FreeBSD.org 233and the manual page was written by 234.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org . 235