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, markj@FreeBSD.org 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
 }