Re: [PATCH v2] bundle doc: rewrite the "DESCRIPTION" section

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 7, 2021, 23:35 UTC
Message-ID: <xmqqh7i9tfhe.fsf@gitster.g>
In-Reply-To: <patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

Show 6 quoted lines

> 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).

Show 8 quoted lines

> -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.