annotate mercurial/help/bundlespec.txt @ 43148:843da18386d5

sidedatacopies: deal with upgrading and downgrading to that format This is quite useful to test this on real life data. Differential Revision: https://phab.mercurial-scm.org/D6955
author Pierre-Yves David <pierre-yves.david@octobus.net>
date Sun, 06 Oct 2019 23:36:52 -0400
parents 01280ec5f840
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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>
32139
de86a6872d06 help: spelling fixes
Matt Harbison <matt_harbison@yahoo.com>
parents: 31793
diff changeset
27 The compression engine and format are delimited by a hyphen (``-``).
31793
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``
32573
01280ec5f840 help: fix typos
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 32139
diff changeset
77 Produce a ``v1`` bundle with no compression.
31793
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.