{"thread":{"id":"22598","subject":"[PATCH] Documentation: reword --thin description","startedAt":"2010-02-10T05:14:11Z","lastAt":"2010-02-18T09:10:28Z","messageCount":11,"participants":["Stephen Boyd","Nicolas Pitre","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"134119","messageId":"1265778851-5397-1-git-send-email-bebarino@gmail.com","threadId":"22598","inReplyTo":null,"subject":"[PATCH] Documentation: reword --thin description","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-10T05:14:11Z","receivedAt":"2010-02-10T05:14:11Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"Signed-off-by: Stephen Boyd <bebarino@gmail.com>\n---\n\nDon't know if git-push needs to say that --thin is passed to send-pack.\n\n Documentation/git-fetch-pack.txt |    4 ++--\n Documentation/git-push.txt       |    6 +++---\n Documentation/git-send-pack.txt  |    4 ++--\n 3 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\nindex e9952e8..2b4e4dd 100644\n--- a/Documentation/git-fetch-pack.txt\n+++ b/Documentation/git-fetch-pack.txt\n@@ -44,8 +44,8 @@ OPTIONS\n \tlocked against repacking.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tSpend extra cycles minimizing the number of sent objects.\n+\tUse it with a slow connection.\n \n --include-tag::\n \tIf the remote side supports it, annotated tags objects will\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex bd79119..a14bc9c 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -141,9 +141,9 @@ useful if you write an alias or script around 'git push'.\n \n --thin::\n --no-thin::\n-\tThese options are passed to 'git send-pack'.  Thin\n-\ttransfer spends extra cycles to minimize the number of\n-\tobjects to be sent and meant to be used on slower connection.\n+\tThese options are passed to 'git send-pack'.  A thin\n+\ttransfer spends extra cycles minimizing the number of\n+\tsent objects and is meant to be used with a slow connection.\n \n -v::\n --verbose::\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex 8178d92..0a78dac 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -48,8 +48,8 @@ OPTIONS\n \tRun verbosely.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tSpend extra cycles minimizing the number of sent objects.\n+\tUse it with a slow connection.\n \n <host>::\n \tA remote host to house the repository.  When this\n-- \n1.7.0.rc2\n"},{"id":"134146","messageId":"alpine.LFD.2.00.1002101037300.1681@xanadu.home","threadId":"22598","inReplyTo":"1265778851-5397-1-git-send-email-bebarino@gmail.com","subject":"Re: [PATCH] Documentation: reword --thin description","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-10T16:07:09Z","receivedAt":"2010-02-10T16:07:09Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Tue, 9 Feb 2010, Stephen Boyd wrote:\n\n>  --thin::\n> -\tSpend extra cycles to minimize the number of objects to be sent.\n> -\tUse it on slower connection.\n> +\tSpend extra cycles minimizing the number of sent objects.\n> +\tUse it with a slow connection.\n\nBoth the old and the new text are bollocks.\n\nThere is no extra cycles involved here.  And linking this to a slow \nconnection is misleading.\n\nThe point of --thin is to create a pack containing delta objects while \nexcluding the base objects they depend on when those objects are known \nto exist in the receiver's repository already.  Because base objects \nare usually significantly bigger than delta objects, this results in a \nlarge reduction in the amount of data to transfer.\n\nHowever we don't allow a pack with delta objects referencing base \nobjects to be stored in a Git repository if those base objects are not \npart of the same pack for robustness reasons.  Therefore, when a thin \npack is transferred via the git protocol, the receiving end must \n\"fatten\" the pack by appending those missing base objects for that pack \nto be complete and valid.  This results in somewhat suboptimal object \nstorage on the receiving end due to some object duplications.  Of course \na simple gc will fix that.\n\nThese days --thin is always the default for a fetch.  We used to think \nthat --thin might not be the best thing to do on a push given that the \nreceiving end is typically a central server in that case and keeping \nstorage low on a central server should be preferred.  But --thin turned \nout to be re-enabled by default for pushes by mistake on a few occasions \nwhen the affected code has been reworked.  No idea what state it is now, \nand I don't think that makes such a difference on the server in the end.\n\n\nNicolas\n"},{"id":"134151","messageId":"4B72E463.6060409@gmail.com","threadId":"22598","inReplyTo":"alpine.LFD.2.00.1002101037300.1681@xanadu.home","subject":"Re: [PATCH] Documentation: reword --thin description","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-10T16:52:51Z","receivedAt":"2010-02-10T16:52:51Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"On 02/10/2010 08:07 AM, Nicolas Pitre wrote:\n> Both the old and the new text are bollocks.\n>\n> There is no extra cycles involved here.  And linking this to a slow \n> connection is misleading.\n>\n> The point of --thin is to create a pack containing delta objects while \n> excluding the base objects they depend on when those objects are known \n> to exist in the receiver's repository already.  Because base objects \n> are usually significantly bigger than delta objects, this results in a \n> large reduction in the amount of data to transfer.\n\nThanks. Maybe this would more accurately describe the option?\n\nCreate a pack containing only delta objects when the base objects the\ndelta objects depend upon are present in the receiver's repository. This\ntypically results in less data being transferred. Default: on\n"},{"id":"134165","messageId":"7vsk98apcr.fsf@alter.siamese.dyndns.org","threadId":"22598","inReplyTo":"alpine.LFD.2.00.1002101037300.1681@xanadu.home","subject":"Re: [PATCH] Documentation: reword --thin description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-10T18:59:48Z","receivedAt":"2010-02-10T18:59:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre <nico@fluxnic.net> writes:\n\n> ....  But --thin turned \n> out to be re-enabled by default for pushes by mistake on a few occasions \n> when the affected code has been reworked.  No idea what state it is now, \n> and I don't think that makes such a difference on the server in the end.\n\nHmmmm... it's doubly bad that the maintainer does not recall these\nfew occasions that mistakes happened.\n"},{"id":"134184","messageId":"alpine.LFD.2.00.1002101554200.1681@xanadu.home","threadId":"22598","inReplyTo":"7vsk98apcr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: reword --thin description","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-10T21:04:57Z","receivedAt":"2010-02-10T21:04:57Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Wed, 10 Feb 2010, Junio C Hamano wrote:\n\n> Nicolas Pitre <nico@fluxnic.net> writes:\n> \n> > ....  But --thin turned \n> > out to be re-enabled by default for pushes by mistake on a few occasions \n> > when the affected code has been reworked.  No idea what state it is now, \n> > and I don't think that makes such a difference on the server in the end.\n> \n> Hmmmm... it's doubly bad that the maintainer does not recall these\n> few occasions that mistakes happened.\n\nThe default was changed in commit a4503a15af.  Seems that today --thin \nis on by default again.  I don't think we should care that much, \nespecially as --thin would logically have to be the default when pushing \nto a bundle.  Obviously leaving it off for push and on for fetch is \ncreating needless confusion.\n\n\nNicolas\n"},{"id":"134293","messageId":"1265961646-28585-1-git-send-email-bebarino@gmail.com","threadId":"22598","inReplyTo":"1265778851-5397-1-git-send-email-bebarino@gmail.com","subject":"[PATCHv2] Documentation: describe --thin more accurately","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-12T08:00:46Z","receivedAt":"2010-02-12T08:00:46Z","isPatch":false,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"The description for --thin was misleading and downright wrong. Correct\nit with some inspiration from the description of index-pack's --fix-thin\nand some background information from Nicolas Pitre <nico@fluxnic.net>.\n\nSigned-off-by: Stephen Boyd <bebarino@gmail.com>\n---\n\nChanges since v1:\n - No longer bollocks ;-)\n - Document --thin for pack-object\n\n Documentation/git-fetch-pack.txt   |    6 ++++--\n Documentation/git-index-pack.txt   |    4 ++--\n Documentation/git-pack-objects.txt |    8 ++++++++\n Documentation/git-push.txt         |    7 ++++---\n Documentation/git-send-pack.txt    |    6 ++++--\n 5 files changed, 22 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\nindex e9952e8..c428f6d 100644\n--- a/Documentation/git-fetch-pack.txt\n+++ b/Documentation/git-fetch-pack.txt\n@@ -44,8 +44,10 @@ OPTIONS\n \tlocked against repacking.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tFetch a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n+\tThe excluded objects are expected to be present on the receiving\n+\tend.\n \n --include-tag::\n \tIf the remote side supports it, annotated tags objects will\ndiff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\nindex 65a301b..73fe51a 100644\n--- a/Documentation/git-index-pack.txt\n+++ b/Documentation/git-index-pack.txt\n@@ -46,10 +46,10 @@ OPTIONS\n \t'git repack'.\n \n --fix-thin::\n-\tIt is possible for 'git pack-objects' to build\n+\tIt is possible for 'git pack-objects' to build a\n \t\"thin\" pack, which records objects in deltified form based on\n \tobjects not included in the pack to reduce network traffic.\n-\tThose objects are expected to be present on the receiving end\n+\tThe excluded objects are expected to be present on the receiving end\n \tand they must be included in the pack for that pack to be self\n \tcontained and indexable. Without this option any attempt to\n \tindex a thin pack will fail. This option only makes sense in\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex ffd5025..f32c322 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -179,6 +179,14 @@ base-name::\n \tAdd --no-reuse-object if you want to force a uniform compression\n \tlevel on all data no matter the source.\n \n+--thin::\n+\tCreate a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n+\tThe excluded objects are expected to be present on the receiving end\n+\tand eventually must be included in the pack for that pack to be self\n+\tcontained and indexable. This option only makes sense in\n+\tconjunction with --stdout.\n+\n --delta-base-offset::\n \tA packed archive can express base object of a delta as\n \teither 20-byte object name or as an offset in the\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex bd79119..c67b06c 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.\n \n --thin::\n --no-thin::\n-\tThese options are passed to 'git send-pack'.  Thin\n-\ttransfer spends extra cycles to minimize the number of\n-\tobjects to be sent and meant to be used on slower connection.\n+\tThese options are passed to linkgit:git-send-pack[1]. A thin transfer\n+\tsignificantly reduces the number of sent objects when the sender and\n+\treceiver share many of the same objects in common. The default is\n+\t\\--thin.\n \n -v::\n --verbose::\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex 8178d92..1d7c4d4 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -48,8 +48,10 @@ OPTIONS\n \tRun verbosely.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tSend a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n+\tThe excluded objects are expected to be present on the receiving\n+\tend.\n \n <host>::\n \tA remote host to house the repository.  When this\n-- \n1.7.0.rc2.28.gf476c0\n"},{"id":"134363","messageId":"7vhbpm2w6n.fsf@alter.siamese.dyndns.org","threadId":"22598","inReplyTo":"1265961646-28585-1-git-send-email-bebarino@gmail.com","subject":"Re: [PATCHv2] Documentation: describe --thin more accurately","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-12T17:36:16Z","receivedAt":"2010-02-12T17:36:16Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephen Boyd <bebarino@gmail.com> writes:\n\n> The description for --thin was misleading and downright wrong. Correct\n> it with some inspiration from the description of index-pack's --fix-thin\n> and some background information from Nicolas Pitre <nico@fluxnic.net>.\n>\n> Signed-off-by: Stephen Boyd <bebarino@gmail.com>\n\nLooks better, but...\n\n> diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\n> index e9952e8..c428f6d 100644\n> --- a/Documentation/git-fetch-pack.txt\n> +++ b/Documentation/git-fetch-pack.txt\n> @@ -44,8 +44,10 @@ OPTIONS\n>  \tlocked against repacking.\n>  \n>  --thin::\n> -\tSpend extra cycles to minimize the number of objects to be sent.\n> -\tUse it on slower connection.\n> +\tFetch a \"thin\" pack, which records objects in deltified form based\n> +\ton objects not included in the pack to reduce network traffic.\n> +\tThe excluded objects are expected to be present on the receiving\n> +\tend.\n\nIt is useless and misleading to say \"expected to be\" for fetch-pack and\nsend-pack.  Imagine you are a first time reader of this documentation and\nread the above.  Wouldn't it be very natural to ask yourself: \"I want to\ntake advantage of reduced network traffic by using --thin.  How do I make\nsure that my local repository (i.e. receiving end) satisfies that\nexpectation?\"\n\nThe answer is, \"nothing\"---the protocol exchange ensures that condition.\n\n> diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\n> index 65a301b..73fe51a 100644\n> --- a/Documentation/git-index-pack.txt\n> +++ b/Documentation/git-index-pack.txt\n> @@ -46,10 +46,10 @@ OPTIONS\n>  \t'git repack'.\n>  \n>  --fix-thin::\n> -\tIt is possible for 'git pack-objects' to build\n> +\tIt is possible for 'git pack-objects' to build a\n>  \t\"thin\" pack, which records objects in deltified form based on\n>  \tobjects not included in the pack to reduce network traffic.\n> -\tThose objects are expected to be present on the receiving end\n> +\tThe excluded objects are expected to be present on the receiving end\n>  \tand they must be included in the pack for that pack to be self\n>  \tcontained and indexable. Without this option any attempt to\n>  \tindex a thin pack will fail. This option only makes sense in\n\nThis \"expected to be present and they must be included\" is correct, but\n\"running index-pack with this option is how you 'fix' the thin pack by\nincluding them\" is missing (not your patch's fault---but because you are\ntouching in the vicinity on this exact topic anyway...).\n\n> diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\n> index ffd5025..f32c322 100644\n> --- a/Documentation/git-pack-objects.txt\n> +++ b/Documentation/git-pack-objects.txt\n> @@ -179,6 +179,14 @@ base-name::\n>  \tAdd --no-reuse-object if you want to force a uniform compression\n>  \tlevel on all data no matter the source.\n>  \n> +--thin::\n> +\tCreate a \"thin\" pack, which records objects in deltified form based\n> +\ton objects not included in the pack to reduce network traffic.\n> +\tThe excluded objects are expected to be present on the receiving end\n> +\tand eventually must be included in the pack for that pack to be self\n> +\tcontained and indexable. This option only makes sense in\n> +\tconjunction with --stdout.\n\nBefore using such a \"thin\" pack, the receiving end must add excluded\nobjects back to make it self-contained and indexable by running index-pack\nwith its --fix-thin option.\n\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index bd79119..c67b06c 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.\n>  \n>  --thin::\n>  --no-thin::\n> -\tThese options are passed to 'git send-pack'.  Thin\n> -\ttransfer spends extra cycles to minimize the number of\n> -\tobjects to be sent and meant to be used on slower connection.\n> +\tThese options are passed to linkgit:git-send-pack[1]. A thin transfer\n> +\tsignificantly reduces the number of sent objects when the sender and\n> +\treceiver share many of the same objects in common. The default is\n> +\t\\--thin.\n\nIt is sometimes true that \"number of\" send objects is reduced, but the\nsignificant reduction comes from sending smaller amount of data.\n\nIf both sides start out with a file with 10000 lines, and you have two\ncommits since then, one adding a line A and then adding another line B on\ntop of it.  Without --thin, you would send the last version (10000\noriginal lines plus A and B) in full and a delta that says \"starting from\nthat version, delete line B\", in order to represent the two versions (one\nwith addition of line A, the other with addition of both line A and B).\nWith --thin, you would instead send two deltas that say \"starting from the\n10000-line file you have, add line A\" and \"starting from that result, add\nline B\", without sending any full version.  The sent number of objects in\nthese two cases are the same (the version with A added, and the version\nwith both A and B added). \n\n> diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\n> index 8178d92..1d7c4d4 100644\n> --- a/Documentation/git-send-pack.txt\n> +++ b/Documentation/git-send-pack.txt\n> @@ -48,8 +48,10 @@ OPTIONS\n>  \tRun verbosely.\n>  \n>  --thin::\n> -\tSpend extra cycles to minimize the number of objects to be sent.\n> -\tUse it on slower connection.\n> +\tSend a \"thin\" pack, which records objects in deltified form based\n> +\ton objects not included in the pack to reduce network traffic.\n> +\tThe excluded objects are expected to be present on the receiving\n> +\tend.\n\nThe same comment as fetch-pack one applies here.\n\nThanks.\n"},{"id":"134655","messageId":"1266262395-11864-1-git-send-email-bebarino@gmail.com","threadId":"22598","inReplyTo":"1265961646-28585-1-git-send-email-bebarino@gmail.com","subject":"[PATCHv3] Documentation: describe --thin more accurately","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-15T19:33:15Z","receivedAt":"2010-02-15T19:33:15Z","isPatch":false,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"The description for --thin was misleading and downright wrong. Correct\nit with some inspiration from the description of index-pack's --fix-thin\nand some background information from Nicolas Pitre <nico@fluxnic.net>.\n\nSigned-off-by: Stephen Boyd <bebarino@gmail.com>\n---\n\nChanges since v2:\n - Address Junio's comments\n\n Documentation/git-fetch-pack.txt   |    4 ++--\n Documentation/git-index-pack.txt   |   11 ++++++-----\n Documentation/git-pack-objects.txt |    9 +++++++++\n Documentation/git-push.txt         |    7 ++++---\n Documentation/git-send-pack.txt    |    4 ++--\n 5 files changed, 23 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\nindex e9952e8..0ad94e3 100644\n--- a/Documentation/git-fetch-pack.txt\n+++ b/Documentation/git-fetch-pack.txt\n@@ -44,8 +44,8 @@ OPTIONS\n \tlocked against repacking.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tFetch a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n \n --include-tag::\n \tIf the remote side supports it, annotated tags objects will\ndiff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\nindex 65a301b..b4fa98e 100644\n--- a/Documentation/git-index-pack.txt\n+++ b/Documentation/git-index-pack.txt\n@@ -46,14 +46,15 @@ OPTIONS\n \t'git repack'.\n \n --fix-thin::\n-\tIt is possible for 'git pack-objects' to build\n+\tIt's possible for 'git pack-objects' to build a\n \t\"thin\" pack, which records objects in deltified form based on\n \tobjects not included in the pack to reduce network traffic.\n-\tThose objects are expected to be present on the receiving end\n+\tThe excluded objects are expected to be present on the receiving end\n \tand they must be included in the pack for that pack to be self\n-\tcontained and indexable. Without this option any attempt to\n-\tindex a thin pack will fail. This option only makes sense in\n-\tconjunction with --stdin.\n+\tcontained and indexable. This option fixes the \"thin\" pack by\n+\tadding the missing objects to the pack. Without this option any\n+\tattempt to index a \"thin\" pack will fail. This option only makes\n+\tsense in conjunction with --stdin.\n \n --keep::\n \tBefore moving the index into its final destination\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex ffd5025..fd9181a 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -179,6 +179,15 @@ base-name::\n \tAdd --no-reuse-object if you want to force a uniform compression\n \tlevel on all data no matter the source.\n \n+--thin::\n+\tCreate a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n+\tThe excluded objects are expected to be present on the receiving end\n+\tand eventually must be included in the pack for that pack to be self\n+\tcontained and indexable (see the \\--fix-thin option of\n+\tlinkgit:git-index-pack[1] for more details). This option only makes\n+\tsense in conjunction with --stdout.\n+\n --delta-base-offset::\n \tA packed archive can express base object of a delta as\n \teither 20-byte object name or as an offset in the\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex bd79119..c86ad29 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.\n \n --thin::\n --no-thin::\n-\tThese options are passed to 'git send-pack'.  Thin\n-\ttransfer spends extra cycles to minimize the number of\n-\tobjects to be sent and meant to be used on slower connection.\n+\tThese options are passed to linkgit:git-send-pack[1]. A thin transfer\n+\tsignificantly reduces the amount of sent data when the sender and\n+\treceiver share many of the same objects in common. The default is\n+\t\\--thin.\n \n -v::\n --verbose::\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex 8178d92..deaa7d9 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -48,8 +48,8 @@ OPTIONS\n \tRun verbosely.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tSend a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n \n <host>::\n \tA remote host to house the repository.  When this\n-- \n1.7.0.17.g7e5eb\n"},{"id":"134662","messageId":"7vfx52xm8d.fsf@alter.siamese.dyndns.org","threadId":"22598","inReplyTo":"1266262395-11864-1-git-send-email-bebarino@gmail.com","subject":"Re: [PATCHv3] Documentation: describe --thin more accurately","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-15T20:44:34Z","receivedAt":"2010-02-15T20:44:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephen Boyd <bebarino@gmail.com> writes:\n\n> The description for --thin was misleading and downright wrong. Correct\n> it with some inspiration from the description of index-pack's --fix-thin\n> and some background information from Nicolas Pitre <nico@fluxnic.net>.\n>\n> Signed-off-by: Stephen Boyd <bebarino@gmail.com>\n> ---\n\nLooking better, thanks.\n\n> index 65a301b..b4fa98e 100644\n> --- a/Documentation/git-index-pack.txt\n> +++ b/Documentation/git-index-pack.txt\n> @@ -46,14 +46,15 @@ OPTIONS\n>  \t'git repack'.\n>  \n>  --fix-thin::\n> +\tIt's possible for 'git pack-objects' to build a\n>  \t\"thin\" pack, which records objects in deltified form based on\n>  \tobjects not included in the pack to reduce network traffic.\n> +\tThe excluded objects are expected to be present on the receiving end\n>  \tand they must be included in the pack for that pack to be self\n> +\tcontained and indexable. This option fixes the \"thin\" pack by\n> +\tadding the missing objects to the pack. Without this option any\n> +\tattempt to index a \"thin\" pack will fail. This option only makes\n> +\tsense in conjunction with --stdin.\n\nAssuming that the reader knows only what \"git objects\" are, and that a\n\"pack\" contains \"git objects\" either in full or in a \"deltified form based\non another object\", the description needs to explain three points:\n\n - \"self-containedness\" requirement to be directly usable by git;\n - \"thin\" pack reduces transfer by violating \"self-containedness\"; and\n - \"--fix-thin\" makes \"thin\" into \"self-contained\".\n\nI however think the first two points might be better covered by the\ndescription of `--thin` of `pack-objects` and we should simply refer to it\nfrom here, like this:\n\n    --fix-thin::\n            Make a \"thin\" pack produced by `git pack-objects --thin` (see\n            linkgit:git-pack-objects[1] for details) directly usable by\n            git, by adding objects that the objects stored in the\n            deltified form are based on to the packfile.\n\nAnd we can thicken the --thin description of pack-objects like this:\n\n> +--thin::\n> +\tCreate a \"thin\" pack, which records objects in deltified form based\n> +\ton objects not included in the pack to reduce network traffic.\n> +\tThe excluded objects are expected to be present on the receiving end\n> +\tand eventually must be included in the pack for that pack to be self\n> +\tcontained and indexable (see the \\--fix-thin option of\n> +\tlinkgit:git-index-pack[1] for more details). This option only makes\n> +\tsense in conjunction with --stdout.\n> +\n\n    --thin::\n            Create a \"thin\" pack in order to reduce network transfer.\n    +\n    For a packfile to be usable directly by git, any object in the pack\n    that is represented in the deltified form must be based on an object\n    that exists in the same pack.  Such a pack is called \"self-contained\".\n    +\n    If the sender sends an object in the deltified form based on an object\n    both the sender and the receiver have, but excludes the common object\n    itself from the datastream, it can often reduce the network traffic\n    dramatically.  Such a datastream is called a \"thin\" pack.\n    +\n    Note that a thin pack violates the self-containedness requirement and\n    is not directly usable by git on the receiving end without making it a\n    self-contained pack by running `git index-pack --fix-thin` (see\n    linkgit:git-index-pack[1]).\n"},{"id":"134932","messageId":"4B7CFB4C.2020507@gmail.com","threadId":"22598","inReplyTo":"7vfx52xm8d.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv3] Documentation: describe --thin more accurately","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-18T08:33:16Z","receivedAt":"2010-02-18T08:33:16Z","isPatch":false,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"On 02/15/2010 12:44 PM, Junio C Hamano wrote:\n> I however think the first two points might be better covered by the\n> description of `--thin` of `pack-objects` and we should simply refer to it\n> from here, like this:\n>\n>     --fix-thin::\n>             Make a \"thin\" pack produced by `git pack-objects --thin` (see\n>             linkgit:git-pack-objects[1] for details) directly usable by\n>             git, by adding objects that the objects stored in the\n>             deltified form are based on to the packfile.\n>\n\nThis looks good. I'd like to avoid introducing the term packfile though\nand just use pack throughout.\n\n>     --thin::\n>             Create a \"thin\" pack in order to reduce network transfer.\n>     +\n>     For a packfile to be usable directly by git, any object in the pack\n>     that is represented in the deltified form must be based on an object\n>     that exists in the same pack.  Such a pack is called \"self-contained\".\n>     +\n>     If the sender sends an object in the deltified form based on an object\n>     both the sender and the receiver have, but excludes the common object\n>     itself from the datastream, it can often reduce the network traffic\n>     dramatically.  Such a datastream is called a \"thin\" pack.\n>     +\n>     Note that a thin pack violates the self-containedness requirement and\n>     is not directly usable by git on the receiving end without making it a\n>     self-contained pack by running `git index-pack --fix-thin` (see\n>     linkgit:git-index-pack[1]).\n\nThis looks long winded. Perhaps we can do without explaining what\nself-containedness is? If you read the second paragraph in the\ndescription section of git-pack-objects.txt it tries to explain\nself-contained:\n\n    The packed archive format (.pack) is designed to be \n    self-contained so that it can be unpacked without\n    any further information\n\n\nIf all I know is a pack contains objects and deltas based on other\nobjects I might be able to figure out that all the objects must be\npresent in the pack for it to be self-contained. This description\nsection might need some work but I don't think repeating ourselves in\n--thin is good.\n\nUpdated patch to follow.\n"},{"id":"134936","messageId":"1266484228-25787-1-git-send-email-bebarino@gmail.com","threadId":"22598","inReplyTo":"1266262395-11864-1-git-send-email-bebarino@gmail.com","subject":"[PATCHv4] Documentation: describe --thin more accurately","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-02-18T09:10:28Z","receivedAt":"2010-02-18T09:10:28Z","isPatch":false,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"The description for --thin was misleading and downright wrong. Correct\nit with some inspiration from the description of index-pack's --fix-thin\nand some background information from Nicolas Pitre <nico@fluxnic.net>.\n\nSigned-off-by: Stephen Boyd <bebarino@gmail.com>\n---\n\nChanges since v3:\n - More heavily reworked git-pack-objects.txt\n - git-index-pack.txt got inspiration from Junio in round 3\n\n Documentation/git-fetch-pack.txt   |    4 +-\n Documentation/git-index-pack.txt   |   12 +++-------\n Documentation/git-pack-objects.txt |   37 +++++++++++++++++++++++------------\n Documentation/git-push.txt         |    7 +++--\n Documentation/git-send-pack.txt    |    4 +-\n 5 files changed, 36 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\nindex e9952e8..0ad94e3 100644\n--- a/Documentation/git-fetch-pack.txt\n+++ b/Documentation/git-fetch-pack.txt\n@@ -44,8 +44,8 @@ OPTIONS\n \tlocked against repacking.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tFetch a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n \n --include-tag::\n \tIf the remote side supports it, annotated tags objects will\ndiff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\nindex 65a301b..f3ccc72 100644\n--- a/Documentation/git-index-pack.txt\n+++ b/Documentation/git-index-pack.txt\n@@ -46,14 +46,10 @@ OPTIONS\n \t'git repack'.\n \n --fix-thin::\n-\tIt is possible for 'git pack-objects' to build\n-\t\"thin\" pack, which records objects in deltified form based on\n-\tobjects not included in the pack to reduce network traffic.\n-\tThose objects are expected to be present on the receiving end\n-\tand they must be included in the pack for that pack to be self\n-\tcontained and indexable. Without this option any attempt to\n-\tindex a thin pack will fail. This option only makes sense in\n-\tconjunction with --stdin.\n+\tFix a \"thin\" pack produced by `git pack-objects --thin` (see\n+\tlinkgit:git-pack-objects[1] for details) by adding the\n+\texcluded objects the deltified objects are based on to the\n+\tpack. This option only makes sense in conjunction with --stdin.\n \n --keep::\n \tBefore moving the index into its final destination\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex ffd5025..1fe5a54 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -21,16 +21,21 @@ DESCRIPTION\n Reads list of objects from the standard input, and writes a packed\n archive with specified base-name, or to the standard output.\n \n-A packed archive is an efficient way to transfer set of objects\n-between two repositories, and also is an archival format which\n-is efficient to access.  The packed archive format (.pack) is\n-designed to be self contained so that it can be unpacked without\n-any further information, but for fast, random access to the objects\n-in the pack, a pack index file (.idx) will be generated.\n-\n-Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or\n+A packed archive is an efficient way to transfer a set of objects\n+between two repositories as well as an access efficient archival\n+format.  In a packed archive, an object is either stored as a\n+compressed whole or as a difference from some other object.\n+The latter is often called a delta.\n+\n+The packed archive format (.pack) is designed to be self-contained\n+so that it can be unpacked without any further information. Therefore,\n+each object that a delta depends upon must be present within the pack.\n+\n+A pack index file (.idx) is generated for fast, random access to the\n+objects in the pack. Placing both the index file (.idx) and the packed\n+archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or\n any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)\n-enables git to read from such an archive.\n+enables git to read from the pack archive.\n \n The 'git unpack-objects' command can read the packed archive and\n expand the objects contained in the pack into \"one-file\n@@ -38,10 +43,6 @@ one-object\" format; this is typically done by the smart-pull\n commands when a pack is created on-the-fly for efficient network\n transport by their peers.\n \n-In a packed archive, an object is either stored as a compressed\n-whole, or as a difference from some other object.  The latter is\n-often called a delta.\n-\n \n OPTIONS\n -------\n@@ -179,6 +180,16 @@ base-name::\n \tAdd --no-reuse-object if you want to force a uniform compression\n \tlevel on all data no matter the source.\n \n+--thin::\n+\tCreate a \"thin\" pack by omitting the common objects between a\n+\tsender and a receiver in order to reduce network transfer. This\n+\toption only makes sense in conjunction with --stdout.\n++\n+Note: A thin pack violates the packed archive format by omitting\n+required objects and is thus unusable by git without making it\n+self-contained. Use `git index-pack --fix-thin`\n+(see linkgit:git-index-pack[1]) to restore the self-contained property.\n+\n --delta-base-offset::\n \tA packed archive can express base object of a delta as\n \teither 20-byte object name or as an offset in the\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex bd79119..c86ad29 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.\n \n --thin::\n --no-thin::\n-\tThese options are passed to 'git send-pack'.  Thin\n-\ttransfer spends extra cycles to minimize the number of\n-\tobjects to be sent and meant to be used on slower connection.\n+\tThese options are passed to linkgit:git-send-pack[1]. A thin transfer\n+\tsignificantly reduces the amount of sent data when the sender and\n+\treceiver share many of the same objects in common. The default is\n+\t\\--thin.\n \n -v::\n --verbose::\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex 8178d92..deaa7d9 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -48,8 +48,8 @@ OPTIONS\n \tRun verbosely.\n \n --thin::\n-\tSpend extra cycles to minimize the number of objects to be sent.\n-\tUse it on slower connection.\n+\tSend a \"thin\" pack, which records objects in deltified form based\n+\ton objects not included in the pack to reduce network traffic.\n \n <host>::\n \tA remote host to house the repository.  When this\n-- \n1.7.0.17.g7e5eb\n"}]}