Documentation: describe --thin more accurately

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 97ea7973a0839eacf74f2f5bd1ca6a17670c7a8b..4a8487c1547abc156c8fad9e7cafe4d3c5a535f6 100644 (file)
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -44,8 +44,8 @@ OPTIONS
        locked against repacking.
 
 --thin::
        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
 
 --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 65a301becefb837b74bffa2d2dd11d51e229a06a..f3ccc72f0d68f03cd7b3fb6a36aabc8d7c7772a1 100644 (file)
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -46,14 +46,10 @@ OPTIONS
        'git repack'.
 
 --fix-thin::
        '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
 
 --keep::
        Before moving the index into its final destination

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 61fd7d09982255aa0488555a54256fc3f03c76e4..034caedc39b6438d64fdc49ae93c82912e40446c 100644 (file)
--- 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.
 
 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)
 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
 
 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.
 
 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
 -------
 
 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.
 
        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
 --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 3f103ccb00b10bb4472b82feae32e0e0a5e80fc2..49b6bd9d925f9150a4aaf2f2c4d7439503863d05 100644 (file)
--- 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::
 
 --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::
 
 -v::
 --verbose::

diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 8178d9264251e45d5af5cabfca2d193252ac1768..deaa7d9654f5938fabad3e1eae29ae7c7803d2ec 100644 (file)
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -48,8 +48,8 @@ OPTIONS
        Run verbosely.
 
 --thin::
        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
 
 <host>::
        A remote host to house the repository.  When this