git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 2/3] backfill: document acceptance of revision-range in more standard manner

From
Elijah Newren via GitGitGadget <gitgitgadget@gmail.com>
Date
Apr 15, 2026, 23:58 UTC
Message-ID
<173831ec92ea712a72f790f3a8eea6643ef7488b.1776297482.git.gitgitgadget@gmail.com>
In-Reply-To
<pull.2088.git.1776297482.gitgitgadget@gmail.com>
From: Elijah Newren <newren@gmail.com>

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>
---
 Documentation/git-backfill.adoc | 15 ++++++++++++---
 builtin/backfill.c              |  2 +-
 2 files changed, 13 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc
index 246ab417c2..bf26d7694f 100644
--- a/Documentation/git-backfill.adoc
+++ b/Documentation/git-backfill.adoc
@@ -9,7 +9,7 @@ git-backfill - Download missing objects in a partial clone
 SYNOPSIS
 --------
 [synopsis]
-git backfill [--min-batch-size=<n>] [--[no-]sparse]
+git backfill [--min-batch-size=<n>] [--[no-]sparse] [<revision-range>]
 
 DESCRIPTION
 -----------
@@ -43,7 +43,7 @@ smaller network calls than downloading the entire repository at clone
 time.
 
 By default, `git backfill` downloads all blobs reachable from the `HEAD`
-commit. This set can be restricted or expanded using various options.
+commit. This set can be restricted or expanded using various options below.
 
 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.
 
@@ -63,7 +63,16 @@ OPTIONS
 	current sparse-checkout. If the sparse-checkout feature is enabled,
 	then `--sparse` is assumed and can be disabled with `--no-sparse`.
 
-You may also specify the commit limiting options from linkgit:git-rev-list[1].
+`<revision-range>`::
+	Backfill only blobs reachable from commits in the specified
+	revision range.  When no _<revision-range>_ is specified, it
+	defaults to `HEAD` (i.e. the whole history leading to the
+	current commit).  For a complete list of ways to spell
+	_<revision-range>_, see the "Specifying Ranges" section of
+	linkgit:gitrevisions[7].
++
+You may also use commit-limiting options understood by
+linkgit:git-rev-list[1] such as `--first-parent`, `--since`, or pathspecs.
 
 SEE ALSO
 --------
diff --git a/builtin/backfill.c b/builtin/backfill.c
index a9edddcb7e..e934d360fd 100644
--- a/builtin/backfill.c
+++ b/builtin/backfill.c
@@ -26,7 +26,7 @@
 #include "path-walk.h"
 
 static const char * const builtin_backfill_usage[] = {
-	N_("git backfill [--min-batch-size=<n>] [--[no-]sparse]"),
+	N_("git backfill [--min-batch-size=<n>] [--[no-]sparse] [<revision-range>]"),
 	NULL
 };
 
-- 
gitgitgadget
Previous: Derrick StoleeNext: Derrick Stolee
Message 4 of 8 in “Backfill fixes and edges”
  1. 0/3 Backfill fixes and edgesElijah Newren via GitGitGadget, Apr 15, 2026
  2. 1/3 backfill: reject rev-list arguments that do not make senseElijah Newren via GitGitGadget, Apr 15, 2026
  3. Derrick StoleeApr 16, 2026
  4. 2/3 backfill: document acceptance of revision-range in more standard mannerElijah Newren via GitGitGadget, Apr 15, 2026
  5. Derrick StoleeApr 16, 2026
  6. 3/3 backfill: default to grabbing edge blobs tooElijah Newren via GitGitGadget, Apr 15, 2026
  7. Derrick StoleeApr 16, 2026
  8. Derrick StoleeApr 16, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.