Changeset View
Changeset View
Standalone View
Standalone View
tools/tools/git/git-arc.8
- This file was added.
.\" | |||||||||||||
.\" 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 | |||||||||||||
yuripv: this seems to be an utility for an user, not system administrator, shouldn't this be in section… | |||||||||||||
.Os | |||||||||||||
.Sh NAME | |||||||||||||
.Nm git-arc | |||||||||||||
.Nd arc wrapper for git-phabricator reviews | |||||||||||||
.Sh SYNOPSIS | |||||||||||||
.Nm | |||||||||||||
.Nm create | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Op Fl l | |||||||||||||
.Op Fl r Cm <reviewer>[,reviewer2...] | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Op Fl s Cm <subscriber>[,...] | |||||||||||||
.Op Cm <commit>|<commit range> | |||||||||||||
.Nm list Cm <commit>|<commit range> | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Nm patch Cm <diff1> [<diff2> ...] | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Nm stage | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Fl b Cm <branch> [<commit>|<commit range>] | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Nm update Cm <commit> | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.Sh DESCRIPTION | |||||||||||||
The | |||||||||||||
.Nm | |||||||||||||
utility create or manages | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
.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. | |||||||||||||
yuripvUnsubmitted Done Inline ActionsI would not use you in man pages. yuripv: I would not use `you` in man pages. | |||||||||||||
.Pp | |||||||||||||
The first parameter must be a verb. | |||||||||||||
The available verbs are: | |||||||||||||
.Bl -tag -width -offset indent | |||||||||||||
yuripvUnsubmitted Done Inline ActionsThe specification here looks to be broken, no width provided. yuripv: The specification here looks to be broken, no width provided. | |||||||||||||
.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 | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
These are manipulated by git-config(1): | |||||||||||||
.Bl -tag -width -offset indent | |||||||||||||
.It Ic arc.assume_yes [bool] | |||||||||||||
yuripvUnsubmitted Done Inline ActionsThese do not belong in ENVIRONMENT section. yuripv: These do not belong in ENVIRONMENT section. | |||||||||||||
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 | |||||||||||||
yuripvUnsubmitted Done Inline Actions
The change above should work with .Bl -item, didn't edit in-place as phab goes crazy. Or check other man pages for EXAMPLES sections. .Ic doesn't seem to be correct macro here; if you just want bold text, use .Sy. yuripv: The change above should work with `.Bl -item`, didn't edit in-place as phab goes crazy. Or… | |||||||||||||
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": | |||||||||||||
yuripvUnsubmitted Done Inline Actionstrailing : seems to be out of place yuripv: trailing `:` seems to be out of place | |||||||||||||
.Sh SEE ALSO | |||||||||||||
.Xr development 7 , | |||||||||||||
yuripvUnsubmitted Done Inline ActionsSort by section, then alphabetically. yuripv: Sort by section, then alphabetically. | |||||||||||||
.Xr build 7 | |||||||||||||
.Sh AUTHOR | |||||||||||||
yuripvUnsubmitted Done Inline Actions
yuripv: | |||||||||||||
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 . |
this seems to be an utility for an user, not system administrator, shouldn't this be in section 1?