Page MenuHomeFreeBSD
Files F142336086

D28519.id83486.diff
No OneTemporary
Actions

D28519.id83486.diff
View Options

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.8
.include <bsd.prog.mk>
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 <reviewer>[,reviewer2...]
+.Op Fl s Cm <subscriber>[,...]
+.Op Cm <commit>|<commit range>
+.Nm list Cm <commit>|<commit range>
+.Nm patch Cm <diff1> [<diff2> ...]
+.Nm stage Fl b Cm <branch> [<commit>|<commit range>]
+.Nm update Cm <commit>
+.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 .

File Metadata

Mime Type
text/plain
Expires
Mon, Jan 19, 6:06 PM (1 h, 30 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
27750551
Default Alt Text
D28519.id83486.diff (5 KB)

Event Timeline