| 1 | git-backfill(1) |
| 2 | =============== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-backfill - Download missing objects in a partial clone |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git backfill [--min-batch-size=<n>] [--[no-]sparse] [--[no-]include-edges] [<revision-range>] |
| 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | |
| 17 | Blobless partial clones are created using `git clone --filter=blob:none` |
| 18 | and then configure the local repository such that the Git client avoids |
| 19 | downloading blob objects unless they are required for a local operation. |
| 20 | This initially means that the clone and later fetches download reachable |
| 21 | commits and trees but no blobs. Later operations that change the `HEAD` |
| 22 | pointer, such as `git checkout` or `git merge`, may need to download |
| 23 | missing blobs in order to complete their operation. |
| 24 | |
| 25 | In the worst cases, commands that compute blob diffs, such as `git blame`, |
| 26 | become very slow as they download the missing blobs in single-blob |
| 27 | requests to satisfy the missing object as the Git command needs it. This |
| 28 | leads to multiple download requests and no ability for the Git server to |
| 29 | provide delta compression across those objects. |
| 30 | |
| 31 | The `git backfill` command provides a way for the user to request that |
| 32 | Git downloads the missing blobs (with optional filters) such that the |
| 33 | missing blobs representing historical versions of files can be downloaded |
| 34 | in batches. The `backfill` command attempts to optimize the request by |
| 35 | grouping blobs that appear at the same path, hopefully leading to good |
| 36 | delta compression in the packfile sent by the server. |
| 37 | |
| 38 | In this way, `git backfill` provides a mechanism to break a large clone |
| 39 | into smaller chunks. Starting with a blobless partial clone with `git |
| 40 | clone --filter=blob:none` and then running `git backfill` in the local |
| 41 | repository provides a way to download all reachable objects in several |
| 42 | 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 below. |
| 47 | |
| 48 | THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE. |
| 49 | |
| 50 | |
| 51 | OPTIONS |
| 52 | ------- |
| 53 | |
| 54 | `--min-batch-size=<n>`:: |
| 55 | Specify a minimum size for a batch of missing objects to request |
| 56 | from the server. This size may be exceeded by the last set of |
| 57 | blobs seen at a given path. The default minimum batch size is |
| 58 | 50,000. |
| 59 | |
| 60 | `--sparse`:: |
| 61 | `--no-sparse`:: |
| 62 | Only download objects if they appear at a path that matches the |
| 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 | `--include-edges`:: |
| 67 | `--no-include-edges`:: |
| 68 | Include blobs from boundary commits in the backfill. Useful in |
| 69 | preparation for commands like `git log -p A..B` or `git replay |
| 70 | --onto TARGET A..B`, where A..B normally excludes A but you need |
| 71 | the blobs from A as well. `--include-edges` is the default. |
| 72 | |
| 73 | `<revision-range>`:: |
| 74 | Backfill only blobs reachable from commits in the specified |
| 75 | revision range. When no _<revision-range>_ is specified, it |
| 76 | defaults to `HEAD` (i.e. the whole history leading to the |
| 77 | current commit). For a complete list of ways to spell |
| 78 | _<revision-range>_, see the "Specifying Ranges" section of |
| 79 | linkgit:gitrevisions[7]. |
| 80 | + |
| 81 | You may also use commit-limiting options understood by |
| 82 | linkgit:git-rev-list[1] such as `--first-parent`, `--since`, or pathspecs. |
| 83 | + |
| 84 | Most `--filter=<spec>` options don't work with the purpose of |
| 85 | `git backfill`, but the `sparse:<oid>` filter is integrated to provide a |
| 86 | focused set of paths to download, distinct from the `--sparse` option. |
| 87 | |
| 88 | SEE ALSO |
| 89 | -------- |
| 90 | linkgit:git-clone[1], |
| 91 | linkgit:git-rev-list[1] |
| 92 | |
| 93 | GIT |
| 94 | --- |
| 95 | Part of the linkgit:git[1] suite |