docs: don't talk about $GIT_DIR/refs/ everywhere
[git/git.git] / Documentation / git-pack-objects.txt
CommitLineData
5f40520f
JH
1git-pack-objects(1)
2===================
5f40520f
JH
3
4NAME
5----
7bd7f280 6git-pack-objects - Create a packed archive of objects
5f40520f
JH
7
8
9SYNOPSIS
10--------
ca5381d4 11[verse]
4f366275
NP
12'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
13 [--no-reuse-delta] [--delta-base-offset] [--non-empty]
14 [--local] [--incremental] [--window=N] [--depth=N]
7f3140cd
JS
15 [--revs [--unpacked | --all]*] [--stdout | base-name]
16 [--keep-true-parents] < object-list
5f40520f
JH
17
18
19DESCRIPTION
20-----------
21Reads list of objects from the standard input, and writes a packed
22archive with specified base-name, or to the standard output.
23
24A packed archive is an efficient way to transfer set of objects
25between two repositories, and also is an archival format which
26is efficient to access. The packed archive format (.pack) is
ba1333fe
PE
27designed to be self contained so that it can be unpacked without
28any further information, but for fast, random access to the objects
29in the pack, a pack index file (.idx) will be generated.
5f40520f 30
1e6ab5de
MK
31Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
32any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
33enables git to read from such an archive.
34
0b444cdb 35The 'git unpack-objects' command can read the packed archive and
5f40520f
JH
36expand the objects contained in the pack into "one-file
37one-object" format; this is typically done by the smart-pull
38commands when a pack is created on-the-fly for efficient network
39transport by their peers.
40
ca5381d4
JH
41In a packed archive, an object is either stored as a compressed
42whole, or as a difference from some other object. The latter is
43often called a delta.
44
5f40520f
JH
45
46OPTIONS
47-------
48base-name::
49 Write into a pair of files (.pack and .idx), using
50 <base-name> to determine the name of the created file.
51 When this option is used, the two files are written in
52 <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash
e23ed9a8
NP
53 of the sorted object names to make the resulting filename
54 based on the pack content, and written to the standard
5f40520f
JH
55 output of the command.
56
57--stdout::
89438677 58 Write the pack contents (what would have been written to
5f40520f
JH
59 .pack file) out to the standard output.
60
4321134c
JH
61--revs::
62 Read the revision arguments from the standard input, instead of
63 individual object names. The revision arguments are processed
0b444cdb 64 the same way as 'git rev-list' with the `--objects` flag
4321134c
JH
65 uses its `commit` arguments to build the list of objects it
66 outputs. The objects on the resulting list are packed.
67
68--unpacked::
69 This implies `--revs`. When processing the list of
70 revision arguments read from the standard input, limit
71 the objects packed to those that are not already packed.
72
73--all::
74 This implies `--revs`. In addition to the list of
75 revision arguments read from the standard input, pretend
cc1b8d8b 76 as if all refs under `refs/` are specified to be
4321134c
JH
77 included.
78
f0a24aa5
SP
79--include-tag::
80 Include unasked-for annotated tags if the object they
81 reference was included in the resulting packfile. This
82 can be useful to send new tags to native git clients.
83
3240240f
SB
84--window=[N]::
85--depth=[N]::
3df19671 86 These two options affect how the objects contained in
5f40520f
JH
87 the pack are stored using delta compression. The
88 objects are first internally sorted by type, size and
89 optionally names and compared against the other objects
90 within --window to see if using delta compression saves
91 space. --depth limits the maximum delta depth; making
92 it too deep affects the performance on the unpacker
93 side, because delta data needs to be applied that many
94 times to get to the necessary object.
618e613a 95 The default value for --window is 10 and --depth is 50.
5f40520f 96
e93b15cd
BD
97--window-memory=[N]::
98 This option provides an additional limit on top of `--window`;
99 the window size will dynamically scale down so as to not take
100 up more than N bytes in memory. This is useful in
101 repositories with a mix of large and small objects to not run
102 out of memory with a large window, but still be able to take
103 advantage of the large window for the smaller objects. The
104 size can be suffixed with "k", "m", or "g".
105 `--window-memory=0` makes memory usage unlimited, which is the
106 default.
107
07cf0f24
NP
108--max-pack-size=[N]::
109 Maximum size of each output pack file. The size can be suffixed with
110 "k", "m", or "g". The minimum size allowed is limited to 1 MiB.
6b94b1a0 111 If specified, multiple packfiles may be created.
2b84b5a8
JS
112 The default is unlimited, unless the config variable
113 `pack.packSizeLimit` is set.
6b94b1a0 114
e96fb9b8
BC
115--honor-pack-keep::
116 This flag causes an object already in a local pack that
117 has a .keep file to be ignored, even if it appears in the
118 standard input.
119
5f40520f
JH
120--incremental::
121 This flag causes an object already in a pack ignored
122 even if it appears in the standard input.
123
12ea5bea
JH
124--local::
125 This flag is similar to `--incremental`; instead of
126 ignoring all packed objects, it only ignores objects
daae0625 127 that are packed and/or not in the local object store
12ea5bea 128 (i.e. borrowed from an alternate).
5f40520f 129
63ae26f8
NW
130--non-empty::
131 Only create a packed archive if it would contain at
132 least one object.
133
231f240b
NP
134--progress::
135 Progress status is reported on the standard error stream
136 by default when it is attached to a terminal, unless -q
137 is specified. This flag forces progress status even if
138 the standard error stream is not directed to a terminal.
139
140--all-progress::
141 When --stdout is specified then progress report is
4f366275 142 displayed during the object count and compression phases
231f240b
NP
143 but inhibited during the write-out phase. The reason is
144 that in some cases the output stream is directly linked
145 to another command which may wish to display progress
146 status of its own as it processes incoming pack data.
147 This flag is like --progress except that it forces progress
148 report for the write-out phase as well even if --stdout is
149 used.
150
4f366275
NP
151--all-progress-implied::
152 This is used to imply --all-progress whenever progress display
153 is activated. Unlike --all-progress this flag doesn't actually
154 force any progress display by itself.
155
ca5381d4
JH
156-q::
157 This flag makes the command not to report its progress
158 on the standard error stream.
159
160--no-reuse-delta::
161 When creating a packed archive in a repository that
162 has existing packs, the command reuses existing deltas.
163 This sometimes results in a slightly suboptimal pack.
164 This flag tells the command not to reuse existing deltas
165 but compute them from scratch.
166
fa736f72
NP
167--no-reuse-object::
168 This flag tells the command not to reuse existing object data at all,
169 including non deltified object, forcing recompression of everything.
960ccca6 170 This implies --no-reuse-delta. Useful only in the obscure case where
fa736f72
NP
171 wholesale enforcement of a different compression level on the
172 packed data is desired.
173
960ccca6
DH
174--compression=[N]::
175 Specifies compression level for newly-compressed data in the
176 generated pack. If not specified, pack compression level is
177 determined first by pack.compression, then by core.compression,
178 and defaults to -1, the zlib default, if neither is set.
483bc4f0 179 Add --no-reuse-object if you want to force a uniform compression
05cc2ffc 180 level on all data no matter the source.
960ccca6 181
63fba759
JH
182--delta-base-offset::
183 A packed archive can express base object of a delta as
184 either 20-byte object name or as an offset in the
185 stream, but older version of git does not understand the
0b444cdb 186 latter. By default, 'git pack-objects' only uses the
63fba759
JH
187 former format for better compatibility. This option
188 allows the command to use the latter format for
189 compactness. Depending on the average delta chain
190 length, this option typically shrinks the resulting
191 packfile by 3-5 per-cent.
192
367f4a43
NP
193--threads=<n>::
194 Specifies the number of threads to spawn when searching for best
195 delta matches. This requires that pack-objects be compiled with
196 pthreads otherwise this option is ignored with a warning.
197 This is meant to reduce packing time on multiprocessor machines.
198 The required amount of memory for the delta search window is
199 however multiplied by the number of threads.
833e3df1
AE
200 Specifying 0 will cause git to auto-detect the number of CPU's
201 and set the number of threads accordingly.
367f4a43 202
be18c1fe
NP
203--index-version=<version>[,<offset>]::
204 This is intended to be used by the test suite only. It allows
205 to force the version for the generated pack index, and to force
206 64-bit index entries on objects located above the given offset.
207
7f3140cd
JS
208--keep-true-parents::
209 With this option, parents that are hidden by grafts are packed
210 nevertheless.
211
ca5381d4 212
5f40520f
JH
213Author
214------
215Written by Linus Torvalds <torvalds@osdl.org>
216
217Documentation
218-------------
219Documentation by Junio C Hamano
220
56ae8df5 221SEE ALSO
e31bb3bb 222--------
5162e697
DM
223linkgit:git-rev-list[1]
224linkgit:git-repack[1]
225linkgit:git-prune-packed[1]
e31bb3bb 226
5f40520f
JH
227GIT
228---
9e1f0a85 229Part of the linkgit:git[1] suite