Skip to contentSkip to conversation

bundle doc: rewrite the "DESCRIPTION" section

PATCH Superseded Ævar Arnfjörð Bjarmason 3 participants 41 messages Jun 7, 2021 – Jul 31, 2021 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for. This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

---
 Documentation/git-bundle.txt | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)
Documentation/git-bundle.txt +22 -9
index 53804cad4b..1d7c6bdbb2 100644
@@ -3,7 +3,7 @@ git-bundle(1)
 
 NAME
 ----
-git-bundle - Move objects and refs by archive
+git-bundle - Create, unpack and manipulate "bundles"
 
 
 SYNOPSIS
@@ -18,15 +18,25 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
+what references are contained within the bundle. The header is in the
+format emitted by linkgit:git-show-ref[1].
 
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
+Like the the packed archive format itself bundles can either be
+self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+
+Bundles are useful for numerous purposes. They were originally
+designed to facilitate the transfer of repository data between
+repositories which could not be directly connect to each other, and
+therefore the interactive Git protocols (git, ssh, http) could not be
+used.
+
+In that scenario a bundle is produced on the originating machine. It
+is then transferred to the other machine (e.g. by sneakernet), and
+unpacked on the other end. The unpacking can happen either with
+linkgit:git-clone[1] (which knows how to clone from bundle files), or
+by "git bundle unbundle".
 
 As no
 direct connection between the repositories exists, the user must specify a
@@ -34,6 +44,9 @@ basis for the bundle that is held by the destination repository: the
 bundle assumes that all objects in the basis are already in the
 destination repository.
 
+Similarly, bundles are commonly used to produce incremental backups of
+git repositories. See the "EXAMPLES" section below.
+
 OPTIONS
 -------
 
Signature · 1 line
2.32.0.rc3.434.gd8aed1f08a7
#1 lore raw

PATCH v2 1/1 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for. This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

---

I didn't think I needed to type "make" to check a doc-only change, but as it turns out v1 of this doesn't compile git because the script to generate command-list.h doesn't know how to escape the quotes in the C-string it generates.

This is probably better in either case, sorry about the noise.

Range-diff against v1:
1: 4e736877d1 ! 1: bc6a6d8922 bundle doc: rewrite the "DESCRIPTION" section
@@ Documentation/git-bundle.txt: git-bundle(1)
NAME
----
-git-bundle - Move objects and refs by archive
-+git-bundle - Create, unpack and manipulate "bundles" ++git-bundle - Create, unpack and manipulate bundles

SYNOPSIS

 Documentation/git-bundle.txt | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)
Documentation/git-bundle.txt +22 -9
index 53804cad4b..cdc4e0b51b 100644
@@ -3,7 +3,7 @@ git-bundle(1)
 
 NAME
 ----
-git-bundle - Move objects and refs by archive
+git-bundle - Create, unpack and manipulate bundles
 
 
 SYNOPSIS
@@ -18,15 +18,25 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
+what references are contained within the bundle. The header is in the
+format emitted by linkgit:git-show-ref[1].
 
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
+Like the the packed archive format itself bundles can either be
+self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+
+Bundles are useful for numerous purposes. They were originally
+designed to facilitate the transfer of repository data between
+repositories which could not be directly connect to each other, and
+therefore the interactive Git protocols (git, ssh, http) could not be
+used.
+
+In that scenario a bundle is produced on the originating machine. It
+is then transferred to the other machine (e.g. by sneakernet), and
+unpacked on the other end. The unpacking can happen either with
+linkgit:git-clone[1] (which knows how to clone from bundle files), or
+by "git bundle unbundle".
 
 As no
 direct connection between the repositories exists, the user must specify a
@@ -34,6 +44,9 @@ basis for the bundle that is held by the destination repository: the
 bundle assumes that all objects in the basis are already in the
 destination repository.
 
+Similarly, bundles are commonly used to produce incremental backups of
+git repositories. See the "EXAMPLES" section below.
+
 OPTIONS
 -------
 
Signature · 1 line
2.32.0.rc3.434.gd8aed1f08a7
#2 lore raw
Quoted 6 lines · Ævar Arnfjörð Bjarmason

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for. This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

OK.

Documentation/git-bundle.txt git-bundle(1) · line 6

Quoted 4 lines

NAME
----

Documentation/git-bundle.txt +1 -1
-git-bundle - Move objects and refs by archive
+git-bundle - Create, unpack and manipulate bundles

While I find the updated description an improvement, I do not think the updated one-line explanation is. Not that "archive" is much better than "bundles", but to those who needs "git-bundle" explained, it is better not to use the same word "bundle" to do so, and worse, when one does not know what "bundles" are, "do X, Y or Z" on that unknown thing would not help understanding all that much. At least, the original _hints_ that it is related to some way to transport Git data (by mentioning "objects and refs"), and those with good instinct may even guess that it is an offline transport (with the hint the word "archive" leaves).

Documentation/git-bundle.txt SYNOPSIS · line 24

Quoted 8 lines
Documentation/git-bundle.txt +4 -4
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
+what references are contained within the bundle. The header is in the
+format emitted by linkgit:git-show-ref[1].

Before going into the composition of a bundle, can we touch the reason why we create such a thing? It is to help "offline" Git transfer without common history discovery.

That is,

Create, unpack, and manipulate "bundle" files, that helps "offline" transfer of Git objects without an active "server" sitting on the other side of the network connection.

or something.

#3 lore raw

v3 cover bundle doc: generaliz & elaborate

In reply to Ævar Arnfjörð Bjarmason

This started as 1 patch in
https://lore.kernel.org/git/[email protected]/
but is now 3.

In rewriting the DESCRIPTION section per Junio's feedback I went on to elaborate on the thin v.s. not thin bundles and in 3/3 rewrote some prose to make heavier use of show and tell.

Per a certain recent CodingGuidelines discussion about patterns in our documentation I've long thought that the sort of change I'm doing in 3/3 is something we could do more of. I.e. replacing somewhat complex and dense prose with short paragraphs broken up by simple command examples (and output), whenever possible.

Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section bundle doc: split out thin v.s. not discussion from <rev-arg> bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 111 +++++++++++++++++++++++++++--------
 1 file changed, 87 insertions(+), 24 deletions(-)

