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