This started as 1 patch in https://lore.kernel.org/git/patch-1.1-bc6a6d8922-20210607T165507Z-avarab@xxxxxxxxx/ 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@xxxxxxxxx> ## 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 -- 2.32.0.610.gd639e370050
