Index: tools/tools/git/Makefile =================================================================== --- tools/tools/git/Makefile +++ tools/tools/git/Makefile @@ -1,4 +1,5 @@ SCRIPTS= git-arc.sh BINDIR?= /usr/local/bin +MAN= git-arc.1 .include Index: tools/tools/git/git-arc.1 =================================================================== --- /dev/null +++ tools/tools/git/git-arc.1 @@ -0,0 +1,184 @@ +.\" +.\" 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 arc wrapper for git-Phabricator reviews +.Sh SYNOPSIS +.Nm +.Cm create +.Op Fl l +.Op Fl r Ar reviewer1 Ns Op , Ns Ar reviewer2 No +.Op Fl s Ar subscriber1 Ns Op , Ns Ar subscriber2 No +.Op Cm | +.Cm list Ar commit Ns | Ns Ar commit-range +.Cm patch Ar diff1 Ns Op , Ns Ar diff2 No +.Cm stage +.Op Fl b Oc +.Ar branch Op Ar commit Ns | Ns Ar commit-range +.Cm update +.Op branch Oo Ar commit Ns | Ns Ar commit-range +.Sh DESCRIPTION +The +.Nm +utility creates 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 the submitter. +.Pp +The first parameter must be a verb. +The available verbs are: +.Bl -tag -width "create" -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 +.Pp +The typical end-to-end usage looks something like this. +.Pp +Commit changes with a message and create a Differential review: +.Bd -literal +.Sy $ git commit -m "kern: Rewrite in Rust" +.Sy $ git arc create HEAD +.Ed +.Pp +Make changes to the diff based on reviewer feedback, then amend the +changes to the existing commit and update the Differential review: +.Bd -literal +.Sy $ git commit --amend +.Sy $ git arc update HEAD +.Ed +.Pp +Now that all reviewers are happy, it is time to stage the commit and +push it: +.Bd -literal +.Sy $ git arc stage HEAD +.Sy $ git push freebsd HEAD:main +.Ed +.Sh CONFIGURATION +These are manipulated by git-config(1): +.Bl -tag -width "arc.assume_yes [bool]" -offset indent +.It Cm arc.assume_yes [bool] +Assume a "yes" answer to all prompts instead of +prompting the user. +Equivalent to the -y flag. +.It Cm arc.browse [bool] +Try to open newly created reviews in a browser tab. +Defaults to false. +.It Cm 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 Cm arc.verbose [bool] +Verbose output. +Equivalent to the -v flag. +.Sh EXAMPLES +.Pp +Create a Phabricator review using the contents of the most recent +commit in your git checkout: +.Bd -literal +.Sy $ 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 +.Sy $ 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 +.Sy $ 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 +.Sy $ git arc patch D12345 +.Ed +.Pp +List the status of reviews for all the commits in the branch +"feature": +.Bd -literal +.Sy $ git arc list main..feature +.Ed +.Sh SEE ALSO +.Xr build 7 +.Xr development 7 , +.Sh AUTHORS +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 .