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