Range-diff against v2:
1: bc6a6d89224 ! 1: 2824133f423 bundle doc: rewrite the "DESCRIPTION" section
@@ Commit message

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly
- into one example of what they might be used for. This changes
- documentation that's been substantially the same ever since the
- command was added in 2e0afafebd8 (Add git-bundle: move objects and
- references by archive, 2007-02-22).
+ into one example of what they might be used for.
+
+ This changes documentation that's been substantially the same ever
+ since the command was added in 2e0afafebd8 (Add git-bundle: move
+ objects and references by archive, 2007-02-22).
+
+ I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
+ section, it briefly discusses the format, but then links to the
+ technical/bundle-format.txt documentation.
+
+ The "the user must specify a basis" part of this is discussed below in
+ "SPECIFYING REFERENCES", so I'm removing that part and letting the
+ brief mention of "thin" suffice.
+
+ To the extent that we should say more on the topic that documentation
+ will be improved by subsequent commits.

## Documentation/git-bundle.txt ##
-@@ Documentation/git-bundle.txt: git-bundle(1)
-
- NAME
- ----
--git-bundle - Move objects and refs by archive
-+git-bundle - Create, unpack and manipulate bundles
-
-
- SYNOPSIS
@@ Documentation/git-bundle.txt: SYNOPSIS
DESCRIPTION
-----------
@@ Documentation/git-bundle.txt: SYNOPSIS
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
-+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
-+what references are contained within the bundle. The header is in the
-+format emitted by linkgit:git-show-ref[1].
-
+-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
+-
+-As no
+-direct connection between the repositories exists, the user must specify a
+-basis for the bundle that is held by the destination repository: the
+-bundle assumes that all objects in the basis are already in the
+-destination repository.
++Create, unpack, and manipulate "bundle" files. Bundles are used for
++the "offline" transfer of Git objects without an active "server"
++sitting on the other side of the network connection.
++
++They can be used to create both incremental and full backups of a
++repository, and to relay the state of the references in one repository
++to another.
++
++Other git commands that understand protocols such as ssh:// and
++https:// can also operate on bundle files. It is possible
++linkgit:git-clone[1] a new repository from a bundle, to use
++linkgit:git-fetch[1] to fetch from one, and to list the references
++contained within it with linkgit:git-ls-remote[1].
++
++See the "EXAMPLES" section below for examples of how to use bundles.
++
++BUNDLE FORMAT
++-------------
++
++Bundles are .pack files (see linkgit:git-pack-objects[1]) with a
++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]).
+
-+Bundles are useful for numerous purposes. They were originally
-+designed to facilitate the transfer of repository data between
-+repositories which could not be directly connect to each other, and
-+therefore the interactive Git protocols (git, ssh, http) could not be
-+used.
-+
-+In that scenario a bundle is produced on the originating machine. It
-+is then transferred to the other machine (e.g. by sneakernet), and
-+unpacked on the other end. The unpacking can happen either with -+linkgit:git-clone[1] (which knows how to clone from bundle files), or
-+by "git bundle unbundle".
-
- As no
- direct connection between the repositories exists, the user must specify a
-@@ Documentation/git-bundle.txt: basis for the bundle that is held by the destination repository: the
- bundle assumes that all objects in the basis are already in the
- destination repository.
++See link:technical/bundle-format.html[the bundle-format
++documentation] for more details.

-+Similarly, bundles are commonly used to produce incremental backups of -+git repositories. See the "EXAMPLES" section below.
-+
OPTIONS
-------
-

-:  ----------- > 2:  63f871a0c72 bundle doc: split out thin v.s. not discussion from <rev-arg>
-:  ----------- > 3:  14e4a724fb2 bundle doc: elaborate on rev<->ref restriction
Signature · 1 line
2.32.0.610.gd639e370050
#4 lore raw

PATCH v3 1/3 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", so I'm removing that part and letting the brief mention of "thin" suffice.

To the extent that we should say more on the topic that documentation will be improved by subsequent commits.

---
 Documentation/git-bundle.txt | 43 +++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +28 -15
index 53804cad4b6..1b02f8b7468 100644
@@ -18,21 +18,34 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Other git commands that understand protocols such as `ssh://` and
+`https://` can also operate on bundle files. It is possible
+linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1].
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+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]).
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.610.gd639e370050
#5 lore raw

Documentation/git-bundle.txt SYNOPSIS · line 30

Quoted 10 lines · Ævar Arnfjörð Bjarmason
Documentation/git-bundle.txt +10 -0
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Other git commands that understand protocols such as `ssh://` and
+`https://` can also operate on bundle files. It is possible

I'd rather drop "Other", especially given that it is irrelevant if "git bundle" understands "<scheme>://" or not. Instead, I'd somehow limit the "git commands" to those that are meant to "read" from the other side.

IOW, "git push git.bndl master" would not make sense (yet).

Thanks.

#6 lore raw

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

In reply to Ævar Arnfjörð Bjarmason

Split out the discussion of why you should or should not create "thin bundles" into a new section, away from the discussion of our handling of the rev-args syntax.

See 2e0afafebd (Add git-bundle: move objects and references by archive, 2007-02-22) for the introduction of the documentation being changed here.

---
 Documentation/git-bundle.txt | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)
Documentation/git-bundle.txt +21 -2
index 1b02f8b7468..f231f42b12f 100644
@@ -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
 --------
 
Signature · 1 line
2.32.0.610.gd639e370050
#7 lore raw

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

Quoted 36 lines · Ævar Arnfjörð Bjarmason

Split out the discussion of why you should or should not create "thin bundles" into a new section, away from the discussion of our handling of the rev-args syntax.

See 2e0afafebd (Add git-bundle: move objects and references by archive, 2007-02-22) for the introduction of the documentation being changed here.

---
 Documentation/git-bundle.txt | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)
Documentation/git-bundle.txt +6 -2
index 1b02f8b7468..f231f42b12f 100644
@@ -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

Documentation/git-bundle.txt contained in the union of the given bases. Each basis can be · line 156

Quoted 10 lines
Documentation/git-bundle.txt +10 -0
+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.

While it is true that "thin" bundle or packfile must have been created with a commit range with an uninteresting end, presence of the negative end in the range does not necessarily mean the resulting packfile or bundle is thin.

If you want to introduce "open" to mean "some objects reachable from the tip may not be present in the resulting pack/bundle", that is perfectly fine, but "thin" is a different concept. For a packfile to be "thin", it has to be "open", but an "open" packfile can be "thick". Even though they are *not* orthogonal concepts, "thin" packfile is a strict subset of "open" packfile.

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.

