[PATCH] bundle doc: rewrite the "DESCRIPTION" section

[PATCH] bundle doc: rewrite the "DESCRIPTION" section

[Æ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).

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..1d7c6bdbb2 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
 
-- 
2.32.0.rc3.434.gd8aed1f08a7

[PATCH v2] bundle doc: rewrite the "DESCRIPTION" section

[Æ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).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---

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(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..cdc4e0b51b 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
 
-- 
2.32.0.rc3.434.gd8aed1f08a7

Re: [PATCH v2] bundle doc: rewrite the "DESCRIPTION" section

[Junio C Hamano]

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

> 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.

>  NAME
>  ----
> -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).

> -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.

[PATCH v3 0/3] bundle doc: generaliz & elaborate

[Ævar Arnfjörð Bjarmason]

This started as 1 patch in
https://lore.kernel.org/git/patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com/
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.
     
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## 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
-- 
2.32.0.610.gd639e370050

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

[Æ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).

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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..1b02f8b7468 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.610.gd639e370050

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 1b02f8b7468..f231f42b12f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -42,7 +42,8 @@ header indicating what references are contained within the bundle. The
 header is (mostly) in the format emitted by linkgit:git-show-ref[1].
 
 Like the the packed archive format itself bundles can either be
-self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+self-contained or thin, see the "OPEN (THIN) AND CLOSED BUNDLES"
+section below.
 
 See link:technical/bundle-format.html[the `bundle-format`
 documentation] for more details.
@@ -139,7 +140,20 @@ contained in the union of the given bases.  Each basis can be
 specified explicitly (e.g. `^master~10`), or implicitly (e.g.
 `master~10..master`, `--since=10.days.ago master`).
 
-It is very important that the basis used be held by the destination.
+OPEN (THIN) AND CLOSED BUNDLES
+------------------------------
+
+When creating bundles it is possible to create bundle tips that are
+either closed or open under reachability, i.e. those that contain all
+the history needed to get to a given point (closed), and those that do
+not (open). A revision such as "master" will produce a closed tip, a
+range such as "master~2..master" will not (unless the full history is
+contained within that range).
+
+Another name for "open" bundles might be "thin bundles", as in the
+`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's
+what `git bundle create` uses to write bundles. When thin bundles
+it is very important that the basis used be held by the destination.
 It is okay to err on the side of caution, causing the bundle file
 to contain objects already in the destination, as these are ignored
 when unpacking at the destination.
@@ -152,6 +166,11 @@ If you want to provide the same set of refs that a clone directly
 from the source repository would get, use `--branches --tags` for
 the `<git-rev-list-args>`.
 
+See the the `--thin` option to linkgit:git-pack-objects[1] noted
+above, and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
+
 EXAMPLES
 --------
 
-- 
2.32.0.610.gd639e370050

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f231f42b12f..5674e18155a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 ------------------------------
-- 
2.32.0.610.gd639e370050

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

[Junio C Hamano]

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

> +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.

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

[Junio C Hamano]

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

> 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.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/git-bundle.txt | 23 +++++++++++++++++++++--
>  1 file changed, 21 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 1b02f8b7468..f231f42b12f 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -42,7 +42,8 @@ header indicating what references are contained within the bundle. The
>  header is (mostly) in the format emitted by linkgit:git-show-ref[1].
>  
>  Like the the packed archive format itself bundles can either be
> -self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
> +self-contained or thin, see the "OPEN (THIN) AND CLOSED BUNDLES"
> +section below.
>  
>  See link:technical/bundle-format.html[the `bundle-format`
>  documentation] for more details.
> @@ -139,7 +140,20 @@ contained in the union of the given bases.  Each basis can be
>  specified explicitly (e.g. `^master~10`), or implicitly (e.g.
>  `master~10..master`, `--since=10.days.ago master`).
>  
> -It is very important that the basis used be held by the destination.
> +OPEN (THIN) AND CLOSED BUNDLES
> +------------------------------
> +
> +When creating bundles it is possible to create bundle tips that are
> +either closed or open under reachability, i.e. those that contain all
> +the history needed to get to a given point (closed), and those that do
> +not (open). A revision such as "master" will produce a closed tip, a
> +range such as "master~2..master" will not (unless the full history is
> +contained within that range).
> +
> +Another name for "open" bundles might be "thin bundles", as in the
> +`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's
> +what `git bundle create` uses to write bundles. When thin bundles
> +it is very important that the basis used be held by the destination.

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.

[PATCH v4 0/3] bundle doc: generalize & elaborate

[Ævar Arnfjörð Bjarmason]

A re-roll of v3:
http://lore.kernel.org/git/cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com

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 <avarab@gmail.com>
     
      ## 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
    + -----------------------
-- 
2.32.0.613.g8e17abc2eb

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

[Æ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).

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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..e19c2b83c91 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.613.g8e17abc2eb

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

