Show More
@@ -0,0 +1,84 b'' | |||
|
1 | Mercurial supports generating standalone "bundle" files that hold repository | |
|
2 | data. These "bundles" are typically saved locally and used later or exchanged | |
|
3 | between different repositories, possibly on different machines. Example | |
|
4 | commands using bundles are :hg:`bundle` and :hg:`unbundle`. | |
|
5 | ||
|
6 | Generation of bundle files is controlled by a "bundle specification" | |
|
7 | ("bundlespec") string. This string tells the bundle generation process how | |
|
8 | to create the bundle. | |
|
9 | ||
|
10 | A "bundlespec" string is composed of the following elements: | |
|
11 | ||
|
12 | type | |
|
13 | A string denoting the bundle format to use. | |
|
14 | ||
|
15 | compression | |
|
16 | Denotes the compression engine to use compressing the raw bundle data. | |
|
17 | ||
|
18 | parameters | |
|
19 | Arbitrary key-value parameters to further control bundle generation. | |
|
20 | ||
|
21 | A "bundlespec" string has the following formats: | |
|
22 | ||
|
23 | <type> | |
|
24 | The literal bundle format string is used. | |
|
25 | ||
|
26 | <compression>-<type> | |
|
27 | The compression engine and format are delimited by a hypthen (``-``). | |
|
28 | ||
|
29 | Optional parameters follow the ``<type>``. Parameters are URI escaped | |
|
30 | ``key=value`` pairs. Each pair is delimited by a semicolon (``;``). The | |
|
31 | first parameter begins after a ``;`` immediately following the ``<type>`` | |
|
32 | value. | |
|
33 | ||
|
34 | Available Types | |
|
35 | =============== | |
|
36 | ||
|
37 | The following bundle <type> strings are available: | |
|
38 | ||
|
39 | v1 | |
|
40 | Produces a legacy "changegroup" version 1 bundle. | |
|
41 | ||
|
42 | This format is compatible with nearly all Mercurial clients because it is | |
|
43 | the oldest. However, it has some limitations, which is why it is no longer | |
|
44 | the default for new repositories. | |
|
45 | ||
|
46 | ``v1`` bundles can be used with modern repositories using the "generaldelta" | |
|
47 | storage format. However, it may take longer to produce the bundle and the | |
|
48 | resulting bundle may be significantly larger than a ``v2`` bundle. | |
|
49 | ||
|
50 | ``v1`` bundles can only use the ``gzip``, ``bzip2``, and ``none`` compression | |
|
51 | formats. | |
|
52 | ||
|
53 | v2 | |
|
54 | Produces a version 2 bundle. | |
|
55 | ||
|
56 | Version 2 bundles are an extensible format that can store additional | |
|
57 | repository data (such as bookmarks and phases information) and they can | |
|
58 | store data more efficiently, resulting in smaller bundles. | |
|
59 | ||
|
60 | Version 2 bundles can also use modern compression engines, such as | |
|
61 | ``zstd``, making them faster to compress and often smaller. | |
|
62 | ||
|
63 | Available Compression Engines | |
|
64 | ============================= | |
|
65 | ||
|
66 | The following bundle <compression> engines can be used: | |
|
67 | ||
|
68 | .. bundlecompressionmarker | |
|
69 | ||
|
70 | Examples | |
|
71 | ======== | |
|
72 | ||
|
73 | ``v2`` | |
|
74 | Produce a ``v2`` bundle using default options, including compression. | |
|
75 | ||
|
76 | ``none-v1`` | |
|
77 | Produce a ``v2`` bundle with no compression. | |
|
78 | ||
|
79 | ``zstd-v2`` | |
|
80 | Produce a ``v2`` bundle with zstandard compression using default | |
|
81 | settings. | |
|
82 | ||
|
83 | ``zstd-v1`` | |
|
84 | This errors because ``zstd`` is not supported for ``v1`` types. |
@@ -15,6 +15,7 b'' | |||
|
15 | 15 | <DirectoryRef Id="INSTALLDIR"> |
|
16 | 16 | <Directory Id="helpdir" Name="help" FileSource="$(var.SourceDir)"> |
|
17 | 17 | <Component Id="help.root" Guid="$(var.help.root.guid)" Win64='$(var.IsX64)'> |
|
18 | <File Name="bundlespec.txt" /> | |
|
18 | 19 | <File Name="color.txt" /> |
|
19 | 20 | <File Name="config.txt" KeyPath="yes" /> |
|
20 | 21 | <File Name="dates.txt" /> |
@@ -210,6 +210,7 b' def internalshelp(ui):' | |||
|
210 | 210 | return ''.join(lines) |
|
211 | 211 | |
|
212 | 212 | helptable = sorted([ |
|
213 | (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')), | |
|
213 | 214 | (['color'], _("Colorizing Outputs"), loaddoc('color')), |
|
214 | 215 | (["config", "hgrc"], _("Configuration Files"), loaddoc('config')), |
|
215 | 216 | (["dates"], _("Date Formats"), loaddoc('dates')), |
@@ -283,6 +284,8 b' def addtopicsymbols(topic, marker, symbo' | |||
|
283 | 284 | return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent) |
|
284 | 285 | addtopichook(topic, add) |
|
285 | 286 | |
|
287 | addtopicsymbols('bundlespec', '.. bundlecompressionmarker', | |
|
288 | util.bundlecompressiontopics()) | |
|
286 | 289 | addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols) |
|
287 | 290 | addtopicsymbols('merge-tools', '.. internaltoolsmarker', |
|
288 | 291 | filemerge.internalsdoc) |
@@ -340,6 +340,7 b' Testing -h/--help:' | |||
|
340 | 340 | |
|
341 | 341 | additional help topics: |
|
342 | 342 | |
|
343 | bundlespec Bundle File Formats | |
|
343 | 344 | color Colorizing Outputs |
|
344 | 345 | config Configuration Files |
|
345 | 346 | dates Date Formats |
@@ -423,6 +424,7 b' Testing -h/--help:' | |||
|
423 | 424 | |
|
424 | 425 | additional help topics: |
|
425 | 426 | |
|
427 | bundlespec Bundle File Formats | |
|
426 | 428 | color Colorizing Outputs |
|
427 | 429 | config Configuration Files |
|
428 | 430 | dates Date Formats |
@@ -102,6 +102,7 b' Short help:' | |||
|
102 | 102 | |
|
103 | 103 | additional help topics: |
|
104 | 104 | |
|
105 | bundlespec Bundle File Formats | |
|
105 | 106 | color Colorizing Outputs |
|
106 | 107 | config Configuration Files |
|
107 | 108 | dates Date Formats |
@@ -179,6 +180,7 b' Short help:' | |||
|
179 | 180 | |
|
180 | 181 | additional help topics: |
|
181 | 182 | |
|
183 | bundlespec Bundle File Formats | |
|
182 | 184 | color Colorizing Outputs |
|
183 | 185 | config Configuration Files |
|
184 | 186 | dates Date Formats |
@@ -827,6 +829,7 b' Test that default list of commands omits' | |||
|
827 | 829 | |
|
828 | 830 | additional help topics: |
|
829 | 831 | |
|
832 | bundlespec Bundle File Formats | |
|
830 | 833 | color Colorizing Outputs |
|
831 | 834 | config Configuration Files |
|
832 | 835 | dates Date Formats |
@@ -1838,6 +1841,15 b' Test dynamic list of merge tools only sh' | |||
|
1838 | 1841 | See the merge-tools and ui sections of hgrc(5) for details on the |
|
1839 | 1842 | configuration of merge tools. |
|
1840 | 1843 | |
|
1844 | Compression engines listed in `hg help bundlespec` | |
|
1845 | ||
|
1846 | $ hg help bundlespec | grep gzip | |
|
1847 | "v1" bundles can only use the "gzip", "bzip2", and "none" compression | |
|
1848 | An algorithm that produces smaller bundles than "gzip". | |
|
1849 | This engine will likely produce smaller bundles than "gzip" but will be | |
|
1850 | "gzip" | |
|
1851 | better compression than "gzip". It also frequently yields better | |
|
1852 | ||
|
1841 | 1853 | Test usage of section marks in help documents |
|
1842 | 1854 | |
|
1843 | 1855 | $ cd "$TESTDIR"/../doc |
@@ -1899,6 +1911,13 b' Dish up an empty repo; serve it cold.' | |||
|
1899 | 1911 | <tr><td colspan="2"><h2><a name="topics" href="#topics">Topics</a></h2></td></tr> |
|
1900 | 1912 | |
|
1901 | 1913 | <tr><td> |
|
1914 | <a href="/help/bundlespec"> | |
|
1915 | bundlespec | |
|
1916 | </a> | |
|
1917 | </td><td> | |
|
1918 | Bundle File Formats | |
|
1919 | </td></tr> | |
|
1920 | <tr><td> | |
|
1902 | 1921 | <a href="/help/color"> |
|
1903 | 1922 | color |
|
1904 | 1923 | </a> |
General Comments 0
You need to be logged in to leave comments.
Login now