Bazaar

Merge lp:~mbp/bzr/636712-sftp-docs into lp:bzr

  1. 636712-sftp-docs
  2. Merge into bzr.dev
Proposed by Martin Pool
Status: Merged
Approved by: John A Meinel
Approved revision: no longer in the source branch.
Merged at revision: 5769
Proposed branch: lp:~mbp/bzr/636712-sftp-docs
Merge into: lp:bzr
Diff against target: 279 lines (+42/-31)
10 files modified
doc/en/release-notes/bzr-2.4.txt (+5/-0)
doc/en/tutorials/centralized_workflow.txt (+19/-15)
doc/en/tutorials/tutorial.txt (+3/-2)
doc/en/user-guide/branching_a_project.txt (+4/-3)
doc/en/user-guide/merging_changes.txt (+1/-1)
doc/en/user-guide/organizing_branches.txt (+1/-1)
doc/en/user-guide/publishing_a_branch.txt (+4/-4)
doc/en/user-guide/reusing_a_checkout.txt (+2/-2)
doc/en/user-guide/stacked.txt (+1/-1)
doc/en/user-guide/using_checkouts.txt (+2/-2)
To merge this branch: bzr merge lp:~mbp/bzr/636712-sftp-docs
Reviewer Review Type Date Requested Status
John A Meinel Approve
Review via email: mp+56504@code.launchpad.net

Commit message

Recommend SSH rather than SFTP in user documentation examples

Description of the change

For most users, ssh is going to be a better bet than sftp, because it will be faster and avoids sftp-server-specific quirks. sftp is mostly a good choice if for some reason it is hard to install bzr on the server.

So this branch updates the documentation to primarily recommend bzr+ssh.

To post a comment you must log in.
Revision history for this message
John A Meinel (jameinel) wrote :

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 04/06/2011 07:01 AM, Martin Pool wrote:
> Martin Pool has proposed merging lp:~mbp/bzr/636712-sftp-docs into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
> Related bugs:
> Bug #636712 in Bazaar: "docs shouldn't recommend sftp"
> https://bugs.launchpad.net/bzr/+bug/636712
>
> For more details, see:
> https://code.launchpad.net/~mbp/bzr/636712-sftp-docs/+merge/56504
>
> For most users, ssh is going to be a better bet than sftp, because it will be faster and avoids sftp-server-specific quirks. sftp is mostly a good choice if for some reason it is hard to install bzr on the server.
>
> So this branch updates the documentation to primarily recommend bzr+ssh.

I wonder if we want to mention somewhere that you can use "sftp" if bzr
is not installed on the remote machine (with degraded performance,
etc.). Anyway, still worthwhile:

 merge: approve

John
=:->

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2cGDEACgkQJdeBCYSNAAPOxACgnPbQ1VFTVtIMf+0Luo4vKa3A
a+kAnjL/wM9ilGWCaMQmKVlv02I+5d41
=rcgI
-----END PGP SIGNATURE-----

review: Approve
Revision history for this message
Martin Pool (mbp) wrote :

> I wonder if we want to mention somewhere that you can use "sftp" if bzr
> is not installed on the remote machine (with degraded performance,
> etc.).

Yes, we should. I think I mention that in the other branch; I'll check here.

Revision history for this message
Andrew Bennetts (spiv) wrote :

