@matheusbsbs / matheus-bagliano / commits / 738820a913
Fork 0

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>

Stephen Boyd committed Feb 18, 2010 at 01:10 UTC 738820a913d05427b6c86d227aafd2bac7cd38d1
5 files changed +36 -28
Documentation/git-fetch-pack.txt
+2 -2
@@ -44,8 +44,8 @@ OPTIONS
44 locked against repacking.
45
46 --thin::
47 - Spend extra cycles to minimize the number of objects to be sent.
48 - Use it on slower connection.
47 + Fetch a "thin" pack, which records objects in deltified form based
48 + on objects not included in the pack to reduce network traffic.
49
50 --include-tag::
51 If the remote side supports it, annotated tags objects will
Documentation/git-index-pack.txt
+4 -8
@@ -46,14 +46,10 @@ OPTIONS
46 'git repack'.
47
48 --fix-thin::
49 - It is possible for 'git pack-objects' to build
50 - "thin" pack, which records objects in deltified form based on
51 - objects not included in the pack to reduce network traffic.
52 - Those objects are expected to be present on the receiving end
53 - and they must be included in the pack for that pack to be self
54 - contained and indexable. Without this option any attempt to
55 - index a thin pack will fail. This option only makes sense in
56 - conjunction with --stdin.
49 + Fix a "thin" pack produced by `git pack-objects --thin` (see
50 + linkgit:git-pack-objects[1] for details) by adding the
51 + excluded objects the deltified objects are based on to the
52 + pack. This option only makes sense in conjunction with --stdin.
53
54 --keep::
55 Before moving the index into its final destination
Documentation/git-pack-objects.txt
+24 -13
@@ -21,16 +21,21 @@ DESCRIPTION
21 Reads list of objects from the standard input, and writes a packed
22 archive with specified base-name, or to the standard output.
23
24 -A packed archive is an efficient way to transfer set of objects
25 -between two repositories, and also is an archival format which
26 -is efficient to access. The packed archive format (.pack) is
27 -designed to be self contained so that it can be unpacked without
28 -any further information, but for fast, random access to the objects
29 -in the pack, a pack index file (.idx) will be generated.
30 -
31 -Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
24 +A packed archive is an efficient way to transfer a set of objects
25 +between two repositories as well as an access efficient archival
26 +format. In a packed archive, an object is either stored as a
27 +compressed whole or as a difference from some other object.
28 +The latter is often called a delta.
29 +
30 +The packed archive format (.pack) is designed to be self-contained
31 +so that it can be unpacked without any further information. Therefore,
32 +each object that a delta depends upon must be present within the pack.
33 +
34 +A pack index file (.idx) is generated for fast, random access to the
35 +objects in the pack. Placing both the index file (.idx) and the packed
36 +archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
37 any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
33 -enables git to read from such an archive.
38 +enables git to read from the pack archive.
39
40 The 'git unpack-objects' command can read the packed archive and
41 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
43 commands when a pack is created on-the-fly for efficient network
44 transport by their peers.
45
41 -In a packed archive, an object is either stored as a compressed
42 -whole, or as a difference from some other object. The latter is
43 -often called a delta.
44 -
46
47 OPTIONS
48 -------
@@ -179,6 +180,16 @@ base-name::
180 Add --no-reuse-object if you want to force a uniform compression
181 level on all data no matter the source.
182
183 +--thin::
184 + Create a "thin" pack by omitting the common objects between a
185 + sender and a receiver in order to reduce network transfer. This
186 + option only makes sense in conjunction with --stdout.
187 ++
188 +Note: A thin pack violates the packed archive format by omitting
189 +required objects and is thus unusable by git without making it
190 +self-contained. Use `git index-pack --fix-thin`
191 +(see linkgit:git-index-pack[1]) to restore the self-contained property.
192 +
193 --delta-base-offset::
194 A packed archive can express base object of a delta as
195 either 20-byte object name or as an offset in the
Documentation/git-push.txt
+4 -3
@@ -141,9 +141,10 @@ useful if you write an alias or script around 'git push'.
141
142 --thin::
143 --no-thin::
144 - These options are passed to 'git send-pack'. Thin
145 - transfer spends extra cycles to minimize the number of
146 - objects to be sent and meant to be used on slower connection.
144 + These options are passed to linkgit:git-send-pack[1]. A thin transfer
145 + significantly reduces the amount of sent data when the sender and
146 + receiver share many of the same objects in common. The default is
147 + \--thin.
148
149 -v::
150 --verbose::
Documentation/git-send-pack.txt
+2 -2
@@ -48,8 +48,8 @@ OPTIONS
48 Run verbosely.
49
50 --thin::
51 - Spend extra cycles to minimize the number of objects to be sent.
52 - Use it on slower connection.
51 + Send a "thin" pack, which records objects in deltified form based
52 + on objects not included in the pack to reduce network traffic.
53
54 <host>::
55 A remote host to house the repository. When this