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

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

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