Index: tools/tools/git/git-arc.8 =================================================================== --- /dev/null +++ tools/tools/git/git-arc.8 @@ -0,0 +1,152 @@ +.\" +.\" 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 8 +.Os +.Sh NAME +.Nm git-arc +.Nd arc wrapper for git-phabricator reviews +.Sh SYNOPSIS +.Nm +.Nm create +.Op Fl l +.Op Fl r Cm [,reviewer2...] +.Op Fl s Cm [,...] +.Op Cm | +.Nm list Cm | +.Nm patch Cm [ ...] +.Nm stage Fl b Cm [|] +.Nm update Cm +.Sh DESCRIPTION +The +.Nm +utility create or manages +.Fx +Phabricator reviews based on git commits. +.Pp +There is 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 by you. +.Pp +The first parameter must be a verb. +The available verbs are: +.Bl -tag -width -offset indent +.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 (main by +default), 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. +.Sh DAILY USAGE +The typical end-to-end usage looks something like this: +.Dl git commit -m "kern: Rewrite in Rust" +.Dl git arc create HEAD +Make changes to the diff based on reviewer feedback, then: +.Dl git commit --amend +.Dl git arc update HEAD +Now that all reviewers are happy, it is time to push: +.Dl git arc stage HEAD +.Dl git push freebsd HEAD:main +.Sh ENVIRONMENT +.Pp +These are manipulated by git-config(1): +.Bl -tag -width -offset indent +.It Ic arc.assume_yes [bool] +Assume a "yes" answer to all prompts instead of +prompting the user. +Equivalent to the -y flag. +.It Ic arc.browse [bool] +Try to open newly created reviews in a browser tab. +Defaults to false. +.It Ic arc.list [bool] +Always use "list mode" (-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. +.It Ic arc.verbose [bool] +Verbose output. +Equivalent to the -v flag. +.Sh EXAMPLES +.Bl -tag -width -offset indent +.It Ic git arc create -r markj HEAD +Create a Phabricator review using the contents of the most recent +commit in your git checkout. +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. +.It Ic git arc create HEAD~3..HEAD +Create a series of Phabricator reviews for each of HEAD~2, HEAD~ and +HEAD. +Pairs of consecutive commits are linked into a patch stack. +Note that the first commit in the specified range is excluded. +.It Ic git arc update b409afcfedcdda +Update the review corresponding to commit b409afcfedcdda. +The title +of the commit must be the same as it was when the review was created. +The review description is not automatically updated. +.It Ic git arc patch D12345 +Apply the patch in review D12345 to the currently checked-out tree, +and stage it. +.It Ic git arc list main..feature +List the status of reviews for all the commits in the branch +"feature": +.Sh SEE ALSO +.Xr development 7 , +.Xr build 7 +.Sh AUTHOR +The +.Nm +utility was written by +.An Mark Johnson Aq Mt markj@FreeBSD.org +and the manual page was written by +.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 14.0 .