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

From: Stephen Boyd <bebarino@gmail.com>
Date: Feb 18, 2010, 08:33 UTC
Message-ID: <4B7CFB4C.2020507@gmail.com>
In-Reply-To: <7vfx52xm8d.fsf@alter.siamese.dyndns.org>

On 02/15/2010 12:44 PM, Junio C Hamano wrote:

Show 10 quoted lines

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

This looks good. I'd like to avoid introducing the term packfile though and just use pack throughout.

Show 16 quoted lines

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

This looks long winded. Perhaps we can do without explaining what self-containedness is? If you read the second paragraph in the description section of git-pack-objects.txt it tries to explain self-contained:

    The packed archive format (.pack) is designed to be 
    self-contained so that it can be unpacked without
    any further information

If all I know is a pack contains objects and deltas based on other objects I might be able to figure out that all the objects must be present in the pack for it to be self-contained. This description section might need some work but I don't think repeating ourselves in --thin is good.

Updated patch to follow.