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