The branch main has been updated by markj: URL: https://cgit.FreeBSD.org/src/commit/?id=1c8dafe618878c563c3740061f83a85b0be10720
commit 1c8dafe618878c563c3740061f83a85b0be10720 Author: Mark Johnston <[email protected]> AuthorDate: 2026-01-05 14:17:21 +0000 Commit: Mark Johnston <[email protected]> CommitDate: 2026-01-05 14:17:21 +0000 git-arc: Try to improve documentation When I originally wrote git-arc, the usage string was the documentation. Later, a man page was added, largely copied from the usage string. Over time they have diverged slightly. It is silly to have two copies of the same information, so let's make the man page the source of truth. While here, document some options for git-arc-patch and rewrite a few sentences here and there in a way that I hope is clearer. Reviewed by: ziaee, ngie, adrian Differential Revision: https://reviews.freebsd.org/D54405 --- tools/tools/git/git-arc.1 | 81 +++++++++++++++++++++++++++++--------- tools/tools/git/git-arc.sh | 96 +--------------------------------------------- 2 files changed, 64 insertions(+), 113 deletions(-) diff --git a/tools/tools/git/git-arc.1 b/tools/tools/git/git-arc.1 index a056a2223e0e..0e2615d83fa4 100644 --- a/tools/tools/git/git-arc.1 +++ b/tools/tools/git/git-arc.1 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd Janurary 15, 2025 +.Dd December 29, 2025 .Dt GIT-ARC 1 .Os .Sh NAME @@ -37,40 +37,59 @@ .Op Fl r Ar reviewer1 Ns Op Cm \&, Ns Ar reviewer2 ... .Op Fl s Ar subscriber1 Ns Op Cm \&, Ns Ar subscriber2 ... .Op Fl p Ar parent -.Op Ar commit ... Ns | Ns Ar commit-range +.Ar commit-ref Op Ar commit-ref ... .Nm -.Cm list Ar commit ... Ns | Ns Ar commit-range +.Cm list Ar commit-ref Op Ar commit-ref ... .Nm +.Op Fl bcrs .Cm patch .Op Fl c -.Ar diff1 Ns Op Cm \&, Ns Ar diff2 +.Ar diff1 Op Cm Ar diff2 Op Ar ... .Nm .Cm stage .Op Fl b Ar branch -.Op Ar commit ... Ns | Ns Ar commit-range +.Ar commit-ref Op Ar commit-ref ... .Nm .Cm update .Op Fl l .Op Fl m Ar message -.Op Ar commit ... Ns | Ns Ar commit-range +.Ar commit-ref Op Ar commit-ref ... .Sh DESCRIPTION The .Nm utility creates and manages .Fx Phabricator reviews based on git commits. +It is geared towards +.Fx +development. It requires the -.Pa devel/arcanist -port or package. +.Pa devel/git , +.Pa devel/arcanist-lib +and +.Pa textproc/jq +packages; these will be installed automatically if +.Nm +is installed via the +.Pa devel/freebsd-git-devtools +package. .Pp .Nm 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, and requires the titles in a pair to match. +Commit titles must therefore be unique across all open Differential Revisions authored by the submitter. +If the title of either a commit or its associated Differential Revision is +changed, the other must be updated manually to maintain the match. .Pp The first parameter must be a verb. +Most verbs accept one or more git commit references: commit hashes, branch +names, commit ranges, and so on. +A branch name refers to the single commit at its tip; use a commit range to +operate on multiple commits. +See +.Xr git-rev-parse 1 +for details on specifying commit references. The available verbs are: .Bl -tag -width "create" .It Cm create @@ -96,19 +115,45 @@ stack in Phabricator. .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 +Try to apply patches from one or more Differential Revision to the currently checked out tree. +The following options are accepted: +.Bl -tag -width "-b" +.It Fl b +Switch to a new branch before applying the patches. +.It Fl c +Commit each applied patch to the git checkout. +The commit message and author are taken from the Differential Revision. +.It Fl r +Rather than using the +.Sy arc +command to apply the patch, download the raw patch file and apply it using +.Xr git-apply 1 . +This is useful for avoiding some misfeatures of +.Sy arc , +particularly its behavior of trying to update all remotes in the tree in some +cases. +.It Fl s +Recursively apply the parent revisions of the specified commit. +This can be used to apply patch stacks by specifying the top-most, i.e., +most recent commit in the stack. +.El .It Cm stage 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 +.Pp +First, the target branch is checked out; by default this is the +main branch but can be overridden with the +.Fl b +option. +Then, the specified commits are cherry-picked with review tags added to the +commit log message, and the log message is opened in an editor for any final updates. -The commits need not have associated Differential -Revisions. +The commits need not have associated Differential Revisions. +.Pp +This is intended to be used after code review has been completed, and the +commits are ready to be pushed to an upstream repository. .It Cm update Synchronize the Differential Revisions associated with the specified commits. diff --git a/tools/tools/git/git-arc.sh b/tools/tools/git/git-arc.sh index bff9b0607761..f15cade1f1e7 100755 --- a/tools/tools/git/git-arc.sh +++ b/tools/tools/git/git-arc.sh @@ -63,102 +63,8 @@ Commands: stage [-b branch] [<commit>|<commit range>] update [-l] [-m message] [<commit>|<commit range>] -Description: - Create or manage FreeBSD Phabricator reviews based on git commits. 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, commit summaries must be unique across - all open Differential revisions authored by you. - - The first parameter must be a verb. The available verbs are: - - create -- Create new Differential revisions from the specified commits. - list -- Print the associated Differential revisions for the specified - commits. - patch -- Apply patches from Differential revisions. By default, patches - are applied to the currently checked-out tree, unless -b is - supplied, in which case a new branch is first created. The -c - option commits the applied patch using the review's metadata. - stage -- Prepare a series of commits to be pushed to the upstream FreeBSD - 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. - 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. - - The typical end-to-end usage looks something like this: - - $ git commit -m "kern: Rewrite in Rust" - $ git arc create HEAD - <Make changes to the diff based on reviewer feedback.> - $ git commit --amend - $ git arc update HEAD - <Now that all reviewers are happy, it's time to push.> - $ git arc stage HEAD - $ git push freebsd HEAD:main - -Config Variables: - These are manipulated by git-config(1). - - arc.assume_yes [bool] - -- Assume a "yes" answer to all prompts instead of - prompting the user. Equivalent to the -y flag. - - arc.browse [bool] -- Try to open newly created reviews in a browser tab. - Defaults to false. - - arc.list [bool] -- Always use "list mode" (-l) with create and update. - In this mode, the list of git revisions to use - is listed with a single prompt before creating or - updating reviews. The diffs for individual commits - are not shown. - - arc.verbose [bool] -- Verbose output. Equivalent to the -v flag. - -Examples: - 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, [email protected] is added as - a reviewer. Also, the "Jails" reviewer group is added using its hashtag. - - $ git arc create -r markj,#jails 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. - - $ git arc create HEAD~3..HEAD - - 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. - - $ git arc update b409afcfedcdda - - Apply the patch in review D12345 to the currently checked-out tree, and stage - it. - - $ git arc patch D12345 - - Apply the patch in review D12345 to the currently checked-out tree, and - commit it using the review's title, summary and author. - - $ git arc patch -c D12345 - - Apply the patches in reviews D12345 and D12346 in a new branch, and commit - them using the review titles, summaries and authors. - - $ git arc patch -bc D12345 D12346 - - List the status of reviews for all the commits in the branch "feature": - - $ git arc list main..feature - +See git-arc(1) for details. __EOF__ - exit 1 }
