[PATCH] Documentation: reword --thin description

[PATCH] Documentation: reword --thin description

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---

Don't know if git-push needs to say that --thin is passed to send-pack.

 Documentation/git-fetch-pack.txt |    4 ++--
 Documentation/git-push.txt       |    6 +++---
 Documentation/git-send-pack.txt  |    4 ++--
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index e9952e8..2b4e4dd 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -44,8 +44,8 @@ OPTIONS
 	locked against repacking.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Spend extra cycles minimizing the number of sent objects.
+	Use it with a slow connection.
 
 --include-tag::
 	If the remote side supports it, annotated tags objects will
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index bd79119..a14bc9c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -141,9 +141,9 @@ useful if you write an alias or script around 'git push'.
 
 --thin::
 --no-thin::
-	These options are passed to 'git send-pack'.  Thin
-	transfer spends extra cycles to minimize the number of
-	objects to be sent and meant to be used on slower connection.
+	These options are passed to 'git send-pack'.  A thin
+	transfer spends extra cycles minimizing the number of
+	sent objects and is meant to be used with a slow connection.
 
 -v::
 --verbose::
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 8178d92..0a78dac 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -48,8 +48,8 @@ OPTIONS
 	Run verbosely.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Spend extra cycles minimizing the number of sent objects.
+	Use it with a slow connection.
 
 <host>::
 	A remote host to house the repository.  When this
-- 
1.7.0.rc2

Re: [PATCH] Documentation: reword --thin description

[Nicolas Pitre]

On Tue, 9 Feb 2010, Stephen Boyd wrote:

>  --thin::
> -	Spend extra cycles to minimize the number of objects to be sent.
> -	Use it on slower connection.
> +	Spend extra cycles minimizing the number of sent objects.
> +	Use it with a slow connection.

Both the old and the new text are bollocks.

There is no extra cycles involved here.  And linking this to a slow 
connection is misleading.

The point of --thin is to create a pack containing delta objects while 
excluding the base objects they depend on when those objects are known 
to exist in the receiver's repository already.  Because base objects 
are usually significantly bigger than delta objects, this results in a 
large reduction in the amount of data to transfer.

However we don't allow a pack with delta objects referencing base 
objects to be stored in a Git repository if those base objects are not 
part of the same pack for robustness reasons.  Therefore, when a thin 
pack is transferred via the git protocol, the receiving end must 
"fatten" the pack by appending those missing base objects for that pack 
to be complete and valid.  This results in somewhat suboptimal object 
storage on the receiving end due to some object duplications.  Of course 
a simple gc will fix that.

These days --thin is always the default for a fetch.  We used to think 
that --thin might not be the best thing to do on a push given that the 
receiving end is typically a central server in that case and keeping 
storage low on a central server should be preferred.  But --thin turned 
out to be re-enabled by default for pushes by mistake on a few occasions 
when the affected code has been reworked.  No idea what state it is now, 
and I don't think that makes such a difference on the server in the end.


Nicolas

Re: [PATCH] Documentation: reword --thin description

[Stephen Boyd]

On 02/10/2010 08:07 AM, Nicolas Pitre wrote:
> Both the old and the new text are bollocks.
>
> There is no extra cycles involved here.  And linking this to a slow 
> connection is misleading.
>
> The point of --thin is to create a pack containing delta objects while 
> excluding the base objects they depend on when those objects are known 
> to exist in the receiver's repository already.  Because base objects 
> are usually significantly bigger than delta objects, this results in a 
> large reduction in the amount of data to transfer.

Thanks. Maybe this would more accurately describe the option?

Create a pack containing only delta objects when the base objects the
delta objects depend upon are present in the receiver's repository. This
typically results in less data being transferred. Default: on

Re: [PATCH] Documentation: reword --thin description

[Junio C Hamano]

Nicolas Pitre <nico@fluxnic.net> writes:

> ....  But --thin turned 
> out to be re-enabled by default for pushes by mistake on a few occasions 
> when the affected code has been reworked.  No idea what state it is now, 
> and I don't think that makes such a difference on the server in the end.

Hmmmm... it's doubly bad that the maintainer does not recall these
few occasions that mistakes happened.

Re: [PATCH] Documentation: reword --thin description

[Nicolas Pitre]

On Wed, 10 Feb 2010, Junio C Hamano wrote:

> Nicolas Pitre <nico@fluxnic.net> writes:
> 
> > ....  But --thin turned 
> > out to be re-enabled by default for pushes by mistake on a few occasions 
> > when the affected code has been reworked.  No idea what state it is now, 
> > and I don't think that makes such a difference on the server in the end.
> 
> Hmmmm... it's doubly bad that the maintainer does not recall these
> few occasions that mistakes happened.

The default was changed in commit a4503a15af.  Seems that today --thin 
is on by default again.  I don't think we should care that much, 
especially as --thin would logically have to be the default when pushing 
to a bundle.  Obviously leaving it off for push and on for fetch is 
creating needless confusion.


Nicolas

[PATCHv2] Documentation: describe --thin more accurately

[Stephen Boyd]

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

Changes since v1:
 - No longer bollocks ;-)
 - Document --thin for pack-object

 Documentation/git-fetch-pack.txt   |    6 ++++--
 Documentation/git-index-pack.txt   |    4 ++--
 Documentation/git-pack-objects.txt |    8 ++++++++
 Documentation/git-push.txt         |    7 ++++---
 Documentation/git-send-pack.txt    |    6 ++++--
 5 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index e9952e8..c428f6d 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -44,8 +44,10 @@ OPTIONS
 	locked against repacking.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Fetch 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.
 
 --include-tag::
 	If the remote side supports it, annotated tags objects will
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 65a301b..73fe51a 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -46,10 +46,10 @@ OPTIONS
 	'git repack'.
 
 --fix-thin::
-	It is possible for 'git pack-objects' to build
+	It is 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.
-	Those objects are expected to be present on the receiving end
+	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. Without this option any attempt to
 	index a thin pack will fail. This option only makes sense in
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index ffd5025..f32c322 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -179,6 +179,14 @@ base-name::
 	Add --no-reuse-object if you want to force a uniform compression
 	level on all data no matter the source.
 
+--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. This option only makes sense in
+	conjunction with --stdout.
+
 --delta-base-offset::
 	A packed archive can express base object of a delta as
 	either 20-byte object name or as an offset in the
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index bd79119..c67b06c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.
 
 --thin::
 --no-thin::
-	These options are passed to 'git send-pack'.  Thin
-	transfer spends extra cycles to minimize the number of
-	objects to be sent and meant to be used on slower connection.
+	These options are passed to linkgit:git-send-pack[1]. A thin transfer
+	significantly reduces the number of sent objects when the sender and
+	receiver share many of the same objects in common. The default is
+	\--thin.
 
 -v::
 --verbose::
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 8178d92..1d7c4d4 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -48,8 +48,10 @@ OPTIONS
 	Run verbosely.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Send 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.
 
 <host>::
 	A remote host to house the repository.  When this
-- 
1.7.0.rc2.28.gf476c0

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

[Junio C Hamano]

Stephen Boyd <bebarino@gmail.com> 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@fluxnic.net>.
>
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>

Looks better, but...

> diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
> index e9952e8..c428f6d 100644
> --- a/Documentation/git-fetch-pack.txt
> +++ b/Documentation/git-fetch-pack.txt
> @@ -44,8 +44,10 @@ OPTIONS
>  	locked against repacking.
>  
>  --thin::
> -	Spend extra cycles to minimize the number of objects to be sent.
> -	Use it on slower connection.
> +	Fetch 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.

It is useless and misleading to say "expected to be" for fetch-pack and
send-pack.  Imagine you are a first time reader of this documentation and
read the above.  Wouldn't it be very natural to ask yourself: "I want to
take advantage of reduced network traffic by using --thin.  How do I make
sure that my local repository (i.e. receiving end) satisfies that
expectation?"

The answer is, "nothing"---the protocol exchange ensures that condition.

> diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
> index 65a301b..73fe51a 100644
> --- a/Documentation/git-index-pack.txt
> +++ b/Documentation/git-index-pack.txt
> @@ -46,10 +46,10 @@ OPTIONS
>  	'git repack'.
>  
>  --fix-thin::
> -	It is possible for 'git pack-objects' to build
> +	It is 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.
> -	Those objects are expected to be present on the receiving end
> +	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. Without this option any attempt to
>  	index a thin pack will fail. This option only makes sense in

This "expected to be present and they must be included" is correct, but
"running index-pack with this option is how you 'fix' the thin pack by
including them" is missing (not your patch's fault---but because you are
touching in the vicinity on this exact topic anyway...).

> diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
> index ffd5025..f32c322 100644
> --- a/Documentation/git-pack-objects.txt
> +++ b/Documentation/git-pack-objects.txt
> @@ -179,6 +179,14 @@ base-name::
>  	Add --no-reuse-object if you want to force a uniform compression
>  	level on all data no matter the source.
>  
> +--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. This option only makes sense in
> +	conjunction with --stdout.