sent to pqm by email

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/en/release-notes/bzr-2.4.txt'
2--- doc/en/release-notes/bzr-2.4.txt 2011-04-06 04:04:54 +0000
3+++ doc/en/release-notes/bzr-2.4.txt 2011-04-06 05:01:28 +0000
4@@ -60,6 +60,11 @@
5 * Added a section about using a shared SSH account on a server for bzr+ssh
6 access. (Russell Smith)
7
8+* The documentation now recommends using SSH rather than SFTP in the
9+ tutorials and the examples, because that will generally be much faster
10+ and better in cases where it can be used. SFTP is still available and
11+ mentioned as an alternative. (Martin Pool, #636712)
12+
13 API Changes
14 ***********
15
16
17=== modified file 'doc/en/tutorials/centralized_workflow.txt'
18--- doc/en/tutorials/centralized_workflow.txt 2010-08-13 19:08:57 +0000
19+++ doc/en/tutorials/centralized_workflow.txt 2011-04-06 05:01:28 +0000
20@@ -80,7 +80,7 @@
21
22 ::
23
24- % bzr init-repo --no-trees sftp://centralhost/srv/bzr/
25+ % bzr init-repo --no-trees bzr+ssh://centralhost/srv/bzr/
26
27 You can think of this step as similar to setting up a new cvsroot, or
28 subversion repository. The ``--no-trees`` option tells bzr to not
29@@ -88,6 +88,10 @@
30 since no one will be making changes directly in the branches within
31 the central repository.
32
33+Here we're using a ``bzr+ssh`` URL, which means to use Bazaar's own
34+protocol on top of the SSH secure shell. See the Administrator Guide for
35+information about setting up a bzr+ssh server.
36+
37
38 Migrating an existing project to Bazaar
39 =======================================
40@@ -116,7 +120,7 @@
41
42 ::
43
44- % bzr init sftp://centralhost/srv/bzr/sigil
45+ % bzr init bzr+ssh://centralhost/srv/bzr/sigil
46
47 This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk"
48 in Subversion terms. We will call this the ``dev`` branch.
49@@ -133,7 +137,7 @@
50 % cd work
51 % mkdir sigil
52 % cd sigil
53- % bzr checkout sftp://centralhost/srv/bzr/sigil dev
54+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil dev
55 % cd dev
56 % cp -ar ~/sigil/* .
57 % bzr add
58@@ -162,10 +166,10 @@
59 To get a copy of the current development tree::
60
61 % cd ~/work/sigil
62- % bzr checkout sftp://centralhost/srv/bzr/sigil dev
63+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil dev
64
65 Now that two people both have a checkout of
66-``sftp://centralhost/srv/bzr/sigil``, there will be times when one of
67+``bzr+ssh://centralhost/srv/bzr/sigil``, there will be times when one of
68 the checkouts will be out of date with the current version.
69 At commit time, Bazaar_ will inform the user of this and prevent them from
70 committing. To get up to date, use ``bzr update`` to update the
71@@ -201,9 +205,9 @@
72 ::
73
74 % cd ~/work/sigil
75- % bzr branch sftp://centralhost/srv/bzr/sigil \
76- sftp://centralhost/srv/bzr/sigil/doodle-fixes
77- % bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
78+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
79+ bzr+ssh://centralhost/srv/bzr/sigil/doodle-fixes
80+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes
81 % cd doodle-fixes
82
83 We now have a place to make any fixes we need to ``doodle``. And we would
84@@ -272,19 +276,19 @@
85 developer their own branch, and their own place to work in the central
86 location. This can be done with::
87
88- % bzr branch sftp://centralhost/srv/bzr/sigil \
89- sftp://centralhost/srv/bzr/sigil/user-a
90- % bzr branch sftp://centralhost/srv/bzr/sigil \
91- sftp://centralhost/srv/bzr/sigil/user-b
92+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
93+ bzr+ssh://centralhost/srv/bzr/sigil/user-a
94+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil \
95+ bzr+ssh://centralhost/srv/bzr/sigil/user-b
96
97 This gives each developer their own branch to work on. And, they can
98 easily create a new feature branch for themselves with just [#cbranch]_
99 ::
100
101- % bzr branch sftp://centralhost/srv/bzr/sigil/user-a \
102- sftp://centralhost/srv/bzr/sigil/user-a/feature
103+ % bzr branch bzr+ssh://centralhost/srv/bzr/sigil/user-a \
104+ bzr+ssh://centralhost/srv/bzr/sigil/user-a/feature
105 % cd ~/work/sigil
106- % bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature
107+ % bzr checkout bzr+ssh://centralhost/srv/bzr/sigil/user-a/feature myfeature
108
109
110 Glossary
111
112=== modified file 'doc/en/tutorials/tutorial.txt'
113--- doc/en/tutorials/tutorial.txt 2010-11-12 22:36:19 +0000
114+++ doc/en/tutorials/tutorial.txt 2011-04-06 05:01:28 +0000
115@@ -209,8 +209,9 @@
116
117 You'll usually refer to branches on your computer's filesystem just by
118 giving the name of the directory containing the branch. bzr also supports
119-accessing branches over HTTP and SFTP, for example::
120+accessing branches over SSH, HTTP and SFTP, amongst other things::
121
122+ % bzr log bzr+ssh://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
123 % bzr log http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
124 % bzr log sftp://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
125
126@@ -608,7 +609,7 @@
127
128 ::
129
130- % bzr push sftp://servername.com/path/to/directory
131+ % bzr push bzr+ssh://servername.com/path/to/directory
132
133 (The destination directory must already exist unless the
134 ``--create-prefix`` option is used.)
135
136=== modified file 'doc/en/user-guide/branching_a_project.txt'
137--- doc/en/user-guide/branching_a_project.txt 2010-11-12 22:36:19 +0000
138+++ doc/en/user-guide/branching_a_project.txt 2011-04-06 05:01:28 +0000
139@@ -9,14 +9,15 @@
140 You may decide to make the top level directory of your branch
141 a network share, an approach familiar to Windows users.
142 Unix users might prefer access to be
143-via SFTP, a secure protocol built-in to most SSH servers.
144+via SSH, a secure protocol built-in to most SSH servers.
145 Bazaar is *very* flexible in this regard with support for
146 lots of protocols some of which are given below.
147
148 =========== ======================================================
149 Prefix Description
150 =========== ======================================================
151- \file:// Access using the standard filesystem (default)
152+ \file:// Access using the standard filesystem (default).
153+ \bzr+ssh:/ Access over SSH (best remote option).
154 \sftp:// Access using SFTP (most SSH servers provide SFTP).
155 \bzr:// Fast access using the Bazaar smart server.
156 \ftp:// Access using passive FTP.
157@@ -39,7 +40,7 @@
158 which directory.)
159
160 To address a path relative to your home directory on the server, use a
161-tilde like so: ``sftp://example.com/~/public_html`` should map to
162+tilde like so: ``bzr+ssh://example.com/~/public_html`` should map to
163 ``public_html`` within your home directory.
164
165 .. note:: Access over HTTP or HTTPS is read-only by default.
166
167=== modified file 'doc/en/user-guide/merging_changes.txt'
168--- doc/en/user-guide/merging_changes.txt 2009-09-09 15:06:00 +0000
169+++ doc/en/user-guide/merging_changes.txt 2011-04-06 05:01:28 +0000
170@@ -29,7 +29,7 @@
171 has done in his. In this case, she needs to explicitly give the URL the
172 first time, e.g.::
173
174- bzr merge sftp://mary@bill-laptop/cool-repo/cool-trunk
175+ bzr merge bzr+ssh://mary@bill-laptop/cool-repo/cool-trunk
176
177 This sets the default merge branch if one is not already set. To change the
178 default after it is set, use the ``--remember`` option.
179
180=== modified file 'doc/en/user-guide/organizing_branches.txt'
181--- doc/en/user-guide/organizing_branches.txt 2009-04-04 02:50:01 +0000
182+++ doc/en/user-guide/organizing_branches.txt 2011-04-06 05:01:28 +0000
183@@ -16,7 +16,7 @@
184
185 bzr init-repo PROJECT
186 cd PROJECT
187- bzr branch sftp://centralhost/srv/bzr/PROJECT/trunk
188+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
189
190 Task branches
191 -------------
192
193=== modified file 'doc/en/user-guide/publishing_a_branch.txt'
194--- doc/en/user-guide/publishing_a_branch.txt 2009-12-02 11:03:35 +0000
195+++ doc/en/user-guide/publishing_a_branch.txt 2011-04-06 05:01:28 +0000
196@@ -14,7 +14,7 @@
197 store history, not working copies of files, so their enclosing
198 repository is usually creating using the ``no-trees`` option, e.g.::
199
200- bzr init-repo --no-trees sftp://centralhost/srv/bzr/PROJECT
201+ bzr init-repo --no-trees bzr+ssh://centralhost/srv/bzr/PROJECT
202
203 You can think of this step as similar to setting up a new cvsroot or
204 Subversion repository. However, Bazaar gives you more flexibility
205@@ -42,14 +42,14 @@
206 bzr add (populate repository; start version control)
207 bzr commit -m "Initial import"
208 (publish to central repository)
209- bzr push sftp://centralhost/srv/bzr/PROJECT/trunk
210+ bzr push bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
211
212 Here is an example of the second way::
213
214 bzr init-repo PROJECT (prepare local repository)
215 cd PROJECT
216- bzr init sftp://centralhost/srv/bzr/PROJECT/trunk
217- bzr checkout sftp://centralhost/srv/bzr/PROJECT/trunk
218+ bzr init bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
219+ bzr checkout bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
220 cd trunk
221 cp -ar ~/PROJECT . (copy files in using OS-specific tools)
222 bzr add (populate repository; start version control)
223
224=== modified file 'doc/en/user-guide/reusing_a_checkout.txt'
225--- doc/en/user-guide/reusing_a_checkout.txt 2008-12-24 03:14:16 +0000
226+++ doc/en/user-guide/reusing_a_checkout.txt 2011-04-06 05:01:28 +0000
227@@ -63,7 +63,7 @@
228
229 bzr init-repo --no-trees PROJECT
230 cd PROJECT
231- bzr branch sftp://centralhost/srv/bzr/PROJECT/trunk
232+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
233 bzr checkout --lightweight trunk my-sandbox
234 cd my-sandbox
235 (hack away)
236@@ -74,7 +74,7 @@
237 need there and switch between them as required. For example::
238
239 (assuming in my-sandbox)
240- bzr branch sftp://centralhost/srv/bzr/PROJECT/PROJECT-1.0 ../PROJECT-1.0
241+ bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/PROJECT-1.0 ../PROJECT-1.0
242 bzr switch ../PROJECT-1.0
243 (fix bug in 1.0)
244 bzr commit -m "blah, blah blah"
245
246=== modified file 'doc/en/user-guide/stacked.txt'
247--- doc/en/user-guide/stacked.txt 2010-03-25 07:34:15 +0000
248+++ doc/en/user-guide/stacked.txt 2011-04-06 05:01:28 +0000
249@@ -78,7 +78,7 @@
250 can be used additionally to inform ``push`` to reference the
251 revisions in ``reference-url``. For example::
252
253- bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
254+ bzr push --stacked-on bzr+ssh://host/project --stacked bzr+ssh://host/user/stacked-branch
255
256 This usage fits the scenario described in the Motivation section.
257
258
259=== modified file 'doc/en/user-guide/using_checkouts.txt'
260--- doc/en/user-guide/using_checkouts.txt 2009-09-09 15:30:59 +0000
261+++ doc/en/user-guide/using_checkouts.txt 2011-04-06 05:01:28 +0000
262@@ -7,7 +7,7 @@
263 If you have a local branch and wish to make it a checkout, use the
264 ``bind`` command like this::
265
266- bzr bind sftp://centralhost/srv/bzr/PROJECT/trunk
267+ bzr bind bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
268
269 This is necessary, for example, after creating a central branch using
270 ``push`` as illustrated in the previous section.
271@@ -56,7 +56,7 @@
272 To get a history-less checkout in Bazaar, use the ``--lightweight``
273 option like this::
274
275- bzr checkout --lightweight sftp://centralhost/srv/bzr/PROJECT/trunk
276+ bzr checkout --lightweight bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
277
278 Of course, many of the benefits of a normal checkout are lost by doing
279 this but that's a tradeoff you can make if and when it makes sense.