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 December 29, 2025 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.Ar commit-ref Op Ar commit-ref ... 41.Nm 42.Cm list Ar commit-ref Op Ar commit-ref ... 43.Nm 44.Op Fl bcrs 45.Cm patch 46.Op Fl c 47.Ar diff1 Op Cm Ar diff2 Op Ar ... 48.Nm 49.Cm stage 50.Op Fl b Ar branch 51.Ar commit-ref Op Ar commit-ref ... 52.Nm 53.Cm update 54.Op Fl l 55.Op Fl m Ar message 56.Ar commit-ref Op Ar commit-ref ... 57.Sh DESCRIPTION 58The 59.Nm 60utility creates and manages 61.Fx 62Phabricator reviews based on git commits. 63It is geared towards 64.Fx 65development. 66It requires the 67.Pa devel/git , 68.Pa devel/arcanist-lib 69and 70.Pa textproc/jq 71packages; these will be installed automatically if 72.Nm 73is installed via the 74.Pa devel/freebsd-git-devtools 75package. 76.Pp 77.Nm 78assumes a one-to-one relationship between git commits and 79Differential Revisions, and requires the titles in a pair to match. 80Commit titles must therefore be unique across all open 81Differential Revisions authored by the submitter. 82If the title of either a commit or its associated Differential Revision is 83changed, the other must be updated manually to maintain the match. 84.Pp 85The first parameter must be a verb. 86Most verbs accept one or more git commit references: commit hashes, branch 87names, commit ranges, and so on. 88A branch name refers to the single commit at its tip; use a commit range to 89operate on multiple commits. 90See 91.Xr git-rev-parse 1 92for details on specifying commit references. 93The available verbs are: 94.Bl -tag -width "create" 95.It Cm create 96Create new Differential Revisions from the specified commits. 97Accepts options: 98.Bl -tag -width "-s subscriber" 99.It Fl l 100Before processing commit(s) display list of commits to be processed 101and wait for confirmation. 102.It Fl r Ar reviewer 103Add one or more reviewers, separated by commas, to revision(s) being created. 104Each argument must be an existing Phabricator user or group. 105Note that group reviewers must be specified using their 106hashtag (e.g. #jails for the "Jails" group). 107.It Fl s Ar subscriber 108Add one or more subscribers, separated by commas, to revision(s) being created. 109Each argument must be an existing Phabricator user or group. 110.It Fl p Ar parent 111Specify the parent of the first commit in the list. 112This is useful when adding more commits on top of an already existing 113stack in Phabricator. 114.El 115.It Cm list 116Print the associated Differential Revisions for the specified commits. 117.It Cm patch 118Try to apply patches from one or more Differential Revision to the currently 119checked out tree. 120The following options are accepted: 121.Bl -tag -width "-b" 122.It Fl b 123Switch to a new branch before applying the patches. 124.It Fl c 125Commit each applied patch to the git checkout. 126The commit message and author are taken from the Differential Revision. 127.It Fl r 128Rather than using the 129.Sy arc 130command to apply the patch, download the raw patch file and apply it using 131.Xr git-apply 1 . 132This is useful for avoiding some misfeatures of 133.Sy arc , 134particularly its behavior of trying to update all remotes in the tree in some 135cases. 136.It Fl s 137Recursively apply the parent revisions of the specified commit. 138This can be used to apply patch stacks by specifying the top-most, i.e., 139most recent commit in the stack. 140.El 141.It Cm stage 142Prepare a series of commits to be pushed to the upstream 143.Fx 144repository. 145.Pp 146First, the target branch is checked out; by default this is the 147main branch but can be overridden with the 148.Fl b 149option. 150Then, the specified commits are cherry-picked with review tags added to the 151commit log message, and the log message is opened in an editor for any final 152updates. 153The commits need not have associated Differential Revisions. 154.Pp 155This is intended to be used after code review has been completed, and the 156commits are ready to be pushed to an upstream repository. 157.It Cm update 158Synchronize the Differential Revisions associated with the 159specified commits. 160Currently only the diff is updated; the review description and other 161metadata are not synchronized. 162If a message is specified with 163.Fl m , 164that message is added as a note to the Differential Revision. 165If no message is supplied, 166the user's editor will be opened to provide an update message for 167each revision. 168If an empty message is supplied via 169.Fl m , 170then no notes will be added when updating Differential Revisions. 171.Pp 172If 173.Fl l 174is used, display list of commits to be updated and wait for confirmation 175of the list rather than prompting for each commit. 176.El 177.Sh CONFIGURATION 178These are manipulated by 179.Nm git-config : 180.Bl -tag -width "arc.assume_yes" 181.It Va arc.assume_yes 182Assume a 183.Dq yes 184answer to all prompts instead of 185prompting the user. 186Equivalent to the 187.Fl y 188flag. 189Defaults to false. 190.It Va arc.browse 191Try to open newly created reviews in a browser tab. 192Defaults to false. 193.It Va arc.list 194Always use 195.Dq list mode 196.Pq Fl l 197with create and update. 198In this mode, the list of git revisions to use 199is listed with a single prompt before creating or updating reviews. 200The diffs for individual commits are not shown. 201Defaults to false. 202.It Va arc.verbose 203Always use verbose output. 204Equivalent to the 205.Fl v 206flag. 207Defaults to false. 208.El 209.Sh EXAMPLES 210The typical end-to-end usage looks something like this. 211.Pp 212Commit changes with a message and create a Differential Review: 213.Bd -literal -offset indent 214$ git commit -m "kern: Rewrite in Rust" 215$ git arc create HEAD 216.Ed 217.Pp 218Make changes to the diff based on review feedback, then amend the 219changes to the existing commit and update the Differential Review: 220.Bd -literal -offset indent 221$ git commit --amend 222$ git arc update HEAD 223.Ed 224.Pp 225Now that all reviewers are happy, it is time to stage the commit and 226push it: 227.Bd -literal -offset indent 228$ git arc stage HEAD 229$ git push freebsd HEAD:main 230.Ed 231.Pp 232Create a Phabricator review using the contents of the most recent 233commit in your git checkout: 234.Bd -literal -offset indent 235$ git arc create -r markj,#jails HEAD 236.Ed 237.Pp 238The commit title is used as the review title, the commit log 239message is used as the review description, and 240.Aq Mt markj@FreeBSD.org 241is added as a reviewer. 242Also, the 243.Dq Jails 244reviewer group is added using its hashtag. 245.Pp 246Create a series of Phabricator reviews for each of HEAD~2, HEAD~ and 247HEAD: 248.Bd -literal -offset indent 249$ git arc create HEAD~3..HEAD 250.Ed 251.Pp 252Pairs of consecutive commits are linked into a patch stack. 253Note that the first commit in the specified range is excluded. 254.Pp 255Create a series of separate reviews for each of the following commits: 256.Bd -literal -offset indent 257$ git arc create b409afcfedcdda ca03ed1345aff0 258.Ed 259.Pp 260Update the review corresponding to commit b409afcfedcdda: 261.Bd -literal -offset indent 262$ git arc update b409afcfedcdda 263.Ed 264.Pp 265The title of the commit must be the same as it was when the review 266was created. 267Note that the review description is not automatically updated. 268.Pp 269Apply the patch in review D12345 to the currently checked-out tree, 270and stage it: 271.Bd -literal -offset indent 272$ git arc patch D12345 273.Ed 274.Pp 275Apply the patch in review D23456 to the currently checked-out tree, 276and commit it to the tree with the commit message in the review and 277make the best guess for what to use for author. 278If the guess is considered unreliable, the user is prompted to see 279if they wish to use it (or abort). 280.Bd -literal -offset indent 281$ git arc patch -c D23456 282.Ed 283.Pp 284List the status of reviews for all the commits in the branch 285.Dq feature : 286.Bd -literal -offset indent 287$ git arc list main..feature 288.Ed 289.Pp 290Update reviews for all commits in the branch 291.Dq feature 292after rebasing: 293.Bd -literal -offset indent 294$ git arc update -lm "Rebase" main..feature 295.Ed 296.Sh SEE ALSO 297.Xr build 7 , 298.Xr development 7 299.Sh HISTORY 300The 301.Nm 302utility appeared in the src tools collection in 303.Fx 14.0 . 304.Sh AUTHORS 305The 306.Nm 307utility was written by 308.An -nosplit 309.An Mark Johnston Aq Mt markj@FreeBSD.org 310and the manual page was written by 311.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org . 312