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