Doc: clarify that pack-objects makes packs, plural
The documentation for pack-objects describes that it creates "a packed archive of objects", which is confusing because it may create multiple packs if --max-pack-size is set. Update the documentation to clarify this, and explaining in which cases such a feature would be useful. Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Tan committed
Aug 22, 2017 at 17:40 UTC
4a4becfb23a2ef98b51bbde3bacda63a85972882
1 file changed
+11
-6
Documentation/git-pack-objects.txt
+11
-6
@@ -18,8 +18,9 @@ SYNOPSIS
18
19
DESCRIPTION
20
-----------
21
-Reads list of objects from the standard input, and writes a packed
22
-archive with specified base-name, or to the standard output.
21
+Reads list of objects from the standard input, and writes either one or
22
+more packed archives with the specified base-name to disk, or a packed
23
+archive to the standard output.
24
25
A packed archive is an efficient way to transfer a set of objects
26
between two repositories as well as an access efficient archival
@@ -47,9 +48,9 @@ transport by their peers.
48
OPTIONS
49
-------
50
base-name::
50
- Write into a pair of files (.pack and .idx), using
51
+ Write into pairs of files (.pack and .idx), using
52
<base-name> to determine the name of the created file.
52
- When this option is used, the two files are written in
53
+ When this option is used, the two files in a pair are written in
54
<base-name>-<SHA-1>.{pack,idx} files. <SHA-1> is a hash
55
based on the pack content and is written to the standard
56
output of the command.
@@ -108,9 +109,13 @@ base-name::
109
is taken from the `pack.windowMemory` configuration variable.
110
111
--max-pack-size=<n>::
111
- Maximum size of each output pack file. The size can be suffixed with
112
+ In unusual scenarios, you may not be able to create files
113
+ larger than a certain size on your filesystem, and this option
114
+ can be used to tell the command to split the output packfile
115
+ into multiple independent packfiles, each not larger than the
116
+ given size. The size can be suffixed with
117
"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
113
- If specified, multiple packfiles may be created, which also
118
+ This option
119
prevents the creation of a bitmap index.
120
The default is unlimited, unless the config variable
121
`pack.packSizeLimit` is set.