[PATCH v3 2/3] bundle doc: split out thin v.s. not discussion from <rev-arg>

From

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

Date

Jun 24, 2021, 19:40 UTC

Message-ID

<patch-2.3-63f871a0c72-20210624T193730Z-avarab@gmail.com>

In-Reply-To

<cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com>

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 1b02f8b7468..f231f42b12f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -42,7 +42,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.
@@ -139,7 +140,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.
+OPEN (THIN) 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).
+
+Another name for "open" bundles might be "thin bundles", as in the
+`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's
+what `git bundle create` uses to write bundles. When thin 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.
@@ -152,6 +166,11 @@ 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>`.
 
+See the the `--thin` option to linkgit:git-pack-objects[1] noted
+above, and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
+
 EXAMPLES
 --------
 

-- 
2.32.0.610.gd639e370050