Page MenuHomeFreeBSD
Differential D28519 Diff 83793 tools/tools/git/git-arc.1

Changeset View

Standalone View

View Options

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 a wrapper to improve integration betwen git and arcanist
.Sh SYNOPSIS
0mpUnsubmitted
Done
Inline Actions

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.

0mp: Perhaps this description could be simplified "git-Phabricator" doesn't look good to me, but…
.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
debdrupAuthorUnsubmitted
Done
Inline Actions

Is 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 Actions

Kind 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…
.Nm
.Cm update
.Op Ar branch Oo Ar commit Ns | Ns Ar commit-range Oc
.Sh DESCRIPTION
markjUnsubmitted
Done
Inline Actions

I would s/or/and/.

markj: I would s/or/and/.
The
.Nm
utility creates and manages
.Fx
markjUnsubmitted
Done
Inline Actions
Phabricator reviews based on git commits.
.Pp
- There is a one-to-one relationship between git commits and
+ .Nm
+ assumes a one-to-one relationship between git commits and
Differential revisions, and the Differential revision title must match

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 Actions

Shouldn't we stylize git as Git in such cases?

0mp: Shouldn't we stylize git as `Git` in such cases?
Phabricator reviews based on git commits.
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…
.Pp
markjUnsubmitted
Done
Inline Actions
Differential revisions, and the Differential revision title must match
- the summary line of the corresponding commit.
+ the summary line of the corresponding commit.
In Particular, the commit summaries must be unique across all open
markj:
Git
markjUnsubmitted
Done
Inline Actions
the summary line of the corresponding commit.
- In Particular, the commit summaries must be unique across all open
+ In particular, the commit summaries must be unique across all open
Differential revisions authored the submitter.
markj:
0mpUnsubmitted
Done
Inline Actions
the summary line of the corresponding commit.
- In Particular, the commit summaries must be unique across all open
+ In particular, the commit summaries must be unique across all open
Differential revisions authored the submitter.
0mp:
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.
0mpUnsubmitted
Done
Inline Actions

I 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…
.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
0mpUnsubmitted
Done
Inline Actions

Since 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.
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
0mpUnsubmitted
Done
Inline Actions

Perhaps 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…
Synchronize the Differential Revisions associated with the
0mpUnsubmitted
Done
Inline Actions

This is not needed. Please see the output of mandoc -Tlint.

0mp: This is not needed. Please see the output of `mandoc -Tlint`.
specified commits.
Currently only the diff is updated; the review description and other
metadata is not synchronized.
.El
0mpUnsubmitted
Done
Inline Actions

I'd add -offset indent for every Bd in this section.

0mp: I'd add `-offset indent` for every `Bd` in this section.
.Sh CONFIGURATION
0mpUnsubmitted
Done
Inline Actions

Usually, 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…
These are manipulated by
.Nm git-config :
.Bl -tag -width "arc.assume_yes" -offset indent
.It Va arc.assume_yes
0mpUnsubmitted
Done
Inline Actions

Could [bool] be dropped now?

0mp: Could `[bool]` be dropped now?
0mpUnsubmitted
Not Done
Inline Actions

I'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 :)
Assume a
0mpUnsubmitted
Done
Inline Actions

Typo? s/review/revision/?

0mp: Typo? s/review/revision/?
.Dq yes
answer to all prompts instead of
prompting the user.
Equivalent to the
.Fl -y
flag.
0mpUnsubmitted
Not Done
Inline Actions
Equivalent to the
- .Fl -y
+ .Fl y
flag.

Typo

0mp: Typo
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
0mpUnsubmitted
Done
Inline Actions
.Sh CONFIGURATION
- These are manipulated by git-config(1):
+ These are manipulated by
+ .Xr git-config 1 :
.Bl -tag -width "arc.assume_yes [bool]" -offset indent

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.
.Pq Fl l
with create.
0mpUnsubmitted
Done
Inline Actions
.Bl -tag -width "arc.assume_yes [bool]" -offset indent
- .It Cm arc.assume_yes [bool]
+ .It Cm arc.assume_yes No [bool]
Assume a "yes" answer to all prompts instead of

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…
In this mode, the list of git revisions to create reviews for
0mpUnsubmitted
Done
Inline Actions
.It Cm arc.assume_yes [bool]
- Assume a "yes" answer to all prompts instead of
+ Assume a
+ .Pq yes
+ answer to all prompts instead of
prompting the user.

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 Actions

I 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 Actions

Sorry 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…
is listed with a single prompt before creating reviews.
The diffs for individual commits are not shown.
0mpUnsubmitted
Done
Inline Actions
prompting the user.
- Equivalent to the -y flag.
+ Equivalent to the
+ .Fl y
+ flag.
.It Cm arc.browse [bool]

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…
Defaults to false.
.It Va arc.verbose
Always use verbose output.
Equivalent to the
.Fl v
0mpUnsubmitted
Done
Inline Actions
.It Cm arc.list [bool]
- Always use "list mode" (-l) with create.
+ Always use
+ .Pq list mode
+ .Po Fl l
+ with create.
In this mode, the list of git revisions to create reviews for
0mp:
flag.
Defaults to false.
0mpUnsubmitted
Done
Inline Actions

Can we merge this and the next line into one line?

0mp: Can we merge this and the next line into one line?
.El
.Sh EXAMPLES
0mpUnsubmitted
Done
Inline Actions

Can we merge this and the next line into one line?

0mp: Can we merge this and the next line into one line?
The typical end-to-end usage looks something like this.
.Pp
Commit changes with a message and create a Differential review:
0mpUnsubmitted
Done
Inline Actions

Should 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?
.Bd -literal -offset indent
0mpUnsubmitted
Done
Inline Actions
Verbose output.
- Equivalent to the -v flag.
+ Equivalent to the
+ .Fl -v
+ flag.
.Sh EXAMPLES

the -v flag of arc?

0mp: the -v flag of arc?
$ 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@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:
0mpUnsubmitted
Done
Inline Actions
List the status of reviews for all the commits in the branch
- "feature":
+ .Pq feature :
.Bd -literal
0mp:
.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
0mpUnsubmitted
Done
Inline Actions
.Sh SEE ALSO
- .Xr build 7
+ .Xr build 7 ,
.Xr development 7 ,
0mp:
was created.
0mpUnsubmitted
Done
Inline Actions
.Xr build 7
- .Xr development 7 ,
+ .Xr development 7
.Sh AUTHORS
0mp:
Note that the review description is not automatically updated.
0mpUnsubmitted
Done
Inline Actions

I 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.
.Pp
Apply the patch in review D12345 to the currently checked-out tree,
and stage it:
.Bd -literal -offset indent
markjUnsubmitted
Done
Inline Actions

My last name has a 't'. :)

markj: My last name has a 't'. :)
$ git arc patch D12345
.Ed
0mpUnsubmitted
Done
Inline Actions
and the manual page was written by
- .An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org
+ .An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org .
.Sh HISTORY
0mp:
.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
markjUnsubmitted
Done
Inline Actions

This 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…
emasteUnsubmitted
Done
Inline Actions

Maybe Appeared in the src tools collection in FreeBSD 14?

emaste: Maybe Appeared in the src tools collection in FreeBSD 14?
rpokalaUnsubmitted
Not Done
Inline Actions

Or 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?
markjUnsubmitted
Not Done
Inline Actions

But 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?
rpokalaUnsubmitted
Not Done
Inline Actions

I 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.
.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@FreeBSD.org
and the manual page was written by
.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org .