Re: [PATCHv2] Documentation: describe --thin more accurately
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:48:14
Stephen Boyd [off-list ref] 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 [off-list ref]. Signed-off-by: Stephen Boyd <redacted>
Looks better, but...
quoted hunk
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.
quoted hunk
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...).
quoted hunk
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.
quoted hunk
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).
quoted hunk
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.