Changeset View
Standalone View
tools/tools/git/git-arc.1
- 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 1 | ||||||||||||
.Os | ||||||||||||
.Sh NAME | ||||||||||||
.Nm git arc | ||||||||||||
.Nd arc wrapper for git-Phabricator reviews | ||||||||||||
0mp: Perhaps this description could be simplified "git-Phabricator" doesn't look good to me, but… | ||||||||||||
.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 | ||||||||||||
debdrupAuthorUnsubmitted Done Inline ActionsIs there a macro which ensures that these arguments are listed on one line each? debdrup: Is there a macro which ensures that these arguments are listed on one line each? | ||||||||||||
0mpUnsubmitted Done Inline ActionsKind of. Here's a corrected 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 No .Nm .Cm stage .Op Fl b Oc .Ar branch Op Ar commit Ns | Ns Ar commit-range .Nm .Cm update .Op Ar branch Oo Ar commit Ns | Ns Ar commit-range Assuming that -b is optional to the stage verb, and branch is required. 0mp: Kind of. Here's a corrected synopsis:
```
.Nm
.Cm create
.Op Fl l
.Op Fl r Ar reviewer1 Ns Op… | ||||||||||||
.Sh DESCRIPTION | ||||||||||||
The | ||||||||||||
.Nm | ||||||||||||
utility creates or manages | ||||||||||||
markjUnsubmitted Done Inline ActionsI would s/or/and/. markj: I would s/or/and/. | ||||||||||||
.Fx | ||||||||||||
Phabricator reviews based on git commits. | ||||||||||||
.Pp | ||||||||||||
There is a one-to-one relationship between git commits and | ||||||||||||
markjUnsubmitted Done Inline Actions
IMO it would be clearer to state that this is an assumption. markj: IMO it would be clearer to state that this is an assumption. | ||||||||||||
0mpUnsubmitted Done Inline ActionsShouldn't we stylize git as Git in such cases? 0mp: Shouldn't we stylize git as `Git` in such cases? | ||||||||||||
Differential revisions, and the Differential revision title must match | ||||||||||||
0mpUnsubmitted Done Inline Actions"Differential revisions" seems a bit inconsistent to me. Should that be either "Differential Revisions" or "differential revisions"? 0mp: "Differential revisions" seems a bit inconsistent to me. Should that be either "Differential… | ||||||||||||
the summary line of the corresponding commit. | ||||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||||
In Particular, the commit summaries must be unique across all open | ||||||||||||
markjUnsubmitted Done Inline Actions
markj: | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
Differential revisions authored the submitter. | ||||||||||||
.Pp | ||||||||||||
The first parameter must be a verb. | ||||||||||||
The available verbs are: | ||||||||||||
.Bl -tag -width "create" -offset indent | ||||||||||||
0mpUnsubmitted Done Inline ActionsI think I'd drop -offset indent. That would be consistent with style in pages like ifconfig(8). 0mp: I think I'd drop `-offset indent`. That would be consistent with style in pages like ifconfig… | ||||||||||||
.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 | ||||||||||||
0mpUnsubmitted Done Inline ActionsSince main is a constant in a way, I'd stylize it with the Ql macro. 0mp: Since main is a constant in a way, I'd stylize it with the Ql macro. | ||||||||||||
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 | ||||||||||||
0mpUnsubmitted Done Inline ActionsPerhaps this should be EXAMPLES instead? I am not sure if the order of sections is going to be correct then... 0mp: Perhaps this should be EXAMPLES instead? I am not sure if the order of sections is going to be… | ||||||||||||
.Pp | ||||||||||||
0mpUnsubmitted Done Inline ActionsThis is not needed. Please see the output of mandoc -Tlint. 0mp: This is not needed. Please see the output of `mandoc -Tlint`. | ||||||||||||
The typical end-to-end usage looks something like this. | ||||||||||||
.Pp | ||||||||||||
Commit changes with a message and create a Differential review: | ||||||||||||
.Bd -literal | ||||||||||||
0mpUnsubmitted Done Inline ActionsI'd add -offset indent for every Bd in this section. 0mp: I'd add `-offset indent` for every `Bd` in this section. | ||||||||||||
.Sy $ git commit -m "kern: Rewrite in Rust" | ||||||||||||
0mpUnsubmitted Done Inline ActionsUsually, we do not use Sy to make exaples bold. I'd remove them for consistency with other manuals. 0mp: Usually, we do not use `Sy` to make exaples bold. I'd remove them for consistency with other… | ||||||||||||
.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: | ||||||||||||
0mpUnsubmitted Done Inline ActionsTypo? s/review/revision/? 0mp: Typo? s/review/revision/? | ||||||||||||
Done Inline ActionsCould [bool] be dropped now? 0mp: Could `[bool]` be dropped now? | ||||||||||||
Not Done Inline ActionsI'd probably drop -offset indent as well here. It's up to you :) 0mp: I'd probably drop `-offset indent` as well here. It's up to you :) | ||||||||||||
.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: | ||||||||||||
Not Done Inline Actions
Typo 0mp: Typo | ||||||||||||
.Bd -literal | ||||||||||||
.Sy $ git arc stage HEAD | ||||||||||||
.Sy $ git push freebsd HEAD:main | ||||||||||||
.Ed | ||||||||||||
.Sh CONFIGURATION | ||||||||||||
These are manipulated by git-config(1): | ||||||||||||
0mpUnsubmitted Done Inline Actions
We should either use .Xr git-config 1 here or something like .Nm git config perhaps. 0mp: We should either use `.Xr git-config 1` here or something like `.Nm git config` perhaps. | ||||||||||||
.Bl -tag -width "arc.assume_yes [bool]" -offset indent | ||||||||||||
.It Cm arc.assume_yes [bool] | ||||||||||||
0mpUnsubmitted Done Inline Actions
Here and in other cases as well. This [bool] is not a part of a command modifier. You may also consider the format used in rc.conf(5) for types. 0mp: Here and in other cases as well. This `[bool]` is not a part of a command modifier.
You may… | ||||||||||||
Assume a "yes" answer to all prompts instead of | ||||||||||||
0mpUnsubmitted Done Inline Actions
We usually try to use the Pq macro for quoting instead of using " directly. 0mp: We usually try to use the Pq macro for quoting instead of using `"` directly. | ||||||||||||
debdrupAuthorUnsubmitted Done Inline ActionsI assume you meant the Qq macro, because Pq is parentheses while the former is double quotes, so that's what I went with, since it matches the text that you rightly spotted should be a macro. :) debdrup: I assume you meant the Qq macro, because Pq is parentheses while the former is double quotes… | ||||||||||||
0mpUnsubmitted Done Inline ActionsSorry for the confusion. Instead of Pq I meant Dq. As documented in style.mdoc we use Dq instead of Qq usually. 0mp: Sorry for the confusion. Instead of Pq I meant Dq. As documented in `style.mdoc` we use Dq… | ||||||||||||
prompting the user. | ||||||||||||
Equivalent to the -y flag. | ||||||||||||
0mpUnsubmitted Done Inline Actions
I'd also add a note the flag of which program we reference here (I guess arc, but I am not sure). Also, the default value is missing. OTOH, the default is quite obvious so maybe we can skip that. 0mp: I'd also add a note the flag of which program we reference here (I guess `arc`, but I am not… | ||||||||||||
.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. | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
In this mode, the list of git revisions to create reviews for | ||||||||||||
is listed with a single prompt before creating | ||||||||||||
0mpUnsubmitted Done Inline ActionsCan we merge this and the next line into one line? 0mp: Can we merge this and the next line into one line? | ||||||||||||
reviews. | ||||||||||||
The diffs for individual commits are not | ||||||||||||
0mpUnsubmitted Done Inline ActionsCan we merge this and the next line into one line? 0mp: Can we merge this and the next line into one line? | ||||||||||||
shown. | ||||||||||||
.It Cm arc.verbose [bool] | ||||||||||||
Verbose output. | ||||||||||||
0mpUnsubmitted Done Inline ActionsShould it be expressed in an imperative form to match other definitions for consistency? 0mp: Should it be expressed in an imperative form to match other definitions for consistency? | ||||||||||||
Equivalent to the -v flag. | ||||||||||||
0mpUnsubmitted Done Inline Actions
the -v flag of arc? 0mp: the -v flag of arc? | ||||||||||||
.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": | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
.Bd -literal | ||||||||||||
.Sy $ git arc list main..feature | ||||||||||||
.Ed | ||||||||||||
.Sh SEE ALSO | ||||||||||||
.Xr build 7 | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
.Xr development 7 , | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
.Sh AUTHORS | ||||||||||||
0mpUnsubmitted Done Inline ActionsI wonder if we should add .An -nosplit here... I guess it's up to you. 0mp: I wonder if we should add `.An -nosplit` here... I guess it's up to you. | ||||||||||||
The | ||||||||||||
.Nm | ||||||||||||
utility was written by | ||||||||||||
.An Mark Johnson Aq Mt markj@FreeBSD.org | ||||||||||||
markjUnsubmitted Done Inline ActionsMy last name has a 't'. :) markj: My last name has a 't'. :) | ||||||||||||
and the manual page was written by | ||||||||||||
.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org | ||||||||||||
0mpUnsubmitted Done Inline Actions
0mp: | ||||||||||||
.Sh HISTORY | ||||||||||||
The | ||||||||||||
.Nm | ||||||||||||
utility appeared in | ||||||||||||
.Fx 14.0 . | ||||||||||||
Done Inline ActionsThis script does not get installed by default, so I'm not really sure that a history section makes much sense. At least, "appeared in FreeBSD 14.0" is a bit misleading since it technically not appear in any FreeBSD release. markj: This script does not get installed by default, so I'm not really sure that a history section… | ||||||||||||
Done Inline ActionsMaybe Appeared in the src tools collection in FreeBSD 14? emaste: Maybe Appeared in the src tools collection in FreeBSD 14? | ||||||||||||
Not Done Inline ActionsOr perhaps not in the src tree at all, and part of devel/git or devel/arcanist instead? rpokala: Or perhaps not in the src tree at all, and part of `devel/git` or `devel/arcanist` instead? | ||||||||||||
Not Done Inline ActionsBut it's not part of those ports. Are you suggesting the script be added to one of them instead? It is somewhat specific to FreeBSD development, at least for now, so I'm not sure whether that is the right place. markj: But it's not part of those ports. Are you suggesting the script be added to one of them instead? | ||||||||||||
Not Done Inline ActionsI was thinking it might be added to one of those ports, yes. Thinking aloud, anyway; whatever. <shrug> rpokala: I was thinking it might be added to one of those ports, yes. Thinking aloud, anyway; whatever. |
Perhaps this description could be simplified "git-Phabricator" doesn't look good to me, but maybe I'm just not feeling this expression. That's why I wonder if it could be simplified to make it clearer.