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