bundle doc: elaborate on object prerequisites
Split out the discussion bout "object prerequisites" into its own section, and add some more examples of the common cases. See 2e0afafebd (Add git-bundle: move objects and references by archive, 2007-02-22) for the introduction of the documentation being changed here. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Jul 31, 2021 at 10:23 UTC
9ab80dd6aeadf398de45a6add5fc7ed6b2e166b7
1 file changed
+34
-3
Documentation/git-bundle.txt
+34
-3
@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.
44
45
Like the the packed archive format itself bundles can either be
46
self-contained, or be created using exclusions.
47
+See the "OBJECT PREREQUISITES" section below.
48
49
Bundles created using revision exclusions are "thin packs" created
50
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -152,19 +153,49 @@ contained in the union of the given bases. Each basis can be
153
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
154
`master~10..master`, `--since=10.days.ago master`).
155
155
-It is very important that the basis used be held by the destination.
156
+OBJECT PREREQUISITES
157
+--------------------
158
+
159
+When creating bundles it is possible to create a self-contained bundle
160
+that can be unbundled in a repository with no common history, as well
161
+as providing negative revisions to exclude objects needed in the
162
+earlier parts of the history.
163
+
164
+Feeding a revision such as `new` to `git bundle create` will create a
165
+bundle file that contains all the objects reachable from the revision
166
+`new`. That bundle can be unbundled in any repository to obtain a full
167
+history that leads to the revision `new`:
168
+
169
+----------------
170
+$ git bundle create full.bundle new
171
+----------------
172
+
173
+A revision range such as `old..new` will produce a bundle file that
174
+will require the revision `old` (and any objects reachable from it)
175
+to exist for the bundle to be "unbundle"-able:
176
+
177
+----------------
178
+$ git bundle create full.bundle old..new
179
+----------------
180
+
181
+A self-contained bundle without any prerequisites can be extracted
182
+into anywhere, even into an empty repository, or be cloned from
183
+(i.e., `new`, but not `old..new`).
184
+
185
It is okay to err on the side of caution, causing the bundle file
186
to contain objects already in the destination, as these are ignored
187
when unpacking at the destination.
188
160
-`git clone` can use any bundle created without negative refspecs
161
-(e.g., `new`, but not `old..new`).
189
If you want to match `git clone --mirror`, which would include your
190
refs such as `refs/remotes/*`, use `--all`.
191
If you want to provide the same set of refs that a clone directly
192
from the source repository would get, use `--branches --tags` for
193
the `<git-rev-list-args>`.
194
195
+The 'git bundle verify' command can be used to check whether your
196
+recipient repository has the required prerequisite commits for a
197
+bundle.
198
+
199
EXAMPLES
200
--------
201