From owner-dev-commits-src-all@freebsd.org Fri Feb 12 22:36:14 2021 Return-Path: Delivered-To: dev-commits-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id AF1DB533C8F; Fri, 12 Feb 2021 22:36:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DcpHy4b1Rz4X1M; Fri, 12 Feb 2021 22:36:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 9058C401E; Fri, 12 Feb 2021 22:36:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 11CMaEYK059423; Fri, 12 Feb 2021 22:36:14 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 11CMaEqQ059422; Fri, 12 Feb 2021 22:36:14 GMT (envelope-from git) Date: Fri, 12 Feb 2021 22:36:14 GMT Message-Id: <202102122236.11CMaEqQ059422@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Daniel Ebdrup Jensen Subject: git: 30f78a063e0d - main - git-arc(1): Add manual page MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: debdrup X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 30f78a063e0d8d34e43c82837f8b2af7efef3770 Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 12 Feb 2021 22:36:14 -0000 The branch main has been updated by debdrup (doc committer): URL: https://cgit.FreeBSD.org/src/commit/?id=30f78a063e0d8d34e43c82837f8b2af7efef3770 commit 30f78a063e0d8d34e43c82837f8b2af7efef3770 Author: Daniel Ebdrup Jensen AuthorDate: 2021-02-12 22:35:02 +0000 Commit: Daniel Ebdrup Jensen CommitDate: 2021-02-12 22:35:02 +0000 git-arc(1): Add manual page Add manual page based on the usage in the script with a few changes and hook it up to the build. Reviewed by: 0mp, markj Differential Revision: https://reviews.freebsd.org/D28519 --- tools/tools/git/Makefile | 1 + tools/tools/git/git-arc.1 | 202 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) diff --git a/tools/tools/git/Makefile b/tools/tools/git/Makefile index 228a41d65275..86c90b9fe77d 100644 --- a/tools/tools/git/Makefile +++ b/tools/tools/git/Makefile @@ -1,4 +1,5 @@ SCRIPTS= git-arc.sh BINDIR?= /usr/local/bin +MAN= git-arc.1 .include diff --git a/tools/tools/git/git-arc.1 b/tools/tools/git/git-arc.1 new file mode 100644 index 000000000000..d863447ea98e --- /dev/null +++ b/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 .