#8 lore raw

PATCH v3 3/3 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +39 -8
index f231f42b12f..5674e18155a 100644
@@ -131,14 +131,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OPEN (THIN) AND CLOSED BUNDLES
 ------------------------------
Signature · 1 line
2.32.0.610.gd639e370050
#9 lore raw

v4 cover bundle doc: generalize & elaborate

In reply to Ævar Arnfjörð Bjarmason

A re-roll of v3:
http://lore.kernel.org/git/[email protected]

Junio had comments to the effect that we should mention that we can't push into bundles, and that I was confusing "thin" v.s. "open" packs. Both ahve been cleared up in this version. I added a new "THIN BUNDLES" section after the "OPEN AND CLOSED BUNDLES" section.

Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: split out open v.s. closed discussion from <rev-arg> bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 130 +++++++++++++++++++++++++++--------
 1 file changed, 103 insertions(+), 27 deletions(-)

Range-diff against v3:
1: 2824133f423 ! 1: e32e7b3322d bundle doc: rewrite the "DESCRIPTION" section
@@ Documentation/git-bundle.txt: SYNOPSIS
+repository, and to relay the state of the references in one repository
+to another.
+
-+Other git commands that understand protocols such as ssh:// and -+https:// can also operate on bundle files. It is possible -+linkgit:git-clone[1] a new repository from a bundle, to use
++Git commands that fetch or otherwise "read" via protocols such as ++ssh:// and https:// can also operate on bundle files. It is
++possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
-+contained within it with linkgit:git-ls-remote[1].
++contained within it with linkgit:git-ls-remote[1]. There's no ++corresponding "write" support, i.e.a 'git push' into a bundle is not ++supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
2: 63f871a0c72 ! 2: fe61f20f19f bundle doc: split out thin v.s. not discussion from <rev-arg>
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <[email protected]>

## Commit message ##
- bundle doc: split out thin v.s. not discussion from <rev-arg>
+ bundle doc: split out open v.s. closed discussion from <rev-arg>

- Split out the discussion of why you should or should not create "thin
+ Split out the discussion of why you should or should not create "open
bundles" into a new section, away from the discussion of our handling of the rev-args syntax.

@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
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
-+------------------------------
+-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
@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
+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.
++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).
@@ Documentation/git-bundle.txt: 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
++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.
+
3: 14e4a724fb2 ! 3: 9a1c33cb853 bundle doc: elaborate on rev<->ref restriction
@@ Documentation/git-bundle.txt: unbundle <file>::
+fatal: Refusing to create empty bundle.
+----------------

- OPEN (THIN) AND CLOSED BUNDLES
- ------------------------------
+ OPEN AND CLOSED BUNDLES
+ -----------------------

Signature · 1 line
2.32.0.613.g8e17abc2eb
#10 lore raw

PATCH v4 1/3 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", so I'm removing that part and letting the brief mention of "thin" suffice.

To the extent that we should say more on the topic that documentation will be improved by subsequent commits.

---
 Documentation/git-bundle.txt | 45 ++++++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +30 -15
index 53804cad4b6..e19c2b83c91 100644
@@ -18,21 +18,36 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+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]).
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.613.g8e17abc2eb
#11 lore raw

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

In reply to Ævar Arnfjörð Bjarmason

Split out the discussion of why you should or should not create "open bundles" into a new section, away from the discussion of our handling of the rev-args syntax.

See 2e0afafebd (Add git-bundle: move objects and references by archive, 2007-02-22) for the introduction of the documentation being changed here.

---
 Documentation/git-bundle.txt | 40 +++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)
Documentation/git-bundle.txt +35 -5
index e19c2b83c91..3bb3b71526c 100644
@@ -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
 --------
 
Signature · 1 line
2.32.0.613.g8e17abc2eb
#12 lore raw

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

Quoted 3 lines · Ævar Arnfjörð Bjarmason

Split out the discussion of why you should or should not create "open bundles" into a new section, away from the discussion of our handling of the rev-args syntax.

I changed my mind about this part.

* There is no option to create a bundle with one or more prerequisite commits with a non-thin packfile as its payload part. So "THIN BUNDLE" is an unnecessary new jargon and concept that does not help readers at all, because there is no "thick bundle" that has prerequisite commits. Let's not introduce such a new word.

* We do not call DAG in our history with bottom end (i.e. a range with one or more uninteresting commits) an "open history". Let's not invent the words, "open" vs "close", to describe the history recorded in a bundle, either.

We do already have an appropriate phrase we can use to explain what you wrote in open/close section: "the prerequisite commits" (find it in the description of "verify" subcommand) and that has been a concept well understood for a long time, ever since 2e0afafe (Add
git-bundle: move objects and references by archive, 2007-02-22) introduced the bundle format. Let's use that phrase, instead of inventing a new word.

In short, there are two kinds of bundles.

- A bundle with one or more prerequisite commits can only be extracted in a repository that already has all these prerequisite commits and the history behind them, and "git bundle verify" is an easy way to check if your recipient repository has the prerequisites. The payload in such a bundle is always a thin packfile, but such a technical detail does not concern readers.

- A bundle without any prerequisites can be extracted into anywhere, even into an empty repository, or cloned from it.

And that should be sufficient to base your new paragraph(s).

