git-backfill.adoc

git-backfill(1)
===============

NAME
----
git-backfill - Download missing objects in a partial clone


SYNOPSIS
--------
[synopsis]
git backfill [--min-batch-size=<n>] [--[no-]sparse] [--[no-]include-edges] [<revision-range>]

DESCRIPTION
-----------

Blobless partial clones are created using `git clone --filter=blob:none`
and then configure the local repository such that the Git client avoids
downloading blob objects unless they are required for a local operation.
This initially means that the clone and later fetches download reachable
commits and trees but no blobs. Later operations that change the `HEAD`
pointer, such as `git checkout` or `git merge`, may need to download
missing blobs in order to complete their operation.

In the worst cases, commands that compute blob diffs, such as `git blame`,
become very slow as they download the missing blobs in single-blob
requests to satisfy the missing object as the Git command needs it. This
leads to multiple download requests and no ability for the Git server to
provide delta compression across those objects.

The `git backfill` command provides a way for the user to request that
Git downloads the missing blobs (with optional filters) such that the
missing blobs representing historical versions of files can be downloaded
in batches. The `backfill` command attempts to optimize the request by
grouping blobs that appear at the same path, hopefully leading to good
delta compression in the packfile sent by the server.

In this way, `git backfill` provides a mechanism to break a large clone
into smaller chunks. Starting with a blobless partial clone with `git
clone --filter=blob:none` and then running `git backfill` in the local
repository provides a way to download all reachable objects in several
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 below.

THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.


OPTIONS
-------

`--min-batch-size=<n>`::
	Specify a minimum size for a batch of missing objects to request
	from the server. This size may be exceeded by the last set of
	blobs seen at a given path. The default minimum batch size is
	50,000.

`--sparse`::
`--no-sparse`::
	Only download objects if they appear at a path that matches the
	current sparse-checkout. If the sparse-checkout feature is enabled,
	then `--sparse` is assumed and can be disabled with `--no-sparse`.

`--include-edges`::
`--no-include-edges`::
	Include blobs from boundary commits in the backfill.  Useful in
	preparation for commands like `git log -p A..B` or `git replay
	--onto TARGET A..B`, where A..B normally excludes A but you need
	the blobs from A as well.  `--include-edges` is the default.

`<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.
+
Most `--filter=<spec>` options don't work with the purpose of
`git backfill`, but the `sparse:<oid>` filter is integrated to provide a
focused set of paths to download, distinct from the `--sparse` option.

SEE ALSO
--------
linkgit:git-clone[1],
linkgit:git-rev-list[1]

GIT
---
Part of the linkgit:git[1] suite