diff options
Diffstat (limited to 'third_party/git/Documentation/git-pack-objects.txt')
| -rw-r--r-- | third_party/git/Documentation/git-pack-objects.txt | 411 |
1 files changed, 0 insertions, 411 deletions
diff --git a/third_party/git/Documentation/git-pack-objects.txt b/third_party/git/Documentation/git-pack-objects.txt deleted file mode 100644 index 54d715ead137..000000000000 --- a/third_party/git/Documentation/git-pack-objects.txt +++ /dev/null @@ -1,411 +0,0 @@ -git-pack-objects(1) -=================== - -NAME ----- -git-pack-objects - Create a packed archive of objects - - -SYNOPSIS --------- -[verse] -'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] - [--no-reuse-delta] [--delta-base-offset] [--non-empty] - [--local] [--incremental] [--window=<n>] [--depth=<n>] - [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list - - -DESCRIPTION ------------ -Reads list of objects from the standard input, and writes either one or -more packed archives with the specified base-name to disk, or a packed -archive to the standard output. - -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) -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 -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. - - -OPTIONS -------- -base-name:: - Write into pairs of files (.pack and .idx), using - <base-name> to determine the name of the created file. - When this option is used, the two files in a pair are written in - <base-name>-<SHA-1>.{pack,idx} files. <SHA-1> is a hash - based on the pack content and is written to the standard - output of the command. - ---stdout:: - Write the pack contents (what would have been written to - .pack file) out to the standard output. - ---revs:: - Read the revision arguments from the standard input, instead of - individual object names. The revision arguments are processed - the same way as 'git rev-list' with the `--objects` flag - uses its `commit` arguments to build the list of objects it - outputs. The objects on the resulting list are packed. - Besides revisions, `--not` or `--shallow <SHA-1>` lines are - also accepted. - ---unpacked:: - This implies `--revs`. When processing the list of - revision arguments read from the standard input, limit - the objects packed to those that are not already packed. - ---all:: - This implies `--revs`. In addition to the list of - revision arguments read from the standard input, pretend - as if all refs under `refs/` are specified to be - included. - ---include-tag:: - Include unasked-for annotated tags if the object they - reference was included in the resulting packfile. This - can be useful to send new tags to native Git clients. - ---window=<n>:: ---depth=<n>:: - These two options affect how the objects contained in - the pack are stored using delta compression. The - objects are first internally sorted by type, size and - optionally names and compared against the other objects - within --window to see if using delta compression saves - space. --depth limits the maximum delta depth; making - it too deep affects the performance on the unpacker - side, because delta data needs to be applied that many - times to get to the necessary object. -+ -The default value for --window is 10 and --depth is 50. The maximum -depth is 4095. - ---window-memory=<n>:: - This option provides an additional limit on top of `--window`; - the window size will dynamically scale down so as to not take - up more than '<n>' bytes in memory. This is useful in - repositories with a mix of large and small objects to not run - out of memory with a large window, but still be able to take - advantage of the large window for the smaller objects. The - size can be suffixed with "k", "m", or "g". - `--window-memory=0` makes memory usage unlimited. The default - is taken from the `pack.windowMemory` configuration variable. - ---max-pack-size=<n>:: - In unusual scenarios, you may not be able to create files - larger than a certain size on your filesystem, and this option - can be used to tell the command to split the output packfile - into multiple independent packfiles, each not larger than the - given size. The size can be suffixed with - "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - This option - prevents the creation of a bitmap index. - The default is unlimited, unless the config variable - `pack.packSizeLimit` is set. - ---honor-pack-keep:: - This flag causes an object already in a local pack that - has a .keep file to be ignored, even if it would have - otherwise been packed. - ---keep-pack=<pack-name>:: - This flag causes an object already in the given pack to be - ignored, even if it would have otherwise been - packed. `<pack-name>` is the pack file name without - leading directory (e.g. `pack-123.pack`). The option could be - specified multiple times to keep multiple packs. - ---incremental:: - This flag causes an object already in a pack to be ignored - even if it would have otherwise been packed. - ---local:: - This flag causes an object that is borrowed from an alternate - object store to be ignored even if it would have otherwise been - packed. - ---non-empty:: - Only create a packed archive if it would contain at - least one object. - ---progress:: - Progress status is reported on the standard error stream - by default when it is attached to a terminal, unless -q - is specified. This flag forces progress status even if - the standard error stream is not directed to a terminal. - ---all-progress:: - When --stdout is specified then progress report is - displayed during the object count and compression phases - but inhibited during the write-out phase. The reason is - that in some cases the output stream is directly linked - to another command which may wish to display progress - status of its own as it processes incoming pack data. - This flag is like --progress except that it forces progress - report for the write-out phase as well even if --stdout is - used. - ---all-progress-implied:: - This is used to imply --all-progress whenever progress display - is activated. Unlike --all-progress this flag doesn't actually - force any progress display by itself. - --q:: - This flag makes the command not to report its progress - on the standard error stream. - ---no-reuse-delta:: - When creating a packed archive in a repository that - has existing packs, the command reuses existing deltas. - This sometimes results in a slightly suboptimal pack. - This flag tells the command not to reuse existing deltas - but compute them from scratch. - ---no-reuse-object:: - This flag tells the command not to reuse existing object data at all, - including non deltified object, forcing recompression of everything. - This implies --no-reuse-delta. Useful only in the obscure case where - wholesale enforcement of a different compression level on the - packed data is desired. - ---compression=<n>:: - Specifies compression level for newly-compressed data in the - generated pack. If not specified, pack compression level is - determined first by pack.compression, then by core.compression, - and defaults to -1, the zlib default, if neither is set. - Add --no-reuse-object if you want to force a uniform compression - level on all data no matter the source. - ---[no-]sparse:: - Toggle the "sparse" algorithm to determine which objects to include in - the pack, when combined with the "--revs" option. This algorithm - only walks trees that appear in paths that introduce new objects. - This can have significant performance benefits when computing - a pack to send a small change. However, it is possible that extra - objects are added to the pack-file if the included commits contain - certain types of direct renames. If this option is not included, - it defaults to the value of `pack.useSparse`, which is true unless - otherwise specified. - ---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. - ---shallow:: - Optimize a pack that will be provided to a client with a shallow - repository. This option, combined with --thin, can result in a - smaller pack at the cost of speed. - ---delta-base-offset:: - A packed archive can express the base object of a delta as - either a 20-byte object name or as an offset in the - stream, but ancient versions of Git don't understand the - latter. By default, 'git pack-objects' only uses the - former format for better compatibility. This option - allows the command to use the latter format for - compactness. Depending on the average delta chain - length, this option typically shrinks the resulting - packfile by 3-5 per-cent. -+ -Note: Porcelain commands such as `git gc` (see linkgit:git-gc[1]), -`git repack` (see linkgit:git-repack[1]) pass this option by default -in modern Git when they put objects in your repository into pack files. -So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. - ---threads=<n>:: - Specifies the number of threads to spawn when searching for best - delta matches. This requires that pack-objects be compiled with - pthreads otherwise this option is ignored with a warning. - This is meant to reduce packing time on multiprocessor machines. - The required amount of memory for the delta search window is - however multiplied by the number of threads. - Specifying 0 will cause Git to auto-detect the number of CPU's - and set the number of threads accordingly. - ---index-version=<version>[,<offset>]:: - This is intended to be used by the test suite only. It allows - to force the version for the generated pack index, and to force - 64-bit index entries on objects located above the given offset. - ---keep-true-parents:: - With this option, parents that are hidden by grafts are packed - nevertheless. - ---filter=<filter-spec>:: - Requires `--stdout`. Omits certain objects (usually blobs) from - the resulting packfile. See linkgit:git-rev-list[1] for valid - `<filter-spec>` forms. - ---no-filter:: - Turns off any previous `--filter=` argument. - ---missing=<missing-action>:: - A debug option to help with future "partial clone" development. - This option specifies how missing objects are handled. -+ -The form '--missing=error' requests that pack-objects stop with an error if -a missing object is encountered. If the repository is a partial clone, an -attempt to fetch missing objects will be made before declaring them missing. -This is the default action. -+ -The form '--missing=allow-any' will allow object traversal to continue -if a missing object is encountered. No fetch of a missing object will occur. -Missing objects will silently be omitted from the results. -+ -The form '--missing=allow-promisor' is like 'allow-any', but will only -allow object traversal to continue for EXPECTED promisor missing objects. -No fetch of a missing object will occur. An unexpected missing object will -raise an error. - ---exclude-promisor-objects:: - Omit objects that are known to be in the promisor remote. (This - option has the purpose of operating only on locally created objects, - so that when we repack, we still maintain a distinction between - locally created objects [without .promisor] and objects from the - promisor remote [with .promisor].) This is used with partial clone. - ---keep-unreachable:: - Objects unreachable from the refs in packs named with - --unpacked= option are added to the resulting pack, in - addition to the reachable objects that are not in packs marked - with *.keep files. This implies `--revs`. - ---pack-loose-unreachable:: - Pack unreachable loose objects (and their loose counterparts - removed). This implies `--revs`. - ---unpack-unreachable:: - Keep unreachable objects in loose form. This implies `--revs`. - ---delta-islands:: - Restrict delta matches based on "islands". See DELTA ISLANDS - below. - - -DELTA ISLANDS -------------- - -When possible, `pack-objects` tries to reuse existing on-disk deltas to -avoid having to search for new ones on the fly. This is an important -optimization for serving fetches, because it means the server can avoid -inflating most objects at all and just send the bytes directly from -disk. This optimization can't work when an object is stored as a delta -against a base which the receiver does not have (and which we are not -already sending). In that case the server "breaks" the delta and has to -find a new one, which has a high CPU cost. Therefore it's important for -performance that the set of objects in on-disk delta relationships match -what a client would fetch. - -In a normal repository, this tends to work automatically. The objects -are mostly reachable from the branches and tags, and that's what clients -fetch. Any deltas we find on the server are likely to be between objects -the client has or will have. - -But in some repository setups, you may have several related but separate -groups of ref tips, with clients tending to fetch those groups -independently. For example, imagine that you are hosting several "forks" -of a repository in a single shared object store, and letting clients -view them as separate repositories through `GIT_NAMESPACE` or separate -repos using the alternates mechanism. A naive repack may find that the -optimal delta for an object is against a base that is only found in -another fork. But when a client fetches, they will not have the base -object, and we'll have to find a new delta on the fly. - -A similar situation may exist if you have many refs outside of -`refs/heads/` and `refs/tags/` that point to related objects (e.g., -`refs/pull` or `refs/changes` used by some hosting providers). By -default, clients fetch only heads and tags, and deltas against objects -found only in those other groups cannot be sent as-is. - -Delta islands solve this problem by allowing you to group your refs into -distinct "islands". Pack-objects computes which objects are reachable -from which islands, and refuses to make a delta from an object `A` -against a base which is not present in all of `A`'s islands. This -results in slightly larger packs (because we miss some delta -opportunities), but guarantees that a fetch of one island will not have -to recompute deltas on the fly due to crossing island boundaries. - -When repacking with delta islands the delta window tends to get -clogged with candidates that are forbidden by the config. Repacking -with a big --window helps (and doesn't take as long as it otherwise -might because we can reject some object pairs based on islands before -doing any computation on the content). - -Islands are configured via the `pack.island` option, which can be -specified multiple times. Each value is a left-anchored regular -expressions matching refnames. For example: - -------------------------------------------- -[pack] -island = refs/heads/ -island = refs/tags/ -------------------------------------------- - -puts heads and tags into an island (whose name is the empty string; see -below for more on naming). Any refs which do not match those regular -expressions (e.g., `refs/pull/123`) is not in any island. Any object -which is reachable only from `refs/pull/` (but not heads or tags) is -therefore not a candidate to be used as a base for `refs/heads/`. - -Refs are grouped into islands based on their "names", and two regexes -that produce the same name are considered to be in the same -island. The names are computed from the regexes by concatenating any -capture groups from the regex, with a '-' dash in between. (And if -there are no capture groups, then the name is the empty string, as in -the above example.) This allows you to create arbitrary numbers of -islands. Only up to 14 such capture groups are supported though. - -For example, imagine you store the refs for each fork in -`refs/virtual/ID`, where `ID` is a numeric identifier. You might then -configure: - -------------------------------------------- -[pack] -island = refs/virtual/([0-9]+)/heads/ -island = refs/virtual/([0-9]+)/tags/ -island = refs/virtual/([0-9]+)/(pull)/ -------------------------------------------- - -That puts the heads and tags for each fork in their own island (named -"1234" or similar), and the pull refs for each go into their own -"1234-pull". - -Note that we pick a single island for each regex to go into, using "last -one wins" ordering (which allows repo-specific config to take precedence -over user-wide config, and so forth). - -SEE ALSO --------- -linkgit:git-rev-list[1] -linkgit:git-repack[1] -linkgit:git-prune-packed[1] - -GIT ---- -Part of the linkgit:git[1] suite |