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

mercurial/commands.py

@@ -1294,7 +1294,10 b' def cat(ui, repo, file1, *pats, **opts):'
     ('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 b' def clone(ui, source, dest=None, **opts)'
     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 b' def clone(ui, source, dest=None, **opts)'
 
           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 b' def clone(ui, source, dest=None, **opts)'
 
     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'),

mercurial/help/internals/wireprotocol.txt

@@ -394,7 +394,7 b' stream-preferred'
 ----------------
 
 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).

tests/test-clone-uncompressed.t

@@ -18,7 +18,16 b' the status call is to check for issue513'
 
 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 b' Basic clone'
 
 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 b' Clone with background file closing enabl'
 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 b' Streaming of secrets can be overridden b'
   $ 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 b' Clone not allowed when full bundles disa'
   $ 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 b' Local stream clone with secrets involved'
 (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 b' prepare repo with small and big file to '
 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

tests/test-clonebundles.t

@@ -432,7 +432,7 b' Test where attribute is missing from som'
   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 b' A manifest with just a gzip bundle'
   > 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 b' A manifest with a stream clone but no BU'
   > 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 b' A manifest with a gzip bundle and a stre'
   > 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 b' A manifest with a gzip bundle and stream'
   > 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 b' A manifest with a gzip bundle and a stre'
   > 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

tests/test-completion.t

@@ -219,7 +219,7 b' Show all commands + options'
   $ 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

tests/test-http-bundle1.t

@@ -40,7 +40,7 b' Test server address cannot be reused'
 
 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 b' clone via stream'
 
 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 b' try to clone via stream but missing requ'
   >     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 b' disable pull-based clones'
 
 ... 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)

tests/test-http-proxy.t

@@ -14,7 +14,7 b''
 
 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)

tests/test-http.t

@@ -31,7 +31,7 b' Test server address cannot be reused'
 
 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 b' clone via stream'
 
 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 b' try to clone via stream but missing requ'
   >     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 b' disable pull-based clones'
 
 ... 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)

tests/test-ssh-bundle1.t

@@ -58,7 +58,7 b' non-existent absolute path'
 
 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 b' clone remote via stream'
 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)

tests/test-ssh-clone-r.t

@@ -17,7 +17,7 b" creating 'remote' repo"
 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 ..

tests/test-ssh.t

@@ -52,7 +52,7 b' non-existent absolute path'
 
 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 b' clone remote via stream'
 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)

tests/test-treemanifest.t

@@ -756,7 +756,7 b' Local clone with fncachestore'
   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 b' Stream clone with basicstore'
   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 b' Stream clone with encodedstore'
   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)