diff --git a/tools/tools/git/git-arc.1 b/tools/tools/git/git-arc.1 index cc510c069c3a..00019a19180d 100644 --- a/tools/tools/git/git-arc.1 +++ b/tools/tools/git/git-arc.1 @@ -1,202 +1,202 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD .\" .\" Copyright (c) 2021 Daniel Ebdrup Jensen .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 7, 2021 .Dt GIT-ARC 1 .Os .Sh NAME .Nm git arc .Nd a wrapper to improve integration betwen git and arcanist .Sh SYNOPSIS .Nm .Cm create .Op Fl l .Op Fl r Ar reviewer1 Ns Op Cm \&, Ns Ar reviewer2 ... .Op Fl s Ar subscriber1 Ns Op Cm \&, Ns Ar subscriber2 ... .Op Ar commit Ns | Ns Ar commit-range .Nm .Cm list Ar commit Ns | Ns Ar commit-range .Nm .Cm patch Ar diff1 Ns Op Cm \&, Ns Ar diff2 .Nm .Cm stage .Op Fl b .Ar branch Op Ar commit Ns | Ns Ar commit-range .Nm .Cm update -.Op Ar branch Oo Ar commit Ns | Ns Ar commit-range Oc +.Op Ar commit Ns | Ns Ar commit-range Oc .Sh DESCRIPTION The .Nm utility creates and manages .Fx Phabricator reviews based on git commits. .Pp Git assumes a one-to-one relationship between git commits and Differential Revisions, and the Differential Revision title must match the summary line of the corresponding commit. In particular, the commit summaries must be unique across all open Differential Revisions authored the submitter. .Pp The first parameter must be a verb. The available verbs are: .Bl -tag -width "create" .It Cm create Create new Differential Revisions from the specified commits. .It Cm list Print the associated Differential Revisions for the specified commits. .It Cm patch Try to apply a patch from a Differential revision to the currently checked out tree. .It Cm stage Prepare a series of commits to be pushed to the upstream .Fx repository. The commits are cherry-picked to a branch (by default the .Dq main branch), review tags are added to the commit log message, and the log message is opened in an editor for any last-minute updates. The commits need not have associated Differential Revisions. .It Cm update Synchronize the Differential Revisions associated with the specified commits. Currently only the diff is updated; the review description and other metadata is not synchronized. .El .Sh CONFIGURATION These are manipulated by .Nm git-config : .Bl -tag -width "arc.assume_yes" .It Va arc.assume_yes Assume a .Dq yes answer to all prompts instead of prompting the user. Equivalent to the .Fl y flag. Defaults to false. .It Va arc.browse Try to open newly created reviews in a browser tab. Defaults to false. .It Va arc.list Always use .Dq list mode .Pq Fl l with create. In this mode, the list of git revisions to create reviews for is listed with a single prompt before creating reviews. The diffs for individual commits are not shown. Defaults to false. .It Va arc.verbose Always use verbose output. Equivalent to the .Fl v flag. Defaults to false. .El .Sh EXAMPLES The typical end-to-end usage looks something like this. .Pp Commit changes with a message and create a Differential review: .Bd -literal -offset indent $ git commit -m "kern: Rewrite in Rust" $ git arc create HEAD .Ed .Pp Make changes to the diff based on review feedback, then amend the changes to the existing commit and update the Differential review: .Bd -literal -offset indent $ git commit --amend $ git arc update HEAD .Ed .Pp Now that all reviewers are happy, it is time to stage the commit and push it: .Bd -literal -offset indent $ git arc stage HEAD $ git push freebsd HEAD:main .Ed .Pp Create a Phabricator review using the contents of the most recent commit in your git checkout: .Bd -literal -offset indent $ git arc create -r markj HEAD .Ed .Pp The commit title is used as the review title, the commit log message is used as the review description, and .Aq Mt markj@FreeBSD.org is added as a reviewer. .Pp Create a series of Phabricator reviews for each of HEAD~2, HEAD~ and HEAD: .Bd -literal -offset indent $ git arc create HEAD~3..HEAD .Ed .Pp Pairs of consecutive commits are linked into a patch stack. Note that the first commit in the specified range is excluded. .Pp Update the review corresponding to commit b409afcfedcdda: .Bd -literal -offset indent $ git arc update b409afcfedcdda .Ed .Pp The title of the commit must be the same as it was when the review was created. Note that the review description is not automatically updated. .Pp Apply the patch in review D12345 to the currently checked-out tree, and stage it: .Bd -literal -offset indent $ git arc patch D12345 .Ed .Pp List the status of reviews for all the commits in the branch .Dq feature : .Bd -literal -offset indent $ git arc list main..feature .Ed .Sh SEE ALSO .Xr build 7 , .Xr development 7 .Sh HISTORY The .Nm utility appeared in the src tools collection in .Fx 14.0 . .Sh AUTHORS The .Nm utility was written by .An -nosplit .An Mark Johnston Aq Mt markj@FreeBSD.org and the manual page was written by .An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org .