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

[Stephen Boyd <bebarino@gmail.com>]

On 02/15/2010 12:44 PM, Junio C Hamano wrote:
> 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.

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