Rev 5769: (spiv) Recommend SSH rather than SFTP in user documentation examples (Martin in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Apr 8 09:04:24 UTC 2011
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 5769 [merge]
revision-id: pqm at pqm.ubuntu.com-20110408090417-06s986zz14u67e0d
parent: pqm at pqm.ubuntu.com-20110408072421-81nrdsapywozyyft
parent: mbp at sourcefrog.net-20110406045843-9n5xjc13ndv4u0jd
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2011-04-08 09:04:17 +0000
message:
(spiv) Recommend SSH rather than SFTP in user documentation examples (Martin
Pool)
modified:
doc/en/release-notes/bzr-2.4.txt bzr2.4.txt-20110114053217-k7ym9jfz243fddjm-1
doc/en/tutorials/centralized_workflow.txt centralized_workflow-20060830194948-kspf52565xvgrlil-1
doc/en/tutorials/tutorial.txt tutorial.txt-20050804190939-9dcbba2ef053bc84
doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
doc/en/user-guide/merging_changes.txt merging_changes.txt-20071122141511-0knao2lklsdsvb1q-3
doc/en/user-guide/organizing_branches.txt organizing_branches.-20071123154453-dk2mjhrg1vpjm5w2-3
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/stacked.txt stacked.txt-20080711023247-4uh9oovoka0sze8b-1
doc/en/user-guide/using_checkouts.txt using_checkouts.txt-20071123055134-k5x4ekduci2lbn36-4
=== modified file 'doc/en/release-notes/bzr-2.4.txt'
--- a/doc/en/release-notes/bzr-2.4.txt 2011-04-08 03:31:54 +0000
+++ b/doc/en/release-notes/bzr-2.4.txt 2011-04-08 09:04:17 +0000
@@ -69,6 +69,11 @@
* Added a section about using a shared SSH account on a server for bzr+ssh
access. (Russell Smith)
+* The documentation now recommends using SSH rather than SFTP in the
+ tutorials and the examples, because that will generally be much faster
+ and better in cases where it can be used. SFTP is still available and
+ mentioned as an alternative. (Martin Pool, #636712)
+
API Changes
***********
=== modified file 'doc/en/tutorials/centralized_workflow.txt'
--- a/doc/en/tutorials/centralized_workflow.txt 2010-08-13 19:08:57 +0000
+++ b/doc/en/tutorials/centralized_workflow.txt 2011-04-06 04:58:43 +0000
@@ -80,7 +80,7 @@
::
- % bzr init-repo --no-trees sftp://centralhost/srv/bzr/
+ % bzr init-repo --no-trees bzr+ssh://centralhost/srv/bzr/
You can think of this step as similar to setting up a new cvsroot, or
subversion repository. The ``--no-trees`` option tells bzr to not
@@ -88,6 +88,10 @@
since no one will be making changes directly in the branches within
the central repository.
+Here we're using a ``bzr+ssh`` URL, which means to use Bazaar's own
+protocol on top of the SSH secure shell. See the Administrator Guide for
+information about setting up a bzr+ssh server.
+
Migrating an existing project to Bazaar
=======================================
@@ -116,7 +120,7 @@
::
- % bzr init sftp://centralhost/srv/bzr/sigil
+ % bzr init bzr+ssh://centralhost/srv/bzr/sigil
This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"
in Subversion terms. We will call this the ``dev`` branch.
@@ -133,7 +137,7 @@
% cd work
% mkdir sigil
% cd sigil
- % bzr checkout sftp://centralhost/srv/bzr/sigil dev
+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil dev
% cd dev
% cp -ar ~/sigil/* .
% bzr add
@@ -162,10 +166,10 @@
To get a copy of the current development tree::
% cd ~/work/sigil
- % bzr checkout sftp://centralhost/srv/bzr/sigil dev
+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil dev
Now that two people both have a checkout of
-``sftp://centralhost/srv/bzr/sigil``, there will be times when one of
+``bzr+ssh://centralhost/srv/bzr/sigil``, there will be times when one of
the checkouts will be out of date with the current version.
At commit time, Bazaar_ will inform the user of this and prevent them from
committing. To get up to date, use ``bzr update`` to update the
@@ -201,9 +205,9 @@
::
% cd ~/work/sigil
- % bzr branch sftp://centralhost/srv/bzr/sigil \
- sftp://centralhost/srv/bzr/sigil/doodle-fixes
- % bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
+ bzr+ssh://centralhost/srv/bzr/sigil/doodle-fixes
+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
% cd doodle-fixes
We now have a place to make any fixes we need to ``doodle``. And we would
@@ -272,19 +276,19 @@
developer their own branch, and their own place to work in the central
location. This can be done with::
- % bzr branch sftp://centralhost/srv/bzr/sigil \
- sftp://centralhost/srv/bzr/sigil/user-a
- % bzr branch sftp://centralhost/srv/bzr/sigil \
- sftp://centralhost/srv/bzr/sigil/user-b
+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
+ bzr+ssh://centralhost/srv/bzr/sigil/user-a
+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
+ bzr+ssh://centralhost/srv/bzr/sigil/user-b
This gives each developer their own branch to work on. And, they can
easily create a new feature branch for themselves with just [#cbranch]_
::
- % bzr branch sftp://centralhost/srv/bzr/sigil/user-a \
- sftp://centralhost/srv/bzr/sigil/user-a/feature
+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil/user-a \
+ bzr+ssh://centralhost/srv/bzr/sigil/user-a/feature
% cd ~/work/sigil
- % bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature
+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil/user-a/feature myfeature
Glossary
=== modified file 'doc/en/tutorials/tutorial.txt'
--- a/doc/en/tutorials/tutorial.txt 2010-11-12 22:36:19 +0000
+++ b/doc/en/tutorials/tutorial.txt 2011-04-06 04:58:43 +0000
@@ -209,8 +209,9 @@
You'll usually refer to branches on your computer's filesystem just by
giving the name of the directory containing the branch. bzr also supports
-accessing branches over HTTP and SFTP, for example::
+accessing branches over SSH, HTTP and SFTP, amongst other things::
+ % bzr log bzr+ssh://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
% bzr log http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
% bzr log sftp://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
@@ -608,7 +609,7 @@
::
- % bzr push sftp://servername.com/path/to/directory
+ % bzr push bzr+ssh://servername.com/path/to/directory
(The destination directory must already exist unless the
``--create-prefix`` option is used.)
=== modified file 'doc/en/user-guide/branching_a_project.txt'
--- a/doc/en/user-guide/branching_a_project.txt 2010-11-12 22:36:19 +0000
+++ b/doc/en/user-guide/branching_a_project.txt 2011-04-06 04:58:43 +0000
@@ -9,14 +9,15 @@
You may decide to make the top level directory of your branch
a network share, an approach familiar to Windows users.
Unix users might prefer access to be
-via SFTP, a secure protocol built-in to most SSH servers.
+via SSH, a secure protocol built-in to most SSH servers.
Bazaar is *very* flexible in this regard with support for
lots of protocols some of which are given below.
=========== ======================================================
Prefix Description
=========== ======================================================
- \file:// Access using the standard filesystem (default)
+ \file:// Access using the standard filesystem (default).
+ \bzr+ssh:/ Access over SSH (best remote option).
\sftp:// Access using SFTP (most SSH servers provide SFTP).
\bzr:// Fast access using the Bazaar smart server.
\ftp:// Access using passive FTP.
@@ -39,7 +40,7 @@
which directory.)
To address a path relative to your home directory on the server, use a
-tilde like so: ``sftp://example.com/~/public_html`` should map to
+tilde like so: ``bzr+ssh://example.com/~/public_html`` should map to
``public_html`` within your home directory.
.. note:: Access over HTTP or HTTPS is read-only by default.
=== modified file 'doc/en/user-guide/merging_changes.txt'
--- a/doc/en/user-guide/merging_changes.txt 2009-09-09 15:06:00 +0000
+++ b/doc/en/user-guide/merging_changes.txt 2011-04-06 04:58:43 +0000
@@ -29,7 +29,7 @@
has done in his. In this case, she needs to explicitly give the URL the
first time, e.g.::
- bzr merge sftp://mary@bill-laptop/cool-repo/cool-trunk
+ bzr merge bzr+ssh://mary@bill-laptop/cool-repo/cool-trunk
This sets the default merge branch if one is not already set. To change the
default after it is set, use the ``--remember`` option.
=== modified file 'doc/en/user-guide/organizing_branches.txt'
--- a/doc/en/user-guide/organizing_branches.txt 2009-04-04 02:50:01 +0000
+++ b/doc/en/user-guide/organizing_branches.txt 2011-04-06 04:58:43 +0000
@@ -16,7 +16,7 @@
bzr init-repo PROJECT
cd PROJECT
- bzr branch sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
Task branches
-------------
=== modified file 'doc/en/user-guide/publishing_a_branch.txt'
--- a/doc/en/user-guide/publishing_a_branch.txt 2011-04-01 05:54:24 +0000
+++ b/doc/en/user-guide/publishing_a_branch.txt 2011-04-08 09:04:17 +0000
@@ -16,7 +16,7 @@
store history, not working copies of files, so their enclosing
repository is usually creating using the ``no-trees`` option, e.g.::
- bzr init-repo --no-trees sftp://centralhost/srv/bzr/PROJECT
+ bzr init-repo --no-trees bzr+ssh://centralhost/srv/bzr/PROJECT
You can think of this step as similar to setting up a new cvsroot or
Subversion repository. However, Bazaar gives you more flexibility
@@ -44,14 +44,14 @@
bzr add (populate repository; start version control)
bzr commit -m "Initial import"
(publish to central repository)
- bzr push sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr push bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
Here is an example of the second way::
bzr init-repo PROJECT (prepare local repository)
cd PROJECT
- bzr init sftp://centralhost/srv/bzr/PROJECT/trunk
- bzr checkout sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr init bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
+ bzr checkout bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
cd trunk
cp -ar ~/PROJECT . (copy files in using OS-specific tools)
bzr add (populate repository; start version control)
=== modified file 'doc/en/user-guide/reusing_a_checkout.txt'
--- a/doc/en/user-guide/reusing_a_checkout.txt 2008-12-24 03:14:16 +0000
+++ b/doc/en/user-guide/reusing_a_checkout.txt 2011-04-06 04:58:43 +0000
@@ -63,7 +63,7 @@
bzr init-repo --no-trees PROJECT
cd PROJECT
- bzr branch sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
bzr checkout --lightweight trunk my-sandbox
cd my-sandbox
(hack away)
@@ -74,7 +74,7 @@
need there and switch between them as required. For example::
(assuming in my-sandbox)
- bzr branch sftp://centralhost/srv/bzr/PROJECT/PROJECT-1.0 ../PROJECT-1.0
+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/PROJECT-1.0 ../PROJECT-1.0
bzr switch ../PROJECT-1.0
(fix bug in 1.0)
bzr commit -m "blah, blah blah"
=== modified file 'doc/en/user-guide/stacked.txt'
--- a/doc/en/user-guide/stacked.txt 2010-03-25 07:34:15 +0000
+++ b/doc/en/user-guide/stacked.txt 2011-04-06 04:58:43 +0000
@@ -78,7 +78,7 @@
can be used additionally to inform ``push`` to reference the
revisions in ``reference-url``. For example::
- bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
+ bzr push --stacked-on bzr+ssh://host/project --stacked bzr+ssh://host/user/stacked-branch
This usage fits the scenario described in the Motivation section.
=== modified file 'doc/en/user-guide/using_checkouts.txt'
--- a/doc/en/user-guide/using_checkouts.txt 2009-09-09 15:30:59 +0000
+++ b/doc/en/user-guide/using_checkouts.txt 2011-04-06 04:58:43 +0000
@@ -7,7 +7,7 @@
If you have a local branch and wish to make it a checkout, use the
``bind`` command like this::
- bzr bind sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr bind bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
This is necessary, for example, after creating a central branch using
``push`` as illustrated in the previous section.
@@ -56,7 +56,7 @@
To get a history-less checkout in Bazaar, use the ``--lightweight``
option like this::
- bzr checkout --lightweight sftp://centralhost/srv/bzr/PROJECT/trunk
+ bzr checkout --lightweight bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
Of course, many of the benefits of a normal checkout are lost by doing
this but that's a tradeoff you can make if and when it makes sense.
More information about the bazaar-commits
mailing list