[MERGE] Tutorial updates
Matthew D. Fuller
fullermd at over-yonder.net
Wed May 30 05:03:49 BST 2007
Some talk on IRC tonite suggested some tutorial updates. Some
highlights:
- 'unknowns' probably shouldn't be a command we talk much about. If
it really needs to be there at all (which I don't think it does), it
should be 'ls --unknown' instead.
- 'rm' DOES now (sometimes) delete the file. Try to describe it well
enough without requiring a foldout footnote.
- Emphasize 'push' and 'pull' over other ways of getting/sending
branches and changes, especially methods like manual rsync.
--
Matthew Fuller (MF4839) | fullermd at over-yonder.net
Systems/Network Administrator | http://www.over-yonder.net/~fullermd/
On the Internet, nobody can hear you scream.
-------------- next part --------------
# Bazaar revision bundle v0.9
#
# message:
# Bump document version from 0.8 to 0.16.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:55:12.417000055 -0500
=== modified file doc/tutorial.txt
--- doc/tutorial.txt
+++ doc/tutorial.txt
@@ -11,7 +11,7 @@
Bazaar Tutorial
===============
-Current for bzr-0.8, 2006-04
+Current for bzr-0.16, 2007-05
Introduction
@@ -180,15 +180,21 @@
% bzr status
unknown:
hello.txt
- % bzr unknowns
- hello.txt
% bzr add hello.txt
added hello.txt
- % bzr unknowns
+ % bzr status
+ added:
+ hello.txt
If you add the wrong file, simply use **bzr remove** to make it
-unversioned again. This does not delete the working copy.
+unversioned again. This does not delete the working copy in this case,
+though it may in others [2]_.
+
+.. [2] ``bzr remove`` will remove the working copy if it is currently
+ versioned, but has no changes from the last committed version. You
+ can force the file to always be kept with the ``--keep`` option to
+ ``bzr remove``, or force it to always be deleted with ``--force``.
Branch locations
================
@@ -210,6 +216,9 @@
By installing bzr plugins you can also access branches using the rsync
protocol.
+See the `Publishing your branch`_ section for more about how to put your
+branch at a given location.
+
Reviewing changes
=================
@@ -246,10 +255,10 @@
''patch'', ''diffstat'', ''filterdiff'' and ''colordiff''::
% bzr diff
- *** added file 'hello.txt'
- --- /dev/null
- +++ hello.txt
- @@ -1,0 +1,1 @@
+ === added file 'hello.txt'
+ --- hello.txt 1970-01-01 00:00:00 +0000
+ +++ hello.txt 2005-10-18 14:23:29 +0000
+ @@ -0,0 +1,1 @@
+hello world
@@ -432,9 +441,9 @@
directory. This is a bit different to CVS, which requires that you also
do **cvs remove**.
- **bzr remove** makes the file un-versioned, but does not delete
- the working copy. This is useful when you add the wrong file, or decide
- that a file should actually not be versioned.
+ **bzr remove** makes the file un-versioned, but may or may not delete
+ the working copy [2]_. This is useful when you add the wrong file,
+ or decide that a file should actually not be versioned.
::
@@ -457,10 +466,9 @@
=========
Often rather than starting your own project, you will want to submit a
-change to an existing project. You can get a copy of an existing branch
-by copying its directory, expanding a tarball, or by a remote copy using
-something like rsync. You can also use bzr to fetch a copy. Because this
-new copy is potentially a new branch, the command is called *branch*::
+change to an existing project. To do this, you'll need to get a copy of
+the existing branch. Because this new copy is potentially a new branch,
+the command is called **branch**::
% bzr branch http://bazaar-vcs.org/bzr/bzr.dev
% cd bzr.dev
@@ -469,6 +477,9 @@
operations on it locally: log, annotate, making and merging branches.
There will be an option to get only part of the history if you wish.
+You can also get a copy of an existing branch by copying its directory,
+expanding a tarball, or by a remote copy using something like rsync.
+
Following upstream changes
==========================
@@ -528,17 +539,23 @@
directory. One can push a branch (or the changes for a branch) by one of
the following three methods:
-* Rsync: rsync -avrz LOCALBRANCH servername.com/path/to/directory
-
- (or any other tool for publishing a directory to a web site.)
-
-* bzr push sftp://servername.com/path/to/directory
+* The best method is to use bzr itself to do it.
+
+ ::
+
+ % bzr push sftp://servername.com/path/to/directory
(The destination directory must already exist unless the
``--create-prefix`` option is used.)
-* The rspush plugin that comes with BzrTools
+* Another option is the rspush plugin that comes with BzrTools, which
+ uses rsync to push the changes to the revision history and the working
+ tree.
+You can also use copy the files around manually, by sending a tarball, or
+using rsync, or other related file transfer methods. This is usually
+less safe than using ``push``, but may be faster or easier in some
+situations.
Moving changes between trees
============================
=== modified directory // last-changed:fullermd at over-yonder.net-20070530035512
... -5wygby6ekqi9uxc2
# revision id: fullermd at over-yonder.net-20070530035512-5wygby6ekqi9uxc2
# sha1: c6573467ce47e128f792b375d79deed0e7a196e3
# inventory sha1: 907e92983d9c913d739dbcf80a1d939d50826488
# parent ids:
# fullermd at over-yonder.net-20070530035408-mpzp6fj1cp3k4c70
# base id: pqm at pqm.ubuntu.com-20070525050023-ip6kst9coq8a32z5
# properties:
# branch-nick: tutorial-updates
# message:
# De-emphasize the heck out of manually rsync'ing for 'push', and
# emphasize the builtin 'push'.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:54:08.752000093 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTUzOSwxNyArNTM5
LDIzIEBACiBkaXJlY3RvcnkuICBPbmUgY2FuIHB1c2ggYSBicmFuY2ggKG9yIHRoZSBjaGFuZ2Vz
IGZvciBhIGJyYW5jaCkgYnkgb25lIG9mCiB0aGUgZm9sbG93aW5nIHRocmVlIG1ldGhvZHM6CiAK
LSogUnN5bmM6ICAgcnN5bmMgLWF2cnogTE9DQUxCUkFOQ0ggIHNlcnZlcm5hbWUuY29tL3BhdGgv
dG8vZGlyZWN0b3J5Ci0KLSAgKG9yIGFueSBvdGhlciB0b29sIGZvciBwdWJsaXNoaW5nIGEgZGly
ZWN0b3J5IHRvIGEgd2ViIHNpdGUuKQotCi0qIGJ6ciBwdXNoIHNmdHA6Ly9zZXJ2ZXJuYW1lLmNv
bS9wYXRoL3RvL2RpcmVjdG9yeSAKKyogVGhlIGJlc3QgbWV0aG9kIGlzIHRvIHVzZSBienIgaXRz
ZWxmIHRvIGRvIGl0LgorCisgIDo6CisKKyAgICAlIGJ6ciBwdXNoIHNmdHA6Ly9zZXJ2ZXJuYW1l
LmNvbS9wYXRoL3RvL2RpcmVjdG9yeSAKIAogICAoVGhlIGRlc3RpbmF0aW9uIGRpcmVjdG9yeSBt
dXN0IGFscmVhZHkgZXhpc3QgdW5sZXNzIHRoZQogICBgYC0tY3JlYXRlLXByZWZpeGBgIG9wdGlv
biBpcyB1c2VkLikKIAotKiBUaGUgcnNwdXNoIHBsdWdpbiB0aGF0IGNvbWVzIHdpdGggQnpyVG9v
bHMKKyogQW5vdGhlciBvcHRpb24gaXMgdGhlIHJzcHVzaCBwbHVnaW4gdGhhdCBjb21lcyB3aXRo
IEJ6clRvb2xzLCB3aGljaAorICB1c2VzIHJzeW5jIHRvIHB1c2ggdGhlIGNoYW5nZXMgdG8gdGhl
IHJldmlzaW9uIGhpc3RvcnkgYW5kIHRoZSB3b3JraW5nCisgIHRyZWUuCiAKK1lvdSBjYW4gYWxz
byB1c2UgY29weSB0aGUgZmlsZXMgYXJvdW5kIG1hbnVhbGx5LCBieSBzZW5kaW5nIGEgdGFyYmFs
bCwgb3IKK3VzaW5nIHJzeW5jLCBvciBvdGhlciByZWxhdGVkIGZpbGUgdHJhbnNmZXIgbWV0aG9k
cy4gIFRoaXMgaXMgdXN1YWxseQorbGVzcyBzYWZlIHRoYW4gdXNpbmcgYGBwdXNoYGAsIGJ1dCBt
YXkgYmUgZmFzdGVyIG9yIGVhc2llciBpbiBzb21lCitzaXR1YXRpb25zLgogCiBNb3ZpbmcgY2hh
bmdlcyBiZXR3ZWVuIHRyZWVzIAogPT09PT09PT09PT09PT09PT09PT09PT09PT09PQoK
=== modified directory // last-changed:fullermd at over-yonder.net-20070530035408
... -mpzp6fj1cp3k4c70
# revision id: fullermd at over-yonder.net-20070530035408-mpzp6fj1cp3k4c70
# sha1: 882da1a9748de00585afa61de91d5e5311edfff8
# inventory sha1: ec9a751fb4e4e988a3e5c7ee1a3cfea40b546d89
# parent ids:
# fullermd at over-yonder.net-20070530034609-o0yzwdqtu8fpj468
# properties:
# branch-nick: tutorial-updates
# message:
# Reorganize some text to emphasize 'bzr branch' over grabbing a tarball
# or rsync'ing.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:46:09.920000076 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTQ2NiwxMCArNDY2
LDkgQEAKID09PT09PT09PQogCiBPZnRlbiByYXRoZXIgdGhhbiBzdGFydGluZyB5b3VyIG93biBw
cm9qZWN0LCB5b3Ugd2lsbCB3YW50IHRvIHN1Ym1pdCBhCi1jaGFuZ2UgdG8gYW4gZXhpc3Rpbmcg
cHJvamVjdC4gIFlvdSBjYW4gZ2V0IGEgY29weSBvZiBhbiBleGlzdGluZyBicmFuY2gKLWJ5IGNv
cHlpbmcgaXRzIGRpcmVjdG9yeSwgZXhwYW5kaW5nIGEgdGFyYmFsbCwgb3IgYnkgYSByZW1vdGUg
Y29weSB1c2luZwotc29tZXRoaW5nIGxpa2UgcnN5bmMuICBZb3UgY2FuIGFsc28gdXNlIGJ6ciB0
byBmZXRjaCBhIGNvcHkuICBCZWNhdXNlIHRoaXMKLW5ldyBjb3B5IGlzIHBvdGVudGlhbGx5IGEg
bmV3IGJyYW5jaCwgdGhlIGNvbW1hbmQgaXMgY2FsbGVkICpicmFuY2gqOjoKK2NoYW5nZSB0byBh
biBleGlzdGluZyBwcm9qZWN0LiAgVG8gZG8gdGhpcywgeW91J2xsIG5lZWQgdG8gZ2V0IGEgY29w
eSBvZgordGhlIGV4aXN0aW5nIGJyYW5jaC4gIEJlY2F1c2UgdGhpcyBuZXcgY29weSBpcyBwb3Rl
bnRpYWxseSBhIG5ldyBicmFuY2gsCit0aGUgY29tbWFuZCBpcyBjYWxsZWQgKipicmFuY2gqKjo6
CiAKICAgICAlIGJ6ciBicmFuY2ggaHR0cDovL2JhemFhci12Y3Mub3JnL2J6ci9ienIuZGV2IAog
ICAgICUgY2QgYnpyLmRldgpAQCAtNDc4LDYgKzQ3Nyw5IEBACiBvcGVyYXRpb25zIG9uIGl0IGxv
Y2FsbHk6IGxvZywgYW5ub3RhdGUsIG1ha2luZyBhbmQgbWVyZ2luZyBicmFuY2hlcy4KIFRoZXJl
IHdpbGwgYmUgYW4gb3B0aW9uIHRvIGdldCBvbmx5IHBhcnQgb2YgdGhlIGhpc3RvcnkgaWYgeW91
IHdpc2guCiAKK1lvdSBjYW4gYWxzbyBnZXQgYSBjb3B5IG9mIGFuIGV4aXN0aW5nIGJyYW5jaCBi
eSBjb3B5aW5nIGl0cyBkaXJlY3RvcnksCitleHBhbmRpbmcgYSB0YXJiYWxsLCBvciBieSBhIHJl
bW90ZSBjb3B5IHVzaW5nIHNvbWV0aGluZyBsaWtlIHJzeW5jLgorCiBGb2xsb3dpbmcgdXBzdHJl
YW0gY2hhbmdlcwogPT09PT09PT09PT09PT09PT09PT09PT09PT0KIAoK
=== modified directory // last-changed:fullermd at over-yonder.net-20070530034609
... -o0yzwdqtu8fpj468
# revision id: fullermd at over-yonder.net-20070530034609-o0yzwdqtu8fpj468
# sha1: b3eb1d101c0b5dda15c1efd8024fa1f9ff25a7fa
# inventory sha1: 0c98e472fd8582d4c9941b7686bde16298aa517c
# parent ids:
# fullermd at over-yonder.net-20070530034330-iog9fm92mph4zyy9
# properties:
# branch-nick: tutorial-updates
# message:
# Another place where we need to clarify that 'rm' may or may not delete
# the file.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:43:30.901999950 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTQ0MSw5ICs0NDEs
OSBAQAogZGlyZWN0b3J5LiAgVGhpcyBpcyBhIGJpdCBkaWZmZXJlbnQgdG8gQ1ZTLCB3aGljaCBy
ZXF1aXJlcyB0aGF0IHlvdSBhbHNvCiBkbyAqKmN2cyByZW1vdmUqKi4KIAotICAgICoqYnpyIHJl
bW92ZSoqIG1ha2VzIHRoZSBmaWxlIHVuLXZlcnNpb25lZCwgYnV0IGRvZXMgbm90IGRlbGV0ZQot
ICAgIHRoZSB3b3JraW5nIGNvcHkuICBUaGlzIGlzIHVzZWZ1bCB3aGVuIHlvdSBhZGQgdGhlIHdy
b25nIGZpbGUsIG9yIGRlY2lkZQotICAgIHRoYXQgYSBmaWxlIHNob3VsZCBhY3R1YWxseSBub3Qg
YmUgdmVyc2lvbmVkLiAKKyAgICAqKmJ6ciByZW1vdmUqKiBtYWtlcyB0aGUgZmlsZSB1bi12ZXJz
aW9uZWQsIGJ1dCBtYXkgb3IgbWF5IG5vdCBkZWxldGUKKyAgICB0aGUgd29ya2luZyBjb3B5IFsy
XV8uICBUaGlzIGlzIHVzZWZ1bCB3aGVuIHlvdSBhZGQgdGhlIHdyb25nIGZpbGUsCisgICAgb3Ig
ZGVjaWRlIHRoYXQgYSBmaWxlIHNob3VsZCBhY3R1YWxseSBub3QgYmUgdmVyc2lvbmVkLiAKIAog
OjoKIAoK
=== modified directory // last-changed:fullermd at over-yonder.net-20070530034330
... -iog9fm92mph4zyy9
# revision id: fullermd at over-yonder.net-20070530034330-iog9fm92mph4zyy9
# sha1: ebdaddc2a2e94884656a19e19af69f4f3c13cd10
# inventory sha1: c314c0287bf9c2b59cf0da0c2428fb79b434f31c
# parent ids:
# fullermd at over-yonder.net-20070530033244-r70yfpy0rbswxnt9
# properties:
# branch-nick: tutorial-updates
# message:
# Adjust diff output to look like diff output looks.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:32:44.045000076 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTI1NSwxMCArMjU1
LDEwIEBACiAnJ3BhdGNoJycsICcnZGlmZnN0YXQnJywgJydmaWx0ZXJkaWZmJycgYW5kICcnY29s
b3JkaWZmJyc6OgogCiAgICAgJSBienIgZGlmZgotICAgICoqKiBhZGRlZCBmaWxlICdoZWxsby50
eHQnCi0gICAgLS0tIC9kZXYvbnVsbCAKLSAgICArKysgaGVsbG8udHh0IAotICAgIEBAIC0xLDAg
KzEsMSBAQAorICAgID09PSBhZGRlZCBmaWxlICdoZWxsby50eHQnCisgICAgLS0tIGhlbGxvLnR4
dCAgIDE5NzAtMDEtMDEgMDA6MDA6MDAgKzAwMDAKKyAgICArKysgaGVsbG8udHh0ICAgMjAwNS0x
MC0xOCAxNDoyMzoyOSArMDAwMAorICAgIEBAIC0wLDAgKzEsMSBAQAogICAgICtoZWxsbyB3b3Js
ZAogCiAKCg==
=== modified directory // last-changed:fullermd at over-yonder.net-20070530033244
... -r70yfpy0rbswxnt9
# revision id: fullermd at over-yonder.net-20070530033244-r70yfpy0rbswxnt9
# sha1: cab13ac02857d11a47626e86a074de67cf7c5482
# inventory sha1: 8a9d180c247618026ed632952dea217c26823dae
# parent ids:
# fullermd at over-yonder.net-20070530032834-bp98yu8tjheuvdpy
# properties:
# branch-nick: tutorial-updates
# message:
# X-ref "Publishing your branch" section from the discussion of branch
# locations. A question was posed on IRC suggesting a need for this.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:28:34.635999918 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTIxNiw2ICsyMTYs
OSBAQAogQnkgaW5zdGFsbGluZyBienIgcGx1Z2lucyB5b3UgY2FuIGFsc28gYWNjZXNzIGJyYW5j
aGVzIHVzaW5nIHRoZSByc3luYwogcHJvdG9jb2wuCiAKK1NlZSB0aGUgYFB1Ymxpc2hpbmcgeW91
ciBicmFuY2hgXyBzZWN0aW9uIGZvciBtb3JlIGFib3V0IGhvdyB0byBwdXQgeW91cgorYnJhbmNo
IGF0IGEgZ2l2ZW4gbG9jYXRpb24uCisKIFJldmlld2luZyBjaGFuZ2VzCiA9PT09PT09PT09PT09
PT09PQogCgo=
=== modified directory // last-changed:fullermd at over-yonder.net-20070530032834
... -bp98yu8tjheuvdpy
# revision id: fullermd at over-yonder.net-20070530032834-bp98yu8tjheuvdpy
# sha1: 7b64b33f1e059753dd7c68eebf910f8f10614a10
# inventory sha1: adc123296ee9029684d51c44f060fd3a4069c672
# parent ids:
# fullermd at over-yonder.net-20070530032249-tww05uv09iomg7sw
# properties:
# branch-nick: tutorial-updates
# message:
# rm does sometimes remove the file now. Try and make that a little
# more correct, without being hopelessly complicated.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:22:49.315999985 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTE4OCw3ICsxODgs
MTMgQEAKIAogCiBJZiB5b3UgYWRkIHRoZSB3cm9uZyBmaWxlLCBzaW1wbHkgdXNlICoqYnpyIHJl
bW92ZSoqIHRvIG1ha2UgaXQKLXVudmVyc2lvbmVkIGFnYWluLiAgVGhpcyBkb2VzIG5vdCBkZWxl
dGUgdGhlIHdvcmtpbmcgY29weS4KK3VudmVyc2lvbmVkIGFnYWluLiAgVGhpcyBkb2VzIG5vdCBk
ZWxldGUgdGhlIHdvcmtpbmcgY29weSBpbiB0aGlzIGNhc2UsCit0aG91Z2ggaXQgbWF5IGluIG90
aGVycyBbMl1fLgorCisuLiBbMl0gYGBienIgcmVtb3ZlYGAgd2lsbCByZW1vdmUgdGhlIHdvcmtp
bmcgY29weSBpZiBpdCBpcyBjdXJyZW50bHkKKyAgIHZlcnNpb25lZCwgYnV0IGhhcyBubyBjaGFu
Z2VzIGZyb20gdGhlIGxhc3QgY29tbWl0dGVkIHZlcnNpb24uICBZb3UKKyAgIGNhbiBmb3JjZSB0
aGUgZmlsZSB0byBhbHdheXMgYmUga2VwdCB3aXRoIHRoZSBgYC0ta2VlcGBgIG9wdGlvbiB0bwor
ICAgYGBienIgcmVtb3ZlYGAsIG9yIGZvcmNlIGl0IHRvIGFsd2F5cyBiZSBkZWxldGVkIHdpdGgg
YGAtLWZvcmNlYGAuCiAKIEJyYW5jaCBsb2NhdGlvbnMKID09PT09PT09PT09PT09PT0KCg==
=== modified directory // last-changed:fullermd at over-yonder.net-20070530032249
... -tww05uv09iomg7sw
# revision id: fullermd at over-yonder.net-20070530032249-tww05uv09iomg7sw
# sha1: 6e9cddb7f6e11b9419e92cc0b21fe239f1a512ae
# inventory sha1: d1fea891704fcdba4a723711095a34cdf3d68965
# parent ids:
# fullermd at over-yonder.net-20070530031550-fipr8tf74ni89fyg
# properties:
# branch-nick: tutorial-updates
# message:
# Get rid of references to 'bzr unknowns'.
#
# committer: Matthew Fuller <fullermd at over-yonder.net>
# date: Tue 2007-05-29 22:15:50.632999897 -0500
=== modified file doc/tutorial.txt // encoding:base64
LS0tIGRvYy90dXRvcmlhbC50eHQKKysrIGRvYy90dXRvcmlhbC50eHQKQEAgLTE4MCwxMSArMTgw
LDExIEBACiAgICAgJSBienIgc3RhdHVzCiAgICAgdW5rbm93bjoKICAgICAgIGhlbGxvLnR4dAot
ICAgICUgYnpyIHVua25vd25zCi0gICAgaGVsbG8udHh0CiAgICAgJSBienIgYWRkIGhlbGxvLnR4
dAogICAgIGFkZGVkIGhlbGxvLnR4dAotICAgICUgYnpyIHVua25vd25zCisgICAgJSBienIgc3Rh
dHVzCisgICAgYWRkZWQ6CisgICAgICBoZWxsby50eHQKIAogCiBJZiB5b3UgYWRkIHRoZSB3cm9u
ZyBmaWxlLCBzaW1wbHkgdXNlICoqYnpyIHJlbW92ZSoqIHRvIG1ha2UgaXQKCg==
=== modified directory // last-changed:fullermd at over-yonder.net-20070530031550
... -fipr8tf74ni89fyg
# revision id: fullermd at over-yonder.net-20070530031550-fipr8tf74ni89fyg
# sha1: 1e7a4a21fd3ea77979738ed65933b1216fbc418f
# inventory sha1: d30a9d6aae65c8f6c7f3564e52b80600bacc48c9
# parent ids:
# pqm at pqm.ubuntu.com-20070525050023-ip6kst9coq8a32z5
# properties:
# branch-nick: tutorial-updates
More information about the bazaar
mailing list