patchbundle doc: rewrite the "DESCRIPTION" section

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

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

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

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

OK.

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

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.

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

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

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

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.

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

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

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.

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

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

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

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

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.

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

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

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

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

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

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

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

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.

This is entirely correct.

So is this.

Thanks.

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

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

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

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

Will squash in the following while queuing.

Thanks.

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

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

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.

On 20/07/2021 21:19, Junio C Hamano wrote:

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

Philip Oakley <philipoakley@iee.email> writes:

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.

On 21/07/2021 17:57, Junio C Hamano wrote:

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

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.

On Thu, Jul 22 2021, Philip Oakley wrote:

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?

On 22/07/2021 12:46, Ævar Arnfjörð Bjarmason wrote:

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

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

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

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

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

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

On 27/07/2021 01:24, Ævar Arnfjörð Bjarmason wrote:

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

Philip

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

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.

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.

This is a good example, as Philip already said.

Thanks.

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

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

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

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

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