tools/tools/git/git-arc.1

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