1 A bundle is a container for repository data. |
|
2 |
|
3 Bundles are used as standalone files as well as the interchange format |
|
4 over the wire protocol used when two Mercurial peers communicate with |
|
5 each other. |
|
6 |
|
7 Headers |
|
8 ======= |
|
9 |
|
10 Bundles produced since Mercurial 0.7 (September 2005) have a 4 byte |
|
11 header identifying the major bundle type. The header always begins with |
|
12 ``HG`` and the follow 2 bytes indicate the bundle type/version. Some |
|
13 bundle types have additional data after this 4 byte header. |
|
14 |
|
15 The following sections describe each bundle header/type. |
|
16 |
|
17 HG10 |
|
18 ---- |
|
19 |
|
20 ``HG10`` headers indicate a *changegroup bundle*. This is the original |
|
21 bundle format, so it is sometimes referred to as *bundle1*. It has been |
|
22 present since version 0.7 (released September 2005). |
|
23 |
|
24 This header is followed by 2 bytes indicating the compression algorithm |
|
25 used for data that follows. All subsequent data following this |
|
26 compression identifier is compressed according to the algorithm/method |
|
27 specified. |
|
28 |
|
29 Supported algorithms include the following. |
|
30 |
|
31 ``BZ`` |
|
32 *bzip2* compression. |
|
33 |
|
34 Bzip2 compressors emit a leading ``BZ`` header. Mercurial uses this |
|
35 leading ``BZ`` as part of the bundle header. Therefore consumers |
|
36 of bzip2 bundles need to *seed* the bzip2 decompressor with ``BZ`` or |
|
37 seek the input stream back to the beginning of the algorithm component |
|
38 of the bundle header so that decompressor input is valid. This behavior |
|
39 is unique among supported compression algorithms. |
|
40 |
|
41 Supported since version 0.7 (released December 2006). |
|
42 |
|
43 ``GZ`` |
|
44 *zlib* compression. |
|
45 |
|
46 Supported since version 0.9.2 (released December 2006). |
|
47 |
|
48 ``UN`` |
|
49 *Uncompressed* or no compression. Unmodified changegroup data follows. |
|
50 |
|
51 Supported since version 0.9.2 (released December 2006). |
|
52 |
|
53 3rd party extensions may implement their own compression. However, no |
|
54 authority reserves values for their compression algorithm identifiers. |
|
55 |
|
56 HG2X |
|
57 ---- |
|
58 |
|
59 ``HG2X`` headers (where ``X`` is any value) denote a *bundle2* bundle. |
|
60 Bundle2 bundles are a container format for various kinds of repository |
|
61 data and capabilities, beyond changegroup data (which was the only data |
|
62 supported by ``HG10`` bundles. |
|
63 |
|
64 ``HG20`` is currently the only defined bundle2 version. |
|
65 |
|
66 The ``HG20`` format is documented at :hg:`help internals.bundle2`. |
|
67 |
|
68 Initial ``HG20`` support was added in Mercurial 3.0 (released May |
|
69 2014). However, bundle2 bundles were hidden behind an experimental flag |
|
70 until version 3.5 (released August 2015), when they were enabled in the |
|
71 wire protocol. Various commands (including ``hg bundle``) did not |
|
72 support generating bundle2 files until Mercurial 3.6 (released November |
|
73 2015). |
|
74 |
|
75 HGS1 |
|
76 ---- |
|
77 |
|
78 *Experimental* |
|
79 |
|
80 A ``HGS1`` header indicates a *streaming clone bundle*. This is a bundle |
|
81 that contains raw revlog data from a repository store. (Typically revlog |
|
82 data is exchanged in the form of changegroups.) |
|
83 |
|
84 The purpose of *streaming clone bundles* are to *clone* repository data |
|
85 very efficiently. |
|
86 |
|
87 The ``HGS1`` header is always followed by 2 bytes indicating a |
|
88 compression algorithm of the data that follows. Only ``UN`` |
|
89 (uncompressed data) is currently allowed. |
|
90 |
|
91 ``HGS1UN`` support was added as an experimental feature in version 3.6 |
|
92 (released November 2015) as part of the initial offering of the *clone |
|
93 bundles* feature. |
|