git: 30f78a063e0d - main - git-arc(1): Add manual page

Fri Feb 12 22:36:14 UTC 2021

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 <debdrup at FreeBSD.org>
AuthorDate: 2021-02-12 22:35:02 +0000
Commit:     Daniel Ebdrup Jensen <debdrup at FreeBSD.org>
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 <bsd.prog.mk>
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 at 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 at FreeBSD.org
+and the manual page was written by
+.An Daniel Ebdrup Jensen Aq Mt debdrup at FreeBSD.org .
