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