@matheusbsbs / matheus-bagliano / commits / ef6d3c9474

backfill: document acceptance of revision-range in more standard manner

302aff09223f (backfill: accept revision arguments, 2026-03-26) added support for passing revision arguments to 'git backfill' but documented them only with a prose sentence: You may also specify the commit limiting options from git-rev-list(1). No other command that accepts revision arguments documents them this way. Commands like log, shortlog, and replay define a formal <revision-range> entry and include rev-list-options.adoc. Commands like bundle, fast-export, and filter-branch, which pass arguments through to the revision machinery without including the full options file, still define a formal <git-rev-list-args> entry explaining what is accepted. Add a formal <revision-range> entry in the synopsis and OPTIONS section, following the convention used by other commands, and mention that commit-limiting options from git-rev-list(1) are also accepted. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Elijah Newren committed Apr 15, 2026 at 23:58 UTC ef6d3c94746462ec560893ed35c83df485a6344d
2 files changed +13 -4
Documentation/git-backfill.adoc
+12 -3
@@ -9,7 +9,7 @@ git-backfill - Download missing objects in a partial clone
9 SYNOPSIS
10 --------
11 [synopsis]
12 -git backfill [--min-batch-size=<n>] [--[no-]sparse]
12 +git backfill [--min-batch-size=<n>] [--[no-]sparse] [<revision-range>]
13
14 DESCRIPTION
15 -----------
@@ -43,7 +43,7 @@ smaller network calls than downloading the entire repository at clone
43 time.
44
45 By default, `git backfill` downloads all blobs reachable from the `HEAD`
46 -commit. This set can be restricted or expanded using various options.
46 +commit. This set can be restricted or expanded using various options below.
47
48 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.
49
@@ -63,7 +63,16 @@ OPTIONS
63 current sparse-checkout. If the sparse-checkout feature is enabled,
64 then `--sparse` is assumed and can be disabled with `--no-sparse`.
65
66 -You may also specify the commit limiting options from linkgit:git-rev-list[1].
66 +`<revision-range>`::
67 + Backfill only blobs reachable from commits in the specified
68 + revision range. When no _<revision-range>_ is specified, it
69 + defaults to `HEAD` (i.e. the whole history leading to the
70 + current commit). For a complete list of ways to spell
71 + _<revision-range>_, see the "Specifying Ranges" section of
72 + linkgit:gitrevisions[7].
73 ++
74 +You may also use commit-limiting options understood by
75 +linkgit:git-rev-list[1] such as `--first-parent`, `--since`, or pathspecs.
76
77 SEE ALSO
78 --------
builtin/backfill.c
+1 -1
@@ -26,7 +26,7 @@
26 #include "path-walk.h"
27
28 static const char * const builtin_backfill_usage[] = {
29 - N_("git backfill [--min-batch-size=<n>] [--[no-]sparse]"),
29 + N_("git backfill [--min-batch-size=<n>] [--[no-]sparse] [<revision-range>]"),
30 NULL
31 };
32