Sorry for having made a potentially confusing comment earlier. What I said about open vs thin was technically correct (i.e. there wasn't fundamental reason why a bundle with prerequisites MUST use a thin pack as its payload---we designed it that way because such a bundle MUST be extracted in a repository with these prerequisites present, hence it was OK to assume that a --fix-thin would work while extracting such a bundle), but it is irrelevant in practice because you cannot ask for a thick packfile to be created when creating such a bundle anyway.

Thanks.

#13 lore raw

PATCH v4 3/3 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +39 -8
index 3bb3b71526c..2216b9f2843 100644
@@ -133,14 +133,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OPEN AND CLOSED BUNDLES
 -----------------------
Signature · 1 line
2.32.0.613.g8e17abc2eb
#14 lore raw

v5 cover bundle doc: generalize & elaborate

In reply to Ævar Arnfjörð Bjarmason

A v5 of improvements to the "git bundle" documentation. See
http://lore.kernel.org/git/[email protected]
for v4.

This hopefully addresses Junio's concern in
https://lore.kernel.org/git/[email protected]/

I didn't remove the discussion of "thin packs" entirely, but now the whole section about "open" v.s. "closed" doesn't use that wording at all, we now talk only about whether a bundle includes prerequisite commits, and use the same language as git-rev-list does when referring to "exclusions'.

The mention of "think pack" is left in the "BUNDLE FORMAT" section. It's made clear that it doesn't matter to the end result, but that it's noted as a reference to other docs. We then go on to link to the bundle & pack technical format docs for the overly curious.

Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 130 ++++++++++++++++++++++++++++-------
 1 file changed, 104 insertions(+), 26 deletions(-)

Range-diff against v4:
1: d10060a237e ! 1: 3b447500da9 bundle doc: rewrite the "DESCRIPTION" section
@@ Commit message
technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in
- "SPECIFYING REFERENCES", so I'm removing that part and letting the
- brief mention of "thin" suffice.
+ "SPECIFYING REFERENCES", and will be further elaborated on in a
+ subsequent commit. So I'm removing that part and letting the mention
+ of "revision exclusions" suffice.

- To the extent that we should say more on the topic that documentation
- will be improved by subsequent commits.
+ There was a discussion about whether to say anything at all about
+ "thin packs" here[1]. I think it's good to mention it for the curious
+ reader willing to read the technical docs, but let's explicitly say
+ that there's no "thick pack", and that the difference shouldn't
+ matter.
+
+ 1. http://lore.kernel.org/git/[email protected]

@@ Documentation/git-bundle.txt: SYNOPSIS
+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 be created using exclusions.
++
++Bundles created using revision exclusions are "thin packs" created ++using the --thin option to linkgit:git-pack-objects[1], and ++unbundled using the --fix-thin option to linkgit:git-index-pack[1]. ++
++There is no option to create a "thick pack" when using revision ++exclusions, users should not be concerned about the difference. By ++using "thin packs" bundles created using exclusions are smaller in ++size. That they're "thin" under the hood is merely noted here as a ++curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the bundle-format
-+documentation] for more details.
++documentation] for more details and the discussion of "thin pack" in ++link:technical/pack-format.html[the pack format documentation] for ++further details.

OPTIONS
-------
2: 6a312fbdb01 ! 2: 444b06740bc bundle doc: split out open v.s. closed discussion from <rev-arg>
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <[email protected]>

## Commit message ##
- bundle doc: split out open v.s. closed discussion from <rev-arg>
+ bundle doc: elaborate on object prerequisites

- Split out the discussion of why you should or should not create "open
- bundles" into a new section, away from the discussion of our handling
- of the rev-args syntax.
+ 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
@@ Commit message

## Documentation/git-bundle.txt ##
-@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle. The
- header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+@@ Documentation/git-bundle.txt: 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.
+ self-contained, or be created using exclusions.
++See the "OBJECT PREREQUISITES" section below.

