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

Message

Ævar Arnfjörð Bjarmason July 27, 2021, 12:24 a.m. UTC

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/[e-mail]/

Æ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 <[e-mail]>
     
      ## 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