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,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 +.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" -offset indent +.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 .