Re: [PATCHv3] Documentation: describe --thin more accurately

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 15, 2010, 20:44 UTC
Message-ID: <7vfx52xm8d.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1266262395-11864-1-git-send-email-bebarino@gmail.com>

Stephen Boyd <bebarino@gmail.com> writes:

Show 6 quoted lines

> The description for --thin was misleading and downright wrong. Correct
> it with some inspiration from the description of index-pack's --fix-thin
> and some background information from Nicolas Pitre <nico@fluxnic.net>.
>
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---

Looking better, thanks.

Show 16 quoted lines

> index 65a301b..b4fa98e 100644
> --- a/Documentation/git-index-pack.txt
> +++ b/Documentation/git-index-pack.txt
> @@ -46,14 +46,15 @@ OPTIONS
>  	'git repack'.
>  
>  --fix-thin::
> +	It's possible for 'git pack-objects' to build a
>  	"thin" pack, which records objects in deltified form based on
>  	objects not included in the pack to reduce network traffic.
> +	The excluded objects are expected to be present on the receiving end
>  	and they must be included in the pack for that pack to be self
> +	contained and indexable. This option fixes the "thin" pack by
> +	adding the missing objects to the pack. Without this option any
> +	attempt to index a "thin" pack will fail. This option only makes
> +	sense in conjunction with --stdin.

Assuming that the reader knows only what "git objects" are, and that a "pack" contains "git objects" either in full or in a "deltified form based on another object", the description needs to explain three points:

 - "self-containedness" requirement to be directly usable by git;
 - "thin" pack reduces transfer by violating "self-containedness"; and
 - "--fix-thin" makes "thin" into "self-contained".

I however think the first two points might be better covered by the description of `--thin` of `pack-objects` and we should simply refer to it from here, like this:

    --fix-thin::
            Make a "thin" pack produced by `git pack-objects --thin` (see
            linkgit:git-pack-objects[1] for details) directly usable by
            git, by adding objects that the objects stored in the
            deltified form are based on to the packfile.

And we can thicken the --thin description of pack-objects like this:

Show 9 quoted lines

> +--thin::
> +	Create a "thin" pack, which records objects in deltified form based
> +	on objects not included in the pack to reduce network traffic.
> +	The excluded objects are expected to be present on the receiving end
> +	and eventually must be included in the pack for that pack to be self
> +	contained and indexable (see the \--fix-thin option of
> +	linkgit:git-index-pack[1] for more details). This option only makes
> +	sense in conjunction with --stdout.
> +

    --thin::
            Create a "thin" pack in order to reduce network transfer.
    +
    For a packfile to be usable directly by git, any object in the pack
    that is represented in the deltified form must be based on an object
    that exists in the same pack.  Such a pack is called "self-contained".
    +
    If the sender sends an object in the deltified form based on an object
    both the sender and the receiver have, but excludes the common object
    itself from the datastream, it can often reduce the network traffic
    dramatically.  Such a datastream is called a "thin" pack.
    +
    Note that a thin pack violates the self-containedness requirement and
    is not directly usable by git on the receiving end without making it a
    self-contained pack by running `git index-pack --fix-thin` (see
    linkgit:git-index-pack[1]).