[PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg>

From

Ævar Arnfjörð Bjarmason <avarab@gmail.com>

Date

Jun 30, 2021, 09:16 UTC

Message-ID

<patch-2.3-fe61f20f19f-20210630T091548Z-avarab@gmail.com>

In-Reply-To

<cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com>

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-bundle.txt | 40 +++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index e19c2b83c91..3bb3b71526c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -44,7 +44,8 @@ header indicating what references are contained within the bundle. The
 header is (mostly) in the format emitted by linkgit:git-show-ref[1].
 
 Like the the packed archive format itself bundles can either be
-self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+self-contained or thin, see the "OPEN (THIN) AND CLOSED BUNDLES"
+section below.
 
 See link:technical/bundle-format.html[the `bundle-format`
 documentation] for more details.
@@ -141,10 +142,20 @@ contained in the union of the given bases.  Each basis can be
 specified explicitly (e.g. `^master~10`), or implicitly (e.g.
 `master~10..master`, `--since=10.days.ago master`).
 
-It is very important that the basis used be held by the destination.
-It is okay to err on the side of caution, causing the bundle file
-to contain objects already in the destination, as these are ignored
-when unpacking at the destination.
+OPEN AND CLOSED BUNDLES
+-----------------------
+
+When creating bundles it is possible to create bundle tips that are
+either closed or open under reachability, i.e. those that contain all
+the history needed to get to a given point (closed), and those that do
+not (open). A revision such as "master" will produce a closed tip, a
+range such as "master~2..master" will not (unless the full history is
+contained within that range).
+
+When creating "open" bundles it is very important that the basis used
+be held by the destination.  It is okay to err on the side of caution,
+causing the bundle file to contain objects already in the destination,
+as these are ignored when unpacking at the destination.
 
 `git clone` can use any bundle created without negative refspecs
 (e.g., `new`, but not `old..new`).
@@ -154,6 +165,25 @@ If you want to provide the same set of refs that a clone directly
 from the source repository would get, use `--branches --tags` for
 the `<git-rev-list-args>`.
 
+THIN BUNDLES
+------------
+
+Bundles that are "open" (see above) are created "thin" by using the
+`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or
+packfile) is "thin" is a subset of whether it's "open". What "thin"
+means is that such a packfile can store an object in a deltified form
+against a base object that is not in the same packfile.
+
+To put it another way, when creating "open" bundles we assume that the
+objects leading up to the starting range(s) already exist in the
+recipient repository, which allows us to save space. When we run 'git
+bundle unbundle' we invoke linkgit:git-index-pack[1] with the
+`--fix-thin` option.
+
+See the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
+
 EXAMPLES
 --------
 

-- 
2.32.0.613.g8e17abc2eb