Stephen Boyd <bebarino@xxxxxxxxx> writes:
> 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@xxxxxxxxxxx>.
>
> Signed-off-by: Stephen Boyd <bebarino@xxxxxxxxx>
> ---
Looking better, thanks.
> 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:
> +--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]).
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html