mercurial/help/internals/bundles.txt
author Matt Harbison <matt_harbison@yahoo.com>
Fri, 09 Jun 2017 22:15:53 -0400
changeset 32802 9a4adc76c88a
parent 29759 aba2bb2a6d0f
child 36481 1fa35ca345a5
permissions -rw-r--r--
setup: avoid linker warnings on Windows about multiple export specifications The PyMODINIT_FUNC macro contains __declspec(dllexport), and then the build process adds an "/EXPORT func" to the command line. The 64-bit linker flags this [1]. Everything except zstd.c and bser.c are covered by redefining the macro in util.h [2]. These modules aren't built with util.h in the #include path, so the redefining hack would have to be open coded two more times. After seeing that extra_linker_flags didn't work, I couldn't find anything authoritative indicating why, though I did see an offhand comment on SO that CFLAGS is also ignored on Windows. I also don't fully understand the interaction between msvccompiler and msvc9compiler- I first subclassed the latter, but it isn't used when building with VS2008. I know the camelcase naming isn't the standard, but the HackedMingw32CCompiler class above it was introduced 5 years ago (and I think the current style was in place by then), so I assume that there's some reason for it. [1] https://support.microsoft.com/en-us/help/835326/you-receive-an-lnk4197-error-in-the-64-bit-version-of-the-visual-c-compiler [2] https://bugs.python.org/issue9709#msg120859
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
27373
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     1
A bundle is a container for repository data.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     2
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     3
Bundles are used as standalone files as well as the interchange format
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     4
over the wire protocol used when two Mercurial peers communicate with
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     5
each other.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     6
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     7
Headers
29759
aba2bb2a6d0f help: don't try to render a section on sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27373
diff changeset
     8
=======
27373
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     9
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    10
Bundles produced since Mercurial 0.7 (September 2005) have a 4 byte
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    11
header identifying the major bundle type. The header always begins with
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    12
``HG`` and the follow 2 bytes indicate the bundle type/version. Some
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    13
bundle types have additional data after this 4 byte header.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    14
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    15
The following sections describe each bundle header/type.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    16
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    17
HG10
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    18
----
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    19
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    20
``HG10`` headers indicate a *changegroup bundle*. This is the original
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    21
bundle format, so it is sometimes referred to as *bundle1*. It has been
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    22
present since version 0.7 (released September 2005).
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    23
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    24
This header is followed by 2 bytes indicating the compression algorithm
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    25
used for data that follows. All subsequent data following this
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    26
compression identifier is compressed according to the algorithm/method
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    27
specified.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    28
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    29
Supported algorithms include the following.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    30
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    31
``BZ``
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    32
   *bzip2* compression.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    33
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    34
   Bzip2 compressors emit a leading ``BZ`` header. Mercurial uses this
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    35
   leading ``BZ`` as part of the bundle header. Therefore consumers
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    36
   of bzip2 bundles need to *seed* the bzip2 decompressor with ``BZ`` or
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    37
   seek the input stream back to the beginning of the algorithm component
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    38
   of the bundle header so that decompressor input is valid. This behavior
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    39
   is unique among supported compression algorithms.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    40
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    41
   Supported since version 0.7 (released December 2006).
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    42
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    43
``GZ``
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    44
  *zlib* compression.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    45
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    46
   Supported since version 0.9.2 (released December 2006).
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    47
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    48
``UN``
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    49
  *Uncompressed* or no compression. Unmodified changegroup data follows.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    50
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    51
  Supported since version 0.9.2 (released December 2006).
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    52
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    53
3rd party extensions may implement their own compression. However, no
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    54
authority reserves values for their compression algorithm identifiers.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    55
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    56
HG2X
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    57
----
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    58
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    59
``HG2X`` headers (where ``X`` is any value) denote a *bundle2* bundle.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    60
Bundle2 bundles are a container format for various kinds of repository
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    61
data and capabilities, beyond changegroup data (which was the only data
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    62
supported by ``HG10`` bundles.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    63
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    64
``HG20`` is currently the only defined bundle2 version.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    65
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    66
The ``HG20`` format is not yet documented here. See the inline comments
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    67
in ``mercurial/exchange.py`` for now.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    68
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    69
Initial ``HG20`` support was added in Mercurial 3.0 (released May
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    70
2014). However, bundle2 bundles were hidden behind an experimental flag
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    71
until version 3.5 (released August 2015), when they were enabled in the
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    72
wire protocol. Various commands (including ``hg bundle``) did not
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    73
support generating bundle2 files until Mercurial 3.6 (released November
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    74
2015).
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    75
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    76
HGS1
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    77
----
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    78
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    79
*Experimental*
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    80
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    81
A ``HGS1`` header indicates a *streaming clone bundle*. This is a bundle
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    82
that contains raw revlog data from a repository store. (Typically revlog
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    83
data is exchanged in the form of changegroups.)
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    84
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    85
The purpose of *streaming clone bundles* are to *clone* repository data
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    86
very efficiently.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    87
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    88
The ``HGS1`` header is always followed by 2 bytes indicating a
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    89
compression algorithm of the data that follows. Only ``UN``
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    90
(uncompressed data) is currently allowed.
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    91
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    92
``HGS1UN`` support was added as an experimental feature in version 3.6
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    93
(released November 2015) as part of the initial offering of the *clone
84784f834b3a help: add documentation for bundle types
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    94
bundles* feature.