| Message ID | patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] bundle doc: rewrite the "DESCRIPTION" section | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > 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). OK. > NAME > ---- > -git-bundle - Move objects and refs by archive > +git-bundle - Create, unpack and manipulate bundles While I find the updated description an improvement, I do not think the updated one-line explanation is. Not that "archive" is much better than "bundles", but to those who needs "git-bundle" explained, it is better not to use the same word "bundle" to do so, and worse, when one does not know what "bundles" are, "do X, Y or Z" on that unknown thing would not help understanding all that much. At least, the original _hints_ that it is related to some way to transport Git data (by mentioning "objects and refs"), and those with good instinct may even guess that it is an offline transport (with the hint the word "archive" leaves). > -Some workflows require that one or more branches of development on one > -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]. Before going into the composition of a bundle, can we touch the reason why we create such a thing? It is to help "offline" Git transfer without common history discovery. That is, Create, unpack, and manipulate "bundle" files, that helps "offline" transfer of Git objects without an active "server" sitting on the other side of the network connection. or something.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 53804cad4b..cdc4e0b51b 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -3,7 +3,7 @@ git-bundle(1) NAME ---- -git-bundle - Move objects and refs by archive +git-bundle - Create, unpack and manipulate bundles SYNOPSIS @@ -18,15 +18,25 @@ SYNOPSIS DESCRIPTION ----------- -Some workflows require that one or more branches of development on one -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). +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 @@ -34,6 +44,9 @@ 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. +Similarly, bundles are commonly used to produce incremental backups of +git repositories. See the "EXAMPLES" section below. + OPTIONS -------
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). Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- I didn't think I needed to type "make" to check a doc-only change, but as it turns out v1 of this doesn't compile git because the script to generate command-list.h doesn't know how to escape the quotes in the C-string it generates. This is probably better in either case, sorry about the noise. Range-diff against v1: 1: 4e736877d1 ! 1: bc6a6d8922 bundle doc: rewrite the "DESCRIPTION" section @@ Documentation/git-bundle.txt: git-bundle(1) NAME ---- -git-bundle - Move objects and refs by archive -+git-bundle - Create, unpack and manipulate "bundles" ++git-bundle - Create, unpack and manipulate bundles SYNOPSIS Documentation/git-bundle.txt | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-)