A v6 of improvements to the "git bundle" documentation. See https://lore.kernel.org/git/cover-0.3-00000000000-20210702T112254Z-avarab@xxxxxxxxx/ 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
