diff --git a/contrib/wix/help.wxs b/contrib/wix/help.wxs --- a/contrib/wix/help.wxs +++ b/contrib/wix/help.wxs @@ -15,6 +15,7 @@ + diff --git a/mercurial/help.py b/mercurial/help.py --- a/mercurial/help.py +++ b/mercurial/help.py @@ -210,6 +210,7 @@ def internalshelp(ui): return ''.join(lines) helptable = sorted([ + (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')), (['color'], _("Colorizing Outputs"), loaddoc('color')), (["config", "hgrc"], _("Configuration Files"), loaddoc('config')), (["dates"], _("Date Formats"), loaddoc('dates')), @@ -283,6 +284,8 @@ def addtopicsymbols(topic, marker, symbo return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent) addtopichook(topic, add) +addtopicsymbols('bundlespec', '.. bundlecompressionmarker', + util.bundlecompressiontopics()) addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols) addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internalsdoc) diff --git a/mercurial/help/bundlespec.txt b/mercurial/help/bundlespec.txt new file mode 100644 --- /dev/null +++ b/mercurial/help/bundlespec.txt @@ -0,0 +1,84 @@ +Mercurial supports generating standalone "bundle" files that hold repository +data. These "bundles" are typically saved locally and used later or exchanged +between different repositories, possibly on different machines. Example +commands using bundles are :hg:`bundle` and :hg:`unbundle`. + +Generation of bundle files is controlled by a "bundle specification" +("bundlespec") string. This string tells the bundle generation process how +to create the bundle. + +A "bundlespec" string is composed of the following elements: + +type + A string denoting the bundle format to use. + +compression + Denotes the compression engine to use compressing the raw bundle data. + +parameters + Arbitrary key-value parameters to further control bundle generation. + +A "bundlespec" string has the following formats: + + + The literal bundle format string is used. + +- + The compression engine and format are delimited by a hypthen (``-``). + +Optional parameters follow the ````. Parameters are URI escaped +``key=value`` pairs. Each pair is delimited by a semicolon (``;``). The +first parameter begins after a ``;`` immediately following the ```` +value. + +Available Types +=============== + +The following bundle strings are available: + +v1 + Produces a legacy "changegroup" version 1 bundle. + + This format is compatible with nearly all Mercurial clients because it is + the oldest. However, it has some limitations, which is why it is no longer + the default for new repositories. + + ``v1`` bundles can be used with modern repositories using the "generaldelta" + storage format. However, it may take longer to produce the bundle and the + resulting bundle may be significantly larger than a ``v2`` bundle. + + ``v1`` bundles can only use the ``gzip``, ``bzip2``, and ``none`` compression + formats. + +v2 + Produces a version 2 bundle. + + Version 2 bundles are an extensible format that can store additional + repository data (such as bookmarks and phases information) and they can + store data more efficiently, resulting in smaller bundles. + + Version 2 bundles can also use modern compression engines, such as + ``zstd``, making them faster to compress and often smaller. + +Available Compression Engines +============================= + +The following bundle engines can be used: + +.. bundlecompressionmarker + +Examples +======== + +``v2`` + Produce a ``v2`` bundle using default options, including compression. + +``none-v1`` + Produce a ``v2`` bundle with no compression. + +``zstd-v2`` + Produce a ``v2`` bundle with zstandard compression using default + settings. + +``zstd-v1`` + This errors because ``zstd`` is not supported for ``v1`` types. diff --git a/tests/test-globalopts.t b/tests/test-globalopts.t --- a/tests/test-globalopts.t +++ b/tests/test-globalopts.t @@ -340,6 +340,7 @@ Testing -h/--help: additional help topics: + bundlespec Bundle File Formats color Colorizing Outputs config Configuration Files dates Date Formats @@ -423,6 +424,7 @@ Testing -h/--help: additional help topics: + bundlespec Bundle File Formats color Colorizing Outputs config Configuration Files dates Date Formats diff --git a/tests/test-help.t b/tests/test-help.t --- a/tests/test-help.t +++ b/tests/test-help.t @@ -102,6 +102,7 @@ Short help: additional help topics: + bundlespec Bundle File Formats color Colorizing Outputs config Configuration Files dates Date Formats @@ -179,6 +180,7 @@ Short help: additional help topics: + bundlespec Bundle File Formats color Colorizing Outputs config Configuration Files dates Date Formats @@ -827,6 +829,7 @@ Test that default list of commands omits additional help topics: + bundlespec Bundle File Formats color Colorizing Outputs config Configuration Files dates Date Formats @@ -1838,6 +1841,15 @@ Test dynamic list of merge tools only sh See the merge-tools and ui sections of hgrc(5) for details on the configuration of merge tools. +Compression engines listed in `hg help bundlespec` + + $ hg help bundlespec | grep gzip + "v1" bundles can only use the "gzip", "bzip2", and "none" compression + An algorithm that produces smaller bundles than "gzip". + This engine will likely produce smaller bundles than "gzip" but will be + "gzip" + better compression than "gzip". It also frequently yields better + Test usage of section marks in help documents $ cd "$TESTDIR"/../doc @@ -1899,6 +1911,13 @@ Dish up an empty repo; serve it cold.

Topics

+ + bundlespec + + + Bundle File Formats + + color diff --git a/tests/test-hgweb-json.t b/tests/test-hgweb-json.t --- a/tests/test-hgweb-json.t +++ b/tests/test-hgweb-json.t @@ -1549,6 +1549,10 @@ help/ shows help topics ], "topics": [ { + "summary": "Bundle File Formats", + "topic": "bundlespec" + }, + { "summary": "Colorizing Outputs", "topic": "color" },