Page MenuHomeFreeBSD
Files F139441813

D28519.id83508.diff
No OneTemporary
Actions

D28519.id83508.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.1
.include <bsd.prog.mk>
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 <commit>|<commit range>
+.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 .

File Metadata

Mime Type
text/plain
Expires
Sat, Dec 13, 3:24 AM (11 h, 10 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
26919874
Default Alt Text
D28519.id83508.diff (6 KB)

Event Timeline