Mercurial > hg
annotate mercurial/help/bundlespec.txt @ 31956:c13ff31818b0
ui: add special-purpose atexit functionality
In spite of its longstanding use, Python's built-in atexit code is
not suitable for Mercurial's purposes, for several reasons:
* Handlers run after application code has finished.
* Because of this, the code that runs handlers swallows exceptions
(since there's no possible stacktrace to associate errors with).
If we're lucky, we'll get something spat out to stderr (if stderr
still works), which of course isn't any use in a big deployment
where it's important that exceptions get logged and aggregated.
* Mercurial's current atexit handlers make unfortunate assumptions
about process state (specifically stdio) that, coupled with the
above problems, make it impossible to deal with certain categories
of error (try "hg status > /dev/full" on a Linux box).
* In Python 3, the atexit implementation is completely hidden, so
we can't hijack the platform's atexit code to run handlers at a
time of our choosing.
As a result, here's a perfectly cromulent atexit-like implementation
over which we have control. This lets us decide exactly when the
handlers run (after each request has completed), and control what
the process state is when that occurs (and afterwards).
author | Bryan O'Sullivan <bryano@fb.com> |
---|---|
date | Tue, 11 Apr 2017 14:54:12 -0700 |
parents | 69d8fcf20014 |
children | de86a6872d06 |
rev | line source |
---|---|
31793
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
1 Mercurial supports generating standalone "bundle" files that hold repository |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
2 data. These "bundles" are typically saved locally and used later or exchanged |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
3 between different repositories, possibly on different machines. Example |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
4 commands using bundles are :hg:`bundle` and :hg:`unbundle`. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
5 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
6 Generation of bundle files is controlled by a "bundle specification" |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
7 ("bundlespec") string. This string tells the bundle generation process how |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
8 to create the bundle. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
9 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
10 A "bundlespec" string is composed of the following elements: |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
11 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
12 type |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
13 A string denoting the bundle format to use. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
14 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
15 compression |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
16 Denotes the compression engine to use compressing the raw bundle data. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
17 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
18 parameters |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
19 Arbitrary key-value parameters to further control bundle generation. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
20 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
21 A "bundlespec" string has the following formats: |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
22 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
23 <type> |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
24 The literal bundle format string is used. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
25 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
26 <compression>-<type> |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
27 The compression engine and format are delimited by a hypthen (``-``). |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
28 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
29 Optional parameters follow the ``<type>``. Parameters are URI escaped |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
30 ``key=value`` pairs. Each pair is delimited by a semicolon (``;``). The |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
31 first parameter begins after a ``;`` immediately following the ``<type>`` |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
32 value. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
33 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
34 Available Types |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
35 =============== |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
36 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
37 The following bundle <type> strings are available: |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
38 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
39 v1 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
40 Produces a legacy "changegroup" version 1 bundle. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
41 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
42 This format is compatible with nearly all Mercurial clients because it is |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
43 the oldest. However, it has some limitations, which is why it is no longer |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
44 the default for new repositories. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
45 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
46 ``v1`` bundles can be used with modern repositories using the "generaldelta" |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
47 storage format. However, it may take longer to produce the bundle and the |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
48 resulting bundle may be significantly larger than a ``v2`` bundle. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
49 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
50 ``v1`` bundles can only use the ``gzip``, ``bzip2``, and ``none`` compression |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
51 formats. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
52 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
53 v2 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
54 Produces a version 2 bundle. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
55 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
56 Version 2 bundles are an extensible format that can store additional |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
57 repository data (such as bookmarks and phases information) and they can |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
58 store data more efficiently, resulting in smaller bundles. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
59 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
60 Version 2 bundles can also use modern compression engines, such as |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
61 ``zstd``, making them faster to compress and often smaller. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
62 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
63 Available Compression Engines |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
64 ============================= |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
65 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
66 The following bundle <compression> engines can be used: |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
67 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
68 .. bundlecompressionmarker |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
69 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
70 Examples |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
71 ======== |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
72 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
73 ``v2`` |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
74 Produce a ``v2`` bundle using default options, including compression. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
75 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
76 ``none-v1`` |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
77 Produce a ``v2`` bundle with no compression. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
78 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
79 ``zstd-v2`` |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
80 Produce a ``v2`` bundle with zstandard compression using default |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
81 settings. |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
82 |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
83 ``zstd-v1`` |
69d8fcf20014
help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
84 This errors because ``zstd`` is not supported for ``v1`` types. |