[Æ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.

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

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

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 3bb3b71526c..2216b9f2843 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -----------------------
-- 
2.32.0.613.g8e17abc2eb

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

[Junio C Hamano]

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

> 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.

[PATCH v5 0/3] bundle doc: generalize & elaborate

[Ævar Arnfjörð Bjarmason]

A v5 of improvements to the "git bundle" documentation. See
http://lore.kernel.org/git/cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com
for v4.

This hopefully addresses Junio's concern in
https://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g/

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/xmqqk0mbt5rj.fsf@gitster.g
     
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
    @@ 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 <avarab@gmail.com>
     
      ## 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
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## 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
    + --------------------
-- 
2.32.0.632.g49a94b9226d

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

[Æ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).

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/xmqqk0mbt5rj.fsf@gitster.g

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..9c743aed49f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.632.g49a94b9226d

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 9c743aed49f..f5430029b8c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------
 
-- 
2.32.0.632.g49a94b9226d

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f5430029b8c..9a96afedaf3 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------------------
-- 
2.32.0.632.g49a94b9226d

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

[Junio C Hamano]

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

> Split out the discussion bout "object prerequisites" into its own
> section, and add some more examples of the common cases.
>
> See 2e0afafebd (Add git-bundle: move objects and references by
> archive, 2007-02-22) for the introduction of the documentation being
> changed here.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 9c743aed49f..f5430029b8c 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -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.

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'.

> +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.

> +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.

> +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.

[PATCH v6 0/3] bundle doc: generalize & elaborate

[Ævar Arnfjörð Bjarmason]

A v6 of improvements to the "git bundle" documentation. See
https://lore.kernel.org/git/cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com/
for v5.

Junio, I think this addresess the points you raised in
https://lore.kernel.org/git/xmqq7di8rbtj.fsf@gitster.g/

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
-- 
2.32.0.874.ge7a9d58bfcf

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

[Æ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).

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/xmqqk0mbt5rj.fsf@gitster.g

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..9c743aed49f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.874.ge7a9d58bfcf

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 9c743aed49f..d5627b8cc51 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------
 
-- 
2.32.0.874.ge7a9d58bfcf

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index d5627b8cc51..e7a685e533e 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------------------
-- 
2.32.0.874.ge7a9d58bfcf

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

[Junio C Hamano]

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

> +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.

diff --git c/Documentation/git-bundle.txt w/Documentation/git-bundle.txt
index e7a685e533..6a45ced017 100644
--- c/Documentation/git-bundle.txt
+++ w/Documentation/git-bundle.txt
@@ -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:
 
 ----------------

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

[Junio C Hamano]

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

> +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.

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

[Philip Oakley]

On 20/07/2021 21:19, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> +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.
>
Should the `list-heads` option be mentioned for investigating existing
bundles?
--
Philip

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

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> writes:

> 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.

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

[Philip Oakley]

On 21/07/2021 17:57, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> writes:
>
>> 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.

> 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.

>
> Thanks.
>
>
>

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

[Ævar Arnfjörð Bjarmason]

On Thu, Jul 22 2021, Philip Oakley wrote:

> On 21/07/2021 17:57, Junio C Hamano wrote:
>> Philip Oakley <philipoakley@iee.email> writes:
>>
>>> 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.
>
>> 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?

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

[Philip Oakley]

On 22/07/2021 12:46, Ævar Arnfjörð Bjarmason wrote:
> On Thu, Jul 22 2021, Philip Oakley wrote:
>
>> On 21/07/2021 17:57, Junio C Hamano wrote:
>>> Philip Oakley <philipoakley@iee.email> writes:
>>>
>>>> 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.
>>
>>> 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?
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

[PATCH v7 0/3] bundle doc: generalize & elaborate

[Æ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/697ca0f3-a897-a20b-48e4-bf439697afb5@iee.email/

Æ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
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
     
      ## 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
-- 
2.32.0.988.g1a6a4b2c5f

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

[Æ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).

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/xmqqk0mbt5rj.fsf@gitster.g

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..339c5b4727 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.988.g1a6a4b2c5f

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 339c5b4727..f1f84ce2c4 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------
 
-- 
2.32.0.988.g1a6a4b2c5f

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f1f84ce2c4..0f28c41409 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------------------
-- 
2.32.0.988.g1a6a4b2c5f

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

[Philip Oakley]

On 27/07/2021 01:24, Ævar Arnfjörð Bjarmason wrote:
> Elaborate on the restriction that you cannot provide a revision that
> doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
> with examples.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
>  1 file changed, 39 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index f1f84ce2c4..0f28c41409 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -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.

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

Philip

> +----------------
>  
>  OBJECT PREREQUISITES
>  --------------------

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

[Junio C Hamano]

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

> +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.


> +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.

> ...
> +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.

[PATCH v8 0/3] bundle doc: generalize & elaborate

[Æ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/cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com

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/xmqqa6m69uvh.fsf@gitster.g/#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)"
-- 
2.32.0.1069.g545f0888808

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

[Æ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).

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/xmqqk0mbt5rj.fsf@gitster.g

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..339c5b47276 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 -------
-- 
2.32.0.1069.g545f0888808

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 339c5b47276..f1f84ce2c42 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------
 
-- 
2.32.0.1069.g545f0888808

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f1f84ce2c42..f36939ab014 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
 --------------------
-- 
2.32.0.1069.g545f0888808

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

[Æ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.

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

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f36939ab014..ac0d0038350 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -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
-- 
2.32.0.1069.g545f0888808