Before using such a "thin" pack, the receiving end must add excluded
objects back to make it self-contained and indexable by running index-pack
with its --fix-thin option.

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index bd79119..c67b06c 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.
>  
>  --thin::
>  --no-thin::
> -	These options are passed to 'git send-pack'.  Thin
> -	transfer spends extra cycles to minimize the number of
> -	objects to be sent and meant to be used on slower connection.
> +	These options are passed to linkgit:git-send-pack[1]. A thin transfer
> +	significantly reduces the number of sent objects when the sender and
> +	receiver share many of the same objects in common. The default is
> +	\--thin.

It is sometimes true that "number of" send objects is reduced, but the
significant reduction comes from sending smaller amount of data.

If both sides start out with a file with 10000 lines, and you have two
commits since then, one adding a line A and then adding another line B on
top of it.  Without --thin, you would send the last version (10000
original lines plus A and B) in full and a delta that says "starting from
that version, delete line B", in order to represent the two versions (one
with addition of line A, the other with addition of both line A and B).
With --thin, you would instead send two deltas that say "starting from the
10000-line file you have, add line A" and "starting from that result, add
line B", without sending any full version.  The sent number of objects in
these two cases are the same (the version with A added, and the version
with both A and B added). 

> diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
> index 8178d92..1d7c4d4 100644
> --- a/Documentation/git-send-pack.txt
> +++ b/Documentation/git-send-pack.txt
> @@ -48,8 +48,10 @@ OPTIONS
>  	Run verbosely.
>  
>  --thin::
> -	Spend extra cycles to minimize the number of objects to be sent.
> -	Use it on slower connection.
> +	Send 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.

The same comment as fetch-pack one applies here.

Thanks.

[PATCHv3] Documentation: describe --thin more accurately

[Stephen Boyd]

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

Changes since v2:
 - Address Junio's comments

 Documentation/git-fetch-pack.txt   |    4 ++--
 Documentation/git-index-pack.txt   |   11 ++++++-----
 Documentation/git-pack-objects.txt |    9 +++++++++
 Documentation/git-push.txt         |    7 ++++---
 Documentation/git-send-pack.txt    |    4 ++--
 5 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index e9952e8..0ad94e3 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -44,8 +44,8 @@ OPTIONS
 	locked against repacking.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Fetch a "thin" pack, which records objects in deltified form based
+	on objects not included in the pack to reduce network traffic.
 
 --include-tag::
 	If the remote side supports it, annotated tags objects will
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
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 is possible for 'git pack-objects' to build
+	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.
-	Those objects are expected to be present on the receiving end
+	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. Without this option any attempt to
-	index a thin pack will fail. This option only makes sense in
-	conjunction with --stdin.
+	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.
 
 --keep::
 	Before moving the index into its final destination
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index ffd5025..fd9181a 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -179,6 +179,15 @@ base-name::
 	Add --no-reuse-object if you want to force a uniform compression
 	level on all data no matter the source.
 
+--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.
+
 --delta-base-offset::
 	A packed archive can express base object of a delta as
 	either 20-byte object name or as an offset in the
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index bd79119..c86ad29 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.
 
 --thin::
 --no-thin::
-	These options are passed to 'git send-pack'.  Thin
-	transfer spends extra cycles to minimize the number of
-	objects to be sent and meant to be used on slower connection.
+	These options are passed to linkgit:git-send-pack[1]. A thin transfer
+	significantly reduces the amount of sent data when the sender and
+	receiver share many of the same objects in common. The default is
+	\--thin.
 
 -v::
 --verbose::
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 8178d92..deaa7d9 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -48,8 +48,8 @@ OPTIONS
 	Run verbosely.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Send a "thin" pack, which records objects in deltified form based
+	on objects not included in the pack to reduce network traffic.
 
 <host>::
 	A remote host to house the repository.  When this
-- 
1.7.0.17.g7e5eb

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

[Junio C Hamano]

Stephen Boyd <bebarino@gmail.com> 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@fluxnic.net>.
>
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---

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

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

[Stephen Boyd]

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.

[PATCHv4] Documentation: describe --thin more accurately

[Stephen Boyd]

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

