commands: rename clone --uncompressed to --stream and document
--uncompressed isn't a very good name and its description in the
help documentation isn't very useful. We refer to this concept as
"stream clones" in a number of places. I think it makes sense to
change the user-facing argument to use the mode --stream. So this
commit does that.
We keep --uncompressed around for backwards compatibility.
While we're here, we overhaul the help docs for streaming clones
to be somewhat useful.
All tests have been updated to reflect the new preferred --stream
argument. A test for backwards compatibility of --uncompressed has
been added.
.. bc::
`hg clone --stream` should now be used instead of --uncompressed.
--uncompressed is marked as deprecated and is an alias for --stream.
There is no schedule for elimination of --uncompressed.
Differential Revision: https://phab.mercurial-scm.org/D864
--- a/mercurial/commands.py Sun Oct 01 10:17:11 2017 +0100
+++ b/mercurial/commands.py Sun Oct 01 11:29:20 2017 +0100
@@ -1294,7 +1294,10 @@
('r', 'rev', [], _('include the specified changeset'), _('REV')),
('b', 'branch', [], _('clone only the specified branch'), _('BRANCH')),
('', 'pull', None, _('use pull protocol to copy metadata')),
- ('', 'uncompressed', None, _('use uncompressed transfer (fast over LAN)')),
+ ('', 'uncompressed', None,
+ _('an alias to --stream (DEPRECATED)')),
+ ('', 'stream', None,
+ _('clone with minimal data processing')),
] + remoteopts,
_('[OPTION]... SOURCE [DEST]'),
norepo=True)
@@ -1325,6 +1328,19 @@
their ancestors. These options (or 'clone src#rev dest') imply
--pull, even for local source repositories.
+ In normal clone mode, the remote normalizes repository data into a common
+ exchange format and the receiving end translates this data into its local
+ storage format. --stream activates a different clone mode that essentially
+ copies repository files from the remote with minimal data processing. This
+ significantly reduces the CPU cost of a clone both remotely and locally.
+ However, it often increases the transferred data size by 30-40%. This can
+ result in substantially faster clones where I/O throughput is plentiful,
+ especially for larger repositories. A side-effect of --stream clones is
+ that storage settings and requirements on the remote are applied locally:
+ a modern client may inherit legacy or inefficient storage used by the
+ remote or a legacy Mercurial client may not be able to clone from a
+ modern Mercurial remote.
+
.. note::
Specifying a tag will include the tagged changeset but not the
@@ -1376,10 +1392,9 @@
hg clone ssh://user@server//home/projects/alpha/
- - do a high-speed clone over a LAN while checking out a
- specified version::
-
- hg clone --uncompressed http://server/repo -u 1.5
+ - do a streaming clone while checking out a specified version::
+
+ hg clone --stream http://server/repo -u 1.5
- create a repository without changesets after a particular revision::
@@ -1399,7 +1414,7 @@
r = hg.clone(ui, opts, source, dest,
pull=opts.get('pull'),
- stream=opts.get('uncompressed'),
+ stream=opts.get('stream') or opts.get('uncompressed'),
rev=opts.get('rev'),
update=opts.get('updaterev') or not opts.get('noupdate'),
branch=opts.get('branch'),
--- a/mercurial/help/internals/wireprotocol.txt Sun Oct 01 10:17:11 2017 +0100
+++ b/mercurial/help/internals/wireprotocol.txt Sun Oct 01 11:29:20 2017 +0100
@@ -394,7 +394,7 @@
----------------
If present the server prefers that clients clone using the streaming clone
-protocol (``hg clone --uncompressed``) rather than the standard
+protocol (``hg clone --stream``) rather than the standard
changegroup/bundle based protocol.
This capability was introduced in Mercurial 2.2 (released May 2012).
--- a/tests/test-clone-uncompressed.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-clone-uncompressed.t Sun Oct 01 11:29:20 2017 +0100
@@ -18,7 +18,16 @@
Basic clone
- $ hg clone --uncompressed -U http://localhost:$HGPORT clone1
+ $ hg clone --stream -U http://localhost:$HGPORT clone1
+ streaming all changes
+ 1027 files to transfer, 96.3 KB of data
+ transferred 96.3 KB in * seconds (*/sec) (glob)
+ searching for changes
+ no changes found
+
+--uncompressed is an alias to --stream
+
+ $ hg clone --uncompressed -U http://localhost:$HGPORT clone1-uncompressed
streaming all changes
1027 files to transfer, 96.3 KB of data
transferred 96.3 KB in * seconds (*/sec) (glob)
@@ -27,7 +36,7 @@
Clone with background file closing enabled
- $ hg --debug --config worker.backgroundclose=true --config worker.backgroundcloseminfilecount=1 clone --uncompressed -U http://localhost:$HGPORT clone-background | grep -v adding
+ $ hg --debug --config worker.backgroundclose=true --config worker.backgroundcloseminfilecount=1 clone --stream -U http://localhost:$HGPORT clone-background | grep -v adding
using http://localhost:$HGPORT/
sending capabilities command
sending branchmap command
@@ -52,7 +61,7 @@
Cannot stream clone when there are secret changesets
$ hg -R server phase --force --secret -r tip
- $ hg clone --uncompressed -U http://localhost:$HGPORT secret-denied
+ $ hg clone --stream -U http://localhost:$HGPORT secret-denied
warning: stream clone requested but server has them disabled
requesting all changes
adding changesets
@@ -69,7 +78,7 @@
$ cat hg.pid > $DAEMON_PIDS
$ cd ..
- $ hg clone --uncompressed -U http://localhost:$HGPORT secret-allowed
+ $ hg clone --stream -U http://localhost:$HGPORT secret-allowed
streaming all changes
1027 files to transfer, 96.3 KB of data
transferred 96.3 KB in * seconds (*/sec) (glob)
@@ -101,7 +110,7 @@
$ cat hg.pid > $DAEMON_PIDS
$ cd ..
- $ hg clone --uncompressed http://localhost:$HGPORT secret-full-disabled
+ $ hg clone --stream http://localhost:$HGPORT secret-full-disabled
warning: stream clone requested but server has them disabled
requesting all changes
remote: abort: server has pull-based clones disabled
@@ -113,7 +122,7 @@
(This is just a test over behavior: if you have access to the repo's files,
there is no security so it isn't important to prevent a clone here.)
- $ hg clone -U --uncompressed server local-secret
+ $ hg clone -U --stream server local-secret
warning: stream clone requested but server has them disabled
requesting all changes
adding changesets
@@ -151,7 +160,7 @@
clone while modifying the repo between stating file with write lock and
actually serving file content
- $ hg clone -q --uncompressed -U http://localhost:$HGPORT1 clone &
+ $ hg clone -q --stream -U http://localhost:$HGPORT1 clone &
$ sleep 1
$ echo >> repo/f1
$ echo >> repo/f2
--- a/tests/test-clonebundles.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-clonebundles.t Sun Oct 01 11:29:20 2017 +0100
@@ -432,7 +432,7 @@
searching for changes
no changes found
-Test interaction between clone bundles and --uncompressed
+Test interaction between clone bundles and --stream
A manifest with just a gzip bundle
@@ -440,7 +440,7 @@
> http://localhost:$HGPORT1/gz-a.hg BUNDLESPEC=gzip-v2
> EOF
- $ hg clone -U --uncompressed http://localhost:$HGPORT uncompressed-gzip
+ $ hg clone -U --stream http://localhost:$HGPORT uncompressed-gzip
no compatible clone bundles available on server; falling back to regular clone
(you may want to report this to the server operator)
streaming all changes
@@ -455,7 +455,7 @@
> http://localhost:$HGPORT1/packed.hg
> EOF
- $ hg clone -U --uncompressed http://localhost:$HGPORT uncompressed-no-bundlespec
+ $ hg clone -U --stream http://localhost:$HGPORT uncompressed-no-bundlespec
no compatible clone bundles available on server; falling back to regular clone
(you may want to report this to the server operator)
streaming all changes
@@ -471,7 +471,7 @@
> http://localhost:$HGPORT1/packed.hg BUNDLESPEC=none-packed1
> EOF
- $ hg clone -U --uncompressed http://localhost:$HGPORT uncompressed-gzip-packed
+ $ hg clone -U --stream http://localhost:$HGPORT uncompressed-gzip-packed
applying clone bundle from http://localhost:$HGPORT1/packed.hg
4 files to transfer, 613 bytes of data
transferred 613 bytes in * seconds (*) (glob)
@@ -486,7 +486,7 @@
> http://localhost:$HGPORT1/packed.hg BUNDLESPEC=none-packed1;requirements%3Drevlogv1
> EOF
- $ hg clone -U --uncompressed http://localhost:$HGPORT uncompressed-gzip-packed-requirements
+ $ hg clone -U --stream http://localhost:$HGPORT uncompressed-gzip-packed-requirements
applying clone bundle from http://localhost:$HGPORT1/packed.hg
4 files to transfer, 613 bytes of data
transferred 613 bytes in * seconds (*) (glob)
@@ -501,7 +501,7 @@
> http://localhost:$HGPORT1/packed.hg BUNDLESPEC=none-packed1;requirements%3Drevlogv42
> EOF
- $ hg clone -U --uncompressed http://localhost:$HGPORT uncompressed-gzip-packed-unsupported-requirements
+ $ hg clone -U --stream http://localhost:$HGPORT uncompressed-gzip-packed-unsupported-requirements
no compatible clone bundles available on server; falling back to regular clone
(you may want to report this to the server operator)
streaming all changes
--- a/tests/test-completion.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-completion.t Sun Oct 01 11:29:20 2017 +0100
@@ -219,7 +219,7 @@
$ hg debugcommands
add: include, exclude, subrepos, dry-run
annotate: rev, follow, no-follow, text, user, file, date, number, changeset, line-number, skip, ignore-all-space, ignore-space-change, ignore-blank-lines, ignore-space-at-eol, include, exclude, template
- clone: noupdate, updaterev, rev, branch, pull, uncompressed, ssh, remotecmd, insecure
+ clone: noupdate, updaterev, rev, branch, pull, uncompressed, stream, ssh, remotecmd, insecure
commit: addremove, close-branch, amend, secret, edit, interactive, include, exclude, message, logfile, date, user, subrepos
diff: rev, change, text, git, binary, nodates, noprefix, show-function, reverse, ignore-all-space, ignore-space-change, ignore-blank-lines, ignore-space-at-eol, unified, stat, root, include, exclude, subrepos
export: output, switch-parent, rev, text, git, binary, nodates
--- a/tests/test-http-bundle1.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-http-bundle1.t Sun Oct 01 11:29:20 2017 +0100
@@ -40,7 +40,7 @@
clone via stream
- $ hg clone --uncompressed http://localhost:$HGPORT/ copy 2>&1
+ $ hg clone --stream http://localhost:$HGPORT/ copy 2>&1
streaming all changes
6 files to transfer, 606 bytes of data
transferred * bytes in * seconds (*/sec) (glob)
@@ -57,7 +57,7 @@
try to clone via stream, should use pull instead
- $ hg clone --uncompressed http://localhost:$HGPORT1/ copy2
+ $ hg clone --stream http://localhost:$HGPORT1/ copy2
warning: stream clone requested but server has them disabled
requesting all changes
adding changesets
@@ -75,7 +75,7 @@
> localrepo.localrepository.supportedformats.remove('generaldelta')
> EOF
- $ hg clone --config extensions.rsf=$TESTTMP/removesupportedformat.py --uncompressed http://localhost:$HGPORT/ copy3
+ $ hg clone --config extensions.rsf=$TESTTMP/removesupportedformat.py --stream http://localhost:$HGPORT/ copy3
warning: stream clone requested but client is missing requirements: generaldelta
(see https://www.mercurial-scm.org/wiki/MissingRequirement for more information)
requesting all changes
@@ -378,7 +378,7 @@
... but keep stream clones working
- $ hg clone --uncompressed --noupdate http://localhost:$HGPORT1/ test-stream-clone
+ $ hg clone --stream --noupdate http://localhost:$HGPORT1/ test-stream-clone
streaming all changes
* files to transfer, * of data (glob)
transferred * in * seconds (* KB/sec) (glob)
--- a/tests/test-http-proxy.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-http-proxy.t Sun Oct 01 11:29:20 2017 +0100
@@ -14,7 +14,7 @@
url for proxy, stream
- $ http_proxy=http://localhost:$HGPORT1/ hg --config http_proxy.always=True clone --uncompressed http://localhost:$HGPORT/ b
+ $ http_proxy=http://localhost:$HGPORT1/ hg --config http_proxy.always=True clone --stream http://localhost:$HGPORT/ b
streaming all changes
3 files to transfer, 303 bytes of data
transferred * bytes in * seconds (*/sec) (glob)
--- a/tests/test-http.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-http.t Sun Oct 01 11:29:20 2017 +0100
@@ -31,7 +31,7 @@
clone via stream
- $ hg clone --uncompressed http://localhost:$HGPORT/ copy 2>&1
+ $ hg clone --stream http://localhost:$HGPORT/ copy 2>&1
streaming all changes
6 files to transfer, 606 bytes of data
transferred * bytes in * seconds (*/sec) (glob)
@@ -48,7 +48,7 @@
try to clone via stream, should use pull instead
- $ hg clone --uncompressed http://localhost:$HGPORT1/ copy2
+ $ hg clone --stream http://localhost:$HGPORT1/ copy2
warning: stream clone requested but server has them disabled
requesting all changes
adding changesets
@@ -66,7 +66,7 @@
> localrepo.localrepository.supportedformats.remove('generaldelta')
> EOF
- $ hg clone --config extensions.rsf=$TESTTMP/removesupportedformat.py --uncompressed http://localhost:$HGPORT/ copy3
+ $ hg clone --config extensions.rsf=$TESTTMP/removesupportedformat.py --stream http://localhost:$HGPORT/ copy3
warning: stream clone requested but client is missing requirements: generaldelta
(see https://www.mercurial-scm.org/wiki/MissingRequirement for more information)
requesting all changes
@@ -367,7 +367,7 @@
... but keep stream clones working
- $ hg clone --uncompressed --noupdate http://localhost:$HGPORT1/ test-stream-clone
+ $ hg clone --stream --noupdate http://localhost:$HGPORT1/ test-stream-clone
streaming all changes
* files to transfer, * of data (glob)
transferred * in * seconds (*/sec) (glob)
--- a/tests/test-ssh-bundle1.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-ssh-bundle1.t Sun Oct 01 11:29:20 2017 +0100
@@ -58,7 +58,7 @@
clone remote via stream
- $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --uncompressed ssh://user@dummy/remote local-stream
+ $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --stream ssh://user@dummy/remote local-stream
streaming all changes
4 files to transfer, 602 bytes of data
transferred 602 bytes in * seconds (*) (glob)
@@ -80,7 +80,7 @@
clone bookmarks via stream
$ hg -R local-stream book mybook
- $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --uncompressed ssh://user@dummy/local-stream stream2
+ $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --stream ssh://user@dummy/local-stream stream2
streaming all changes
4 files to transfer, 602 bytes of data
transferred 602 bytes in * seconds (*) (glob)
--- a/tests/test-ssh-clone-r.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-ssh-clone-r.t Sun Oct 01 11:29:20 2017 +0100
@@ -17,7 +17,7 @@
clone remote via stream
$ for i in 0 1 2 3 4 5 6 7 8; do
- > hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --uncompressed -r "$i" ssh://user@dummy/remote test-"$i"
+ > hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --stream -r "$i" ssh://user@dummy/remote test-"$i"
> if cd test-"$i"; then
> hg verify
> cd ..
--- a/tests/test-ssh.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-ssh.t Sun Oct 01 11:29:20 2017 +0100
@@ -52,7 +52,7 @@
clone remote via stream
- $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --uncompressed ssh://user@dummy/remote local-stream
+ $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --stream ssh://user@dummy/remote local-stream
streaming all changes
4 files to transfer, 602 bytes of data
transferred 602 bytes in * seconds (*) (glob)
@@ -74,7 +74,7 @@
clone bookmarks via stream
$ hg -R local-stream book mybook
- $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --uncompressed ssh://user@dummy/local-stream stream2
+ $ hg clone -e "\"$PYTHON\" \"$TESTDIR/dummyssh\"" --stream ssh://user@dummy/local-stream stream2
streaming all changes
4 files to transfer, 602 bytes of data
transferred 602 bytes in * seconds (*) (glob)
--- a/tests/test-treemanifest.t Sun Oct 01 10:17:11 2017 +0100
+++ b/tests/test-treemanifest.t Sun Oct 01 11:29:20 2017 +0100
@@ -756,7 +756,7 @@
8 files, 4 changesets, 18 total revisions
Stream clone with basicstore
- $ hg clone --config experimental.changegroup3=True --uncompressed -U \
+ $ hg clone --config experimental.changegroup3=True --stream -U \
> http://localhost:$HGPORT1 stream-clone-basicstore
streaming all changes
18 files to transfer, * of data (glob)
@@ -772,7 +772,7 @@
8 files, 4 changesets, 18 total revisions
Stream clone with encodedstore
- $ hg clone --config experimental.changegroup3=True --uncompressed -U \
+ $ hg clone --config experimental.changegroup3=True --stream -U \
> http://localhost:$HGPORT2 stream-clone-encodedstore
streaming all changes
18 files to transfer, * of data (glob)
@@ -788,7 +788,7 @@
8 files, 4 changesets, 18 total revisions
Stream clone with fncachestore
- $ hg clone --config experimental.changegroup3=True --uncompressed -U \
+ $ hg clone --config experimental.changegroup3=True --stream -U \
> http://localhost:$HGPORT stream-clone-fncachestore
streaming all changes
18 files to transfer, * of data (glob)