A re-roll of v3: http://lore.kernel.org/git/cover-0.3-00000000000-20210624T193730Z-avarab@xxxxxxxxx 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@xxxxxxxxx> ## 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