- See link:technical/bundle-format.html[the bundle-format
- documentation] for more details.
+ Bundles created using revision exclusions are "thin packs" created
+ using the --thin option to linkgit:git-pack-objects[1], and
@@ Documentation/git-bundle.txt: 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
-+-----------------------
++OBJECT PREREQUISITES
++--------------------
+
-+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 bundles it is possible to create a fully self-contained ++bundle with all the prerequisite objects, as well as providing ++negative revisions to exclude prerequisite objects.
+
-+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. ++A revision such as new will produce a tip with all the prerequisite ++objects needed for the new reference.
++
++A revision range such as old..new will produce a bundle tip that'll ++require any objects existing before new to already be present in the ++repository performing the 'git bundle unbundle' operation. ++
++A self-contained bundle without any prerequisites can be extracted ++into anywhere, even into an empty repository, or be cloned from ++(i.e., new, but not old..new).
++
+ 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).
-@@ Documentation/git-bundle.txt: If you want to provide the same set of refs that a clone directly +-git clone can use any bundle created without negative refspecs
+-(e.g., new, but not old..new).
+ If you want to match git clone --mirror, which would include your
+ refs such as refs/remotes/*, use --all.
+ 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.
++The 'git bundle verify' command can be used to check whether your ++recipient repository has the required prerequisite commits for a ++bundle.
+
EXAMPLES
--------
3: 47b8dacb4aa ! 3: 6d8f2f27088 bundle doc: elaborate on rev<->ref restriction
@@ Documentation/git-bundle.txt: unbundle <file>::
+fatal: Refusing to create empty bundle.
+----------------

- OPEN AND CLOSED BUNDLES
- -----------------------
+ OBJECT PREREQUISITES
+ --------------------

Signature · 1 line
2.32.0.632.g49a94b9226d
#15 lore raw

PATCH v5 1/3 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", and will be further elaborated on in a subsequent commit. So I'm removing that part and letting the mention of "revision exclusions" suffice.

There was a discussion about whether to say anything at all about "thin packs" here[1]. I think it's good to mention it for the curious reader willing to read the technical docs, but let's explicitly say that there's no "thick pack", and that the difference shouldn't matter.

1. http://lore.kernel.org/git/[email protected]

---
 Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +42 -15
index 53804cad4b6..9c743aed49f 100644
@@ -18,21 +18,48 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+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 be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.632.g49a94b9226d
#16 lore raw

PATCH v5 2/3 bundle doc: elaborate on object prerequisites

In reply to Ævar Arnfjörð Bjarmason

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.

---
 Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)
Documentation/git-bundle.txt +23 -3
index 9c743aed49f..f5430029b8c 100644
@@ -45,6 +45,7 @@ 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 be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
 
 Bundles created using revision exclusions are "thin packs" created
 using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,38 @@ 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.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a fully self-contained
+bundle with all the prerequisite objects, as well as providing
+negative revisions to exclude prerequisite objects.
+
+A revision such as `new` will produce a tip with all the prerequisite
+objects needed for the `new` reference.
+
+A revision range such as `old..new` will produce a bundle tip that'll
+require any objects existing before `new` to already be present in the
+repository performing the 'git bundle unbundle' operation.
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
 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`).
 If you want to match `git clone --mirror`, which would include your
 refs such as `refs/remotes/*`, use `--all`.
 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>`.
 
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
 EXAMPLES
 --------
 
Signature · 1 line
2.32.0.632.g49a94b9226d
#17 lore raw

Re: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites

Quoted 28 lines · Ævar Arnfjörð Bjarmason

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.

---
 Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)
Documentation/git-bundle.txt +1 -0
index 9c743aed49f..f5430029b8c 100644
@@ -45,6 +45,7 @@ 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 be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
 
 Bundles created using revision exclusions are "thin packs" created
 using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,38 @@ 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`).
 

Documentation/git-bundle.txt contained in the union of the given bases. Each basis can be · line 165

Quoted 10 lines
Documentation/git-bundle.txt +9 -1
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a fully self-contained
+bundle with all the prerequisite objects, as well as providing
+negative revisions to exclude prerequisite objects.
+
+A revision such as `new` will produce a tip with all the prerequisite
+objects needed for the `new` reference.

The above two paragraphs use the word "prerequisites" in a confusing way. The original meaning of the word in the context of talking about a bundle is "you must have these commits in the receiving repository for the bundle to be unbundle-able".

"git bundle create recent.bndl old..new" creates a bundle that requires 'old' (and everything reachable from it) to exist in the receiving repository. We call the object 'old' (not the objects reachable from it) the prerequisite of the bundle.

"git bundle create full.bndl new" creates a bundle that needs no prerequistes.

It is confusing to say that full.bndl has all the prerequisite objects needed. It is correct to say that it has all the objects reachable from 'new', but if we wanted to say that, we did not have to introduce the new term "prerequisite" when we invented the bundle format. The concept "prerequisite" tries to convey is different.

So, the two paragraphs above use the word "prerequisite" when it wants to talk about "reachable objects" (except for one use---the one in "to exclude prerequisite objects" is correctly used), which is confusing. Here is the first paragraph with probably a better phrasing.

... it is possible to create a self-contained bundle that can be unbundled in an empty repository, as well as providing negative revisions to exclude objects needed in the earlier parts of the history.

As to the second paragraph:

... will produce a bundle without any prerequisites. It can be unbundled in any repository to obtain a full history that leads to the commit new.

By the way, I needed to read "a revision such as new will produce ..." three times before realizing that the reader must fill quite a lot of missing words to understand what the sentence wanted to say, which is:

(feeding) a revision such as new (to "git bundle create" as the revision range argument) will produce ...

I think it is easier to follow if you spelled the command out, e.g.

A command

$ git bundle create full.bndl new

will create a bundle file that contains all the objects reachable from the branch 'new'.

Documentation/git-bundle.txt contained in the union of the given bases. Each basis can be · line 169

Quoted 3 lines
Documentation/git-bundle.txt +3 -0
+A revision range such as `old..new` will produce a bundle tip that'll
+require any objects existing before `new` to already be present in the
+repository performing the 'git bundle unbundle' operation.

Getting warmer ;-). In this case, 'old' is the prerequisite, so

... that'll require the commit 'old' (and any objects reachable from it) to exist for the bundle to be "unbundle"-able.

would be correct.

Documentation/git-bundle.txt contained in the union of the given bases. Each basis can be · line 174

Quoted 4 lines
Documentation/git-bundle.txt +4 -0
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+

This is entirely correct.

Documentation/git-bundle.txt contained in the union of the given bases. Each basis can be · line 187

Quoted 3 lines
Documentation/git-bundle.txt +3 -0
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.

So is this.

Thanks.

#18 lore raw

PATCH v5 3/3 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +39 -8
index f5430029b8c..9a96afedaf3 100644
@@ -145,14 +145,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OBJECT PREREQUISITES
 --------------------
Signature · 1 line
2.32.0.632.g49a94b9226d
#19 lore raw

v6 cover bundle doc: generalize & elaborate

In reply to Ævar Arnfjörð Bjarmason

A v6 of improvements to the "git bundle" documentation. See
https://lore.kernel.org/git/[email protected]/
for v5.

Junio, I think this addresess the points you raised in
https://lore.kernel.org/git/[email protected]/

I used your suggested wording, but changed "empty repository" to "a repository with no common history" for the purposes of the documentation that's trying to talk about what you can unbundle where without ambiguity.

Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 141 ++++++++++++++++++++++++++++-------
 1 file changed, 115 insertions(+), 26 deletions(-)

Range-diff against v5:

1:  3b447500da9 = 1:  d5360bb6f74 bundle doc: rewrite the "DESCRIPTION" section
2:  444b06740bc ! 2:  a0f95ce3a1d bundle doc: elaborate on object prerequisites

@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
+OBJECT PREREQUISITES
+--------------------
+
-+When creating bundles it is possible to create a fully self-contained -+bundle with all the prerequisite objects, as well as providing -+negative revisions to exclude prerequisite objects.
++When creating bundles it is possible to create a self-contained bundle ++that can be unbundled in a repository with no common history, as well ++as providing negative revisions to exclude objects needed in the ++earlier parts of the history.
+
-+A revision such as new will produce a tip with all the prerequisite -+objects needed for the new reference.
++Feeding a revision such as new to git bundle create will create a ++bundle file that contains all the objects reachable from the revision ++new. That bundle can be unbundled in any repository to obtain a full ++history that leads to the revision new:
++
++----------------
++$ git bundle create full.bundle new
++----------------
+
+A revision range such as old..new will produce a bundle tip that'll
-+require any objects existing before new to already be present in the -+repository performing the 'git bundle unbundle' operation. ++that'll require the revision old (and any objects reachable from it) ++to exist for the bundle to be "unbundle"-able:
++
++----------------
++$ git bundle create full.bundle old..new
++----------------
+
+A self-contained bundle without any prerequisites can be extracted +into anywhere, even into an empty repository, or be cloned from
3: 6d8f2f27088 = 3: 6d66d4480ff bundle doc: elaborate on rev<->ref restriction

Signature · 1 line
2.32.0.874.ge7a9d58bfcf
#20 lore raw

PATCH v6 1/3 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", and will be further elaborated on in a subsequent commit. So I'm removing that part and letting the mention of "revision exclusions" suffice.

There was a discussion about whether to say anything at all about "thin packs" here[1]. I think it's good to mention it for the curious reader willing to read the technical docs, but let's explicitly say that there's no "thick pack", and that the difference shouldn't matter.

1. http://lore.kernel.org/git/[email protected]

---
 Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +42 -15
index 53804cad4b6..9c743aed49f 100644
@@ -18,21 +18,48 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+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 be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.874.ge7a9d58bfcf
#21 lore raw

PATCH v6 2/3 bundle doc: elaborate on object prerequisites

In reply to Ævar Arnfjörð Bjarmason

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.

---
 Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)
Documentation/git-bundle.txt +34 -3
index 9c743aed49f..d5627b8cc51 100644
@@ -45,6 +45,7 @@ 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 be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
 
 Bundles created using revision exclusions are "thin packs" created
 using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,49 @@ 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.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle tip that'll
+that'll require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
 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`).
 If you want to match `git clone --mirror`, which would include your
 refs such as `refs/remotes/*`, use `--all`.
 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>`.
 
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
 EXAMPLES
 --------
 
Signature · 1 line
2.32.0.874.ge7a9d58bfcf
#22 lore raw

Re: [PATCH v6 2/3] bundle doc: elaborate on object prerequisites

Review

Quoted 3 lines · Ævar Arnfjörð Bjarmason
(quoted diff) +3 -0
+A revision range such as `old..new` will produce a bundle tip that'll
+that'll require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:

Will squash in the following while queuing.

Thanks.

Documentation/git-bundle.txt +2 -2
index e7a685e533..6a45ced017 100644
@@ -202,8 +202,8 @@ history that leads to the revision `new`:
 $ git bundle create full.bundle new
 ----------------
 
-A revision range such as `old..new` will produce a bundle tip that'll
-that'll require the revision `old` (and any objects reachable from it)
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
 to exist for the bundle to be "unbundle"-able:
 
 ----------------
#23 lore raw

PATCH v6 3/3 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +39 -8
index d5627b8cc51..e7a685e533e 100644
@@ -145,14 +145,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OBJECT PREREQUISITES
 --------------------
Signature · 1 line
2.32.0.874.ge7a9d58bfcf
#24 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Documentation/git-bundle.txt unbundle <file>:: · line 150

Quoted 3 lines · Ævar Arnfjörð Bjarmason
Documentation/git-bundle.txt +3 -0
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.

This may be an improvement in the way how the description refers to "show-ref", but we do not have to say anything about "show-ref" ;-)

The reason we should give readers why they must give refs while creating a bundle, I think, is because the only way to access the contents of the bundle is to fetch refs from it, and the refs given to the command when the bundle was created becomes the refs that can be fetched from the bundle.

Thanks.

#25 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 8 lines · Junio C Hamano

Documentation/git-bundle.txt unbundle <file>:: · line 150

Quoted 3 lines · Ævar Arnfjörð Bjarmason
Documentation/git-bundle.txt +3 -0
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.

This may be an improvement in the way how the description refers to "show-ref", but we do not have to say anything about "show-ref" ;-)

Quoted 8 lines

The reason we should give readers why they must give refs while creating a bundle, I think, is because the only way to access the contents of the bundle is to fetch refs from it, and the refs given to the command when the bundle was created becomes the refs that can be fetched from the bundle.

Thanks.

Should the list-heads option be mentioned for investigating existing bundles?
--
Philip

#26 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 2 lines · Philip Oakley

Should the list-heads option be mentioned for investigating existing bundles?

I think 'list-heads' has been listed in the options section. I however may encourage people to use "git ls-remote one.bndl" over "git bundle list-heads one.bndl"---they do the same thing, no?

Thanks.

#27 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Philip Oakley

Should the list-heads option be mentioned for investigating existing bundles?

I think 'list-heads' has been listed in the options section.

True, it's why I was suggesting pointing at that route for the extra details that are beyond just a set of refs.

Quoted 3 lines

I
however may encourage people to use "git ls-remote one.bndl" over "git bundle list-heads one.bndl"---they do the same thing, no?

It is good to provide both directions to the user. The formats may be different but the content is essentially the same, and redirecting users to the more core command is useful.

Quoted 5 lines

Thanks.

#28 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 10 lines · Philip Oakley
Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Philip Oakley

Should the list-heads option be mentioned for investigating existing bundles?

I think 'list-heads' has been listed in the options section.

True, it's why I was suggesting pointing at that route for the extra details that are beyond just a set of refs.

Quoted 8 lines
Quoted 3 lines

I
however may encourage people to use "git ls-remote one.bndl" over "git bundle list-heads one.bndl"---they do the same thing, no?

It is good to provide both directions to the user. The formats may be different but the content is essentially the same, and redirecting users to the more core command is useful.

I'll work those suggestions into a future update of the docs I have queued, but for now I think talking about list-heads v.s. ls-remote doesn't have much directly to do with this particular series, correct?

#29 lore raw

Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 14 lines · Ævar Arnfjörð Bjarmason
Quoted 12 lines · Philip Oakley
Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Philip Oakley

Should the list-heads option be mentioned for investigating existing bundles?

I think 'list-heads' has been listed in the options section.

True, it's why I was suggesting pointing at that route for the extra details that are beyond just a set of refs.

Quoted 3 lines

I
however may encourage people to use "git ls-remote one.bndl" over "git bundle list-heads one.bndl"---they do the same thing, no?

Quoted 7 lines
Quoted 4 lines

It is good to provide both directions to the user. The formats may be different but the content is essentially the same, and redirecting users to the more core command is useful.

I'll work those suggestions into a future update of the docs I have queued, but for now I think talking about list-heads v.s. ls-remote doesn't have much directly to do with this particular series, correct?

True.

However I'm still not really clear about the distinction between the 'basis' and the header references (that is, the text doesn't make it clear).

for the future updates, it would also be good if the --all and --branches --tags text was also shown in the examples - I continue to get StackOverflow points for my Q&A on that ;-)

Philip

#30 lore raw

v7 cover bundle doc: generalize & elaborate

In reply to Ævar Arnfjörð Bjarmason

This v7 hopefully addresses the outstanding comments on v6.

The mention of "show-ref" is gone (more confusing than not), and this includes Junio's queued squash.

I left the further clarification of "basis" and "header references" mentioned in [1] be. I think the former refers to the "basis can be specified" wording in 3/3, which isn't new, but in that regard mostly moves existing documentation around.

This documentation can definitely be improved further, but given that this is in v7 and we're changing smaller and smaller things I'd like to not add anything new to it for now, and hopefully get it merged down & then build on top of it for any further changes.

1. https://lore.kernel.org/git/[email protected]/

Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction

 Documentation/git-bundle.txt | 140 ++++++++++++++++++++++++++++-------
 1 file changed, 114 insertions(+), 26 deletions(-)

Range-diff against v6:
1: 3b447500da ! 1: b8f8a20e78 bundle doc: rewrite the "DESCRIPTION" section
@@ Documentation/git-bundle.txt: SYNOPSIS
+-------------
+
+Bundles are .pack files (see linkgit:git-pack-objects[1]) with a
-+header indicating what references are contained within the bundle. The -+header is (mostly) in the format emitted by linkgit:git-show-ref[1]. ++header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be +self-contained, or be created using exclusions.
2: 444b06740b ! 2: 5f344bd24a bundle doc: elaborate on object prerequisites
@@ Commit message

## Documentation/git-bundle.txt ##
-@@ Documentation/git-bundle.txt: header is (mostly) in the format emitted by linkgit:git-show-ref[1]. +@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle.

Like the the packed archive format itself bundles can either be self-contained, or be created using exclusions.
@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
+OBJECT PREREQUISITES
+--------------------
+
-+When creating bundles it is possible to create a fully self-contained -+bundle with all the prerequisite objects, as well as providing -+negative revisions to exclude prerequisite objects.
++When creating bundles it is possible to create a self-contained bundle ++that can be unbundled in a repository with no common history, as well ++as providing negative revisions to exclude objects needed in the ++earlier parts of the history.
+
-+A revision such as new will produce a tip with all the prerequisite -+objects needed for the new reference.
++Feeding a revision such as new to git bundle create will create a ++bundle file that contains all the objects reachable from the revision ++new. That bundle can be unbundled in any repository to obtain a full ++history that leads to the revision new:
+
-+A revision range such as old..new will produce a bundle tip that'll -+require any objects existing before new to already be present in the -+repository performing the 'git bundle unbundle' operation.
++----------------
++$ git bundle create full.bundle new
++----------------
++
++A revision range such as old..new will produce a bundle file that ++will require the revision old (and any objects reachable from it) ++to exist for the bundle to be "unbundle"-able:
++
++----------------
++$ git bundle create full.bundle old..new
++----------------
+
+A self-contained bundle without any prerequisites can be extracted +into anywhere, even into an empty repository, or be cloned from
3: 6d8f2f2708 = 3: 88e7ad1cf4 bundle doc: elaborate on rev<->ref restriction

Signature · 1 line
2.32.0.988.g1a6a4b2c5f
#31 lore raw

PATCH v7 1/3 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", and will be further elaborated on in a subsequent commit. So I'm removing that part and letting the mention of "revision exclusions" suffice.

There was a discussion about whether to say anything at all about "thin packs" here[1]. I think it's good to mention it for the curious reader willing to read the technical docs, but let's explicitly say that there's no "thick pack", and that the difference shouldn't matter.

1. http://lore.kernel.org/git/[email protected]

---
 Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +41 -15
index 53804cad4b..339c5b4727 100644
@@ -18,21 +18,47 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.988.g1a6a4b2c5f
#32 lore raw

PATCH v7 2/3 bundle doc: elaborate on object prerequisites

In reply to Ævar Arnfjörð Bjarmason

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.

---
 Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)
Documentation/git-bundle.txt +34 -3
index 339c5b4727..f1f84ce2c4 100644
@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.
 
 Like the the packed archive format itself bundles can either be
 self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
 
 Bundles created using revision exclusions are "thin packs" created
 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
 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.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
 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`).
 If you want to match `git clone --mirror`, which would include your
 refs such as `refs/remotes/*`, use `--all`.
 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>`.
 
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
 EXAMPLES
 --------
 
Signature · 1 line
2.32.0.988.g1a6a4b2c5f
#33 lore raw

PATCH v7 3/3 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +39 -8
index f1f84ce2c4..0f28c41409 100644
@@ -144,14 +144,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OBJECT PREREQUISITES
 --------------------
Signature · 1 line
2.32.0.988.g1a6a4b2c5f
#34 lore raw

Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction

Quoted 53 lines · Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +28 -8
index f1f84ce2c4..0f28c41409 100644
@@ -144,14 +144,45 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next

Documentation/git-bundle.txt unbundle <file>:: · line 184

Quoted 10 lines
Documentation/git-bundle.txt +10 -0
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.

I like this example showing the need for a reference name to be part of the basis, clarifying that part of the description.

Philip

Quoted 4 lines
Documentation/git-bundle.txt +1 -0
+----------------
 
 OBJECT PREREQUISITES
 --------------------
#35 lore raw

Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Documentation/git-bundle.txt unbundle <file>:: · line 149

Quoted 3 lines · Ævar Arnfjörð Bjarmason
Documentation/git-bundle.txt +3 -0
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.

As I already said in the review of v6, I do not think "header has a format similar to show-ref" is not something we need to say so prominently to the user.

The reason we should give readers why they must give refs while creating a bundle, I think, is because the only way to access the contents of the bundle is to fetch refs from it, and the refs given to the command when the bundle was created becomes the refs that can be fetched from the bundle.

And that is what the readers should be told here, I think.

Documentation/git-bundle.txt unbundle <file>:: · line 158

Quoted 8 lines
Documentation/git-bundle.txt +8 -0
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).

Also, we introduced "prerequisite objects" in the previous step, but here we say "basis". The readers would be helped greatly if we were a bit more consistent.

Documentation/git-bundle.txt unbundle <file>:: · line 185

Quoted 10 lines

...

Documentation/git-bundle.txt +9 -0
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------

This is a good example, as Philip already said.

Thanks.

#36 lore raw

v8 cover bundle doc: generalize & elaborate

In reply to Ævar Arnfjörð Bjarmason

As mentioned in v7 I got rid of the comparisons of the bundle header to the format of show-ref:
https://lore.kernel.org/git/[email protected]

Except I managed to miss that it was in two places in the series, sorry. Here's an update with what I meant to send in v7.

Junio also mentioned it being confusing that we mix "basis" and "object prerequisites", I agree, but wanted to keep these changes minimal, so I wasn't rewording the existing occurances of "basis".

This now has a minimal patch-on-top which follows up and rewords those existing and moved-around occurrences of "basis" to "[commit|object] prerequisite(s)".

1. https://lore.kernel.org/git/[email protected]/#t

Ævar Arnfjörð Bjarmason (4):
bundle doc: rewrite the "DESCRIPTION" section bundle doc: elaborate on object prerequisites bundle doc: elaborate on rev<->ref restriction bundle doc: replace "basis" with "prerequsite(s)"

 Documentation/git-bundle.txt | 147 ++++++++++++++++++++++++++++-------
 1 file changed, 117 insertions(+), 30 deletions(-)

Range-diff against v7:

1:  b8f8a20e789 = 1:  b8f8a20e789 bundle doc: rewrite the "DESCRIPTION" section
2:  5f344bd24aa = 2:  5f344bd24aa bundle doc: elaborate on object prerequisites
3:  88e7ad1cf49 ! 3:  0e702337c7f bundle doc: elaborate on rev<->ref restriction

@@ Documentation/git-bundle.txt: unbundle <file>::
-specified explicitly (e.g. ^master~10), or implicitly (e.g. -master~10..master, --since=10.days.ago master).
+Revisions must accompanied by reference names to be packaged in a
-+bundle, since the header of the bundle is in a format similar to 'git -+show-ref'.
++bundle.
+
+More than one reference may be packaged, and more than one basis can +be specified. The objects packaged are those not contained in the
-: ----------- > 4: 1f3dcd42863 bundle doc: replace "basis" with "prerequsite(s)"

Signature · 1 line
2.32.0.1069.g545f0888808
#37 lore raw

PATCH v8 1/4 bundle doc: rewrite the "DESCRIPTION" section

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for.

This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22).

I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation.

The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", and will be further elaborated on in a subsequent commit. So I'm removing that part and letting the mention of "revision exclusions" suffice.

There was a discussion about whether to say anything at all about "thin packs" here[1]. I think it's good to mention it for the curious reader willing to read the technical docs, but let's explicitly say that there's no "thick pack", and that the difference shouldn't matter.

1. http://lore.kernel.org/git/[email protected]

---
 Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 15 deletions(-)
Documentation/git-bundle.txt +41 -15
index 53804cad4b6..339c5b47276 100644
@@ -18,21 +18,47 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
 
 OPTIONS
 -------
Signature · 1 line
2.32.0.1069.g545f0888808
#38 lore raw

PATCH v8 2/4 bundle doc: elaborate on object prerequisites

In reply to Ævar Arnfjörð Bjarmason

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.

---
 Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)
Documentation/git-bundle.txt +34 -3
index 339c5b47276..f1f84ce2c42 100644
@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.
 
 Like the the packed archive format itself bundles can either be
 self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
 
 Bundles created using revision exclusions are "thin packs" created
 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
 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.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
 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`).
 If you want to match `git clone --mirror`, which would include your
 refs such as `refs/remotes/*`, use `--all`.
 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>`.
 
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
 EXAMPLES
 --------
 
Signature · 1 line
2.32.0.1069.g545f0888808
#39 lore raw

PATCH v8 3/4 bundle doc: elaborate on rev<->ref restriction

In reply to Ævar Arnfjörð Bjarmason

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples.

---
 Documentation/git-bundle.txt | 46 +++++++++++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 8 deletions(-)
Documentation/git-bundle.txt +38 -8
index f1f84ce2c42..f36939ab014 100644
@@ -144,14 +144,44 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads.  References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis.  More than one reference may be packaged, and more
-than one basis can be specified.  The objects packaged are those not
-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`).
+Revisions must accompanied by reference names to be packaged in a
+bundle.
+
+More than one reference may be packaged, and more than one basis can
+be specified.  The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
 
 OBJECT PREREQUISITES
 --------------------
Signature · 1 line
2.32.0.1069.g545f0888808
#40 lore raw

PATCH v8 4/4 bundle doc: replace "basis" with "prerequsite(s)"

In reply to Ævar Arnfjörð Bjarmason

In the preceding commits we introduced new documentation that talks about "[commit|object] prerequsite(s)", but also faithfully moved around existing documentation that talks about the "basis".

Let's change both that moved-around documentation and other existing documentation in the file to consistently use "[commit|object]" prerequisite(s)" instead of talking about "basis". The mention of "basis" isn't wrong, but readers will be helped by us using only one term throughout the document for this concept.

---
 Documentation/git-bundle.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
Documentation/git-bundle.txt +7 -7
index f36939ab014..ac0d0038350 100644
@@ -147,13 +147,13 @@ SPECIFYING REFERENCES
 Revisions must accompanied by reference names to be packaged in a
 bundle.
 
-More than one reference may be packaged, and more than one basis can
+More than one reference may be packaged, and more than one set of prerequisite objects can
 be specified.  The objects packaged are those not contained in the
-union of the given bases.
+union of the prerequisites.
 
 The 'git bundle create' command resolves the reference names for you
 using the same rules as `git rev-parse --abbrev-ref=loose`. Each
-basis can be specified explicitly (e.g. `^master~10`), or implicitly
+prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
 (e.g. `master~10..master`, `--since=10.days.ago master`).
 
 All of these simple cases are OK (assuming we have a "master" and
@@ -236,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.).
 We want to update R2 with development made on the branch master in R1.
 
 To bootstrap the process, you can first create a bundle that does not have
-any basis. You can use a tag to remember up to what commit you last
+any prerequisites. You can use a tag to remember up to what commit you last
 processed, in order to make it easy to later update the other repository
 with an incremental bundle:
 
@@ -287,7 +287,7 @@ machineB$ git pull
 
 If you know up to what commit the intended recipient repository should
 have the necessary objects, you can use that knowledge to specify the
-basis, giving a cut-off point to limit the revisions and objects that go
+prerequisites, giving a cut-off point to limit the revisions and objects that go
 in the resulting bundle. The previous example used the lastR2bundle tag
 for this purpose, but you can use any other options that you would give to
 the linkgit:git-log[1] command. Here are more examples:
@@ -298,7 +298,7 @@ You can use a tag that is present in both:
 $ git bundle create mybundle v1.0.0..master
 ----------------
 
-You can use a basis based on time:
+You can use a prerequisite based on time:
 
 ----------------
 $ git bundle create mybundle --since=10.days master
@@ -311,7 +311,7 @@ $ git bundle create mybundle -10 master
 ----------------
 
 You can run `git-bundle verify` to see if you can extract from a bundle
-that was created with a basis:
+that was created with a prerequisite:
 
 ----------------
 $ git bundle verify mybundle
Signature · 1 line
2.32.0.1069.g545f0888808