tools/tools/git/git-arc.1

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