Changes since v3:
 - More heavily reworked git-pack-objects.txt
 - git-index-pack.txt got inspiration from Junio in round 3

 Documentation/git-fetch-pack.txt   |    4 +-
 Documentation/git-index-pack.txt   |   12 +++-------
 Documentation/git-pack-objects.txt |   37 +++++++++++++++++++++++------------
 Documentation/git-push.txt         |    7 +++--
 Documentation/git-send-pack.txt    |    4 +-
 5 files changed, 36 insertions(+), 28 deletions(-)

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index e9952e8..0ad94e3 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -44,8 +44,8 @@ OPTIONS
 	locked against repacking.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Fetch a "thin" pack, which records objects in deltified form based
+	on objects not included in the pack to reduce network traffic.
 
 --include-tag::
 	If the remote side supports it, annotated tags objects will
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 65a301b..f3ccc72 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -46,14 +46,10 @@ OPTIONS
 	'git repack'.
 
 --fix-thin::
-	It is possible for 'git pack-objects' to build
-	"thin" pack, which records objects in deltified form based on
-	objects not included in the pack to reduce network traffic.
-	Those 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. Without this option any attempt to
-	index a thin pack will fail. This option only makes sense in
-	conjunction with --stdin.
+	Fix a "thin" pack produced by `git pack-objects --thin` (see
+	linkgit:git-pack-objects[1] for details) by adding the
+	excluded objects the deltified objects are based on to the
+	pack. This option only makes sense in conjunction with --stdin.
 
 --keep::
 	Before moving the index into its final destination
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index ffd5025..1fe5a54 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -21,16 +21,21 @@ DESCRIPTION
 Reads list of objects from the standard input, and writes a packed
 archive with specified base-name, or to the standard output.
 
-A packed archive is an efficient way to transfer set of objects
-between two repositories, and also is an archival format which
-is efficient to access.  The packed archive format (.pack) is
-designed to be self contained so that it can be unpacked without
-any further information, but for fast, random access to the objects
-in the pack, a pack index file (.idx) will be generated.
-
-Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
+A packed archive is an efficient way to transfer a set of objects
+between two repositories as well as an access efficient archival
+format.  In a packed archive, an object is either stored as a
+compressed whole or as a difference from some other object.
+The latter is often called a delta.
+
+The packed archive format (.pack) is designed to be self-contained
+so that it can be unpacked without any further information. Therefore,
+each object that a delta depends upon must be present within the pack.
+
+A pack index file (.idx) is generated for fast, random access to the
+objects in the pack. Placing both the index file (.idx) and the packed
+archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
 any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
-enables git to read from such an archive.
+enables git to read from the pack archive.
 
 The 'git unpack-objects' command can read the packed archive and
 expand the objects contained in the pack into "one-file
@@ -38,10 +43,6 @@ one-object" format; this is typically done by the smart-pull
 commands when a pack is created on-the-fly for efficient network
 transport by their peers.
 
-In a packed archive, an object is either stored as a compressed
-whole, or as a difference from some other object.  The latter is
-often called a delta.
-
 
 OPTIONS
 -------
@@ -179,6 +180,16 @@ base-name::
 	Add --no-reuse-object if you want to force a uniform compression
 	level on all data no matter the source.
 
+--thin::
+	Create a "thin" pack by omitting the common objects between a
+	sender and a receiver in order to reduce network transfer. This
+	option only makes sense in conjunction with --stdout.
++
+Note: A thin pack violates the packed archive format by omitting
+required objects and is thus unusable by git without making it
+self-contained. Use `git index-pack --fix-thin`
+(see linkgit:git-index-pack[1]) to restore the self-contained property.
+
 --delta-base-offset::
 	A packed archive can express base object of a delta as
 	either 20-byte object name or as an offset in the
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index bd79119..c86ad29 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.
 
 --thin::
 --no-thin::
-	These options are passed to 'git send-pack'.  Thin
-	transfer spends extra cycles to minimize the number of
-	objects to be sent and meant to be used on slower connection.
+	These options are passed to linkgit:git-send-pack[1]. A thin transfer
+	significantly reduces the amount of sent data when the sender and
+	receiver share many of the same objects in common. The default is
+	\--thin.
 
 -v::
 --verbose::
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 8178d92..deaa7d9 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -48,8 +48,8 @@ OPTIONS
 	Run verbosely.
 
 --thin::
-	Spend extra cycles to minimize the number of objects to be sent.
-	Use it on slower connection.
+	Send a "thin" pack, which records objects in deltified form based
+	on objects not included in the pack to reduce network traffic.
 
 <host>::
 	A remote host to house the repository.  When this
-- 
1.7.0.17.g7e5eb