Rev 3076: User Guide corrections/tweaks from mrevell/jameinel feedback (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Wed Dec 5 00:33:38 GMT 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3076
revision-id:pqm at pqm.ubuntu.com-20071205003329-42n4davel9bplp04
parent: pqm at pqm.ubuntu.com-20071204185324-guhluk76wrccurxj
parent: ian.clatworthy at internode.on.net-20071204235140-f2onw3fslgcryu7f
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Wed 2007-12-05 00:33:29 +0000
message:
User Guide corrections/tweaks from mrevell/jameinel feedback (Ian Clatworthy)
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/merging_changes.txt merging_changes.txt-20071122141511-0knao2lklsdsvb1q-3
doc/en/user-guide/resolving_conflicts.txt resolving_conflicts.-20071122141511-0knao2lklsdsvb1q-5
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/undoing_mistakes.txt undoing_mistakes.txt-20071121092300-8fyacngt1w98e5mp-1
doc/en/user-guide/working_offline_central.txt working_offline_cent-20071123055134-k5x4ekduci2lbn36-5
------------------------------------------------------------
revno: 3075.1.1
revision-id:ian.clatworthy at internode.on.net-20071204235140-f2onw3fslgcryu7f
parent: pqm at pqm.ubuntu.com-20071204185324-guhluk76wrccurxj
parent: ian.clatworthy at internode.on.net-20071204125631-9xnjwum1nbkd1zhp
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: ianc-integration
timestamp: Wed 2007-12-05 09:51:40 +1000
message:
User Guide corrections/tweaks from mrevell/jameinel feedback (Ian Clatworthy)
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/merging_changes.txt merging_changes.txt-20071122141511-0knao2lklsdsvb1q-3
doc/en/user-guide/resolving_conflicts.txt resolving_conflicts.-20071122141511-0knao2lklsdsvb1q-5
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/undoing_mistakes.txt undoing_mistakes.txt-20071121092300-8fyacngt1w98e5mp-1
doc/en/user-guide/working_offline_central.txt working_offline_cent-20071123055134-k5x4ekduci2lbn36-5
------------------------------------------------------------
revno: 3074.1.3
revision-id:ian.clatworthy at internode.on.net-20071204125631-9xnjwum1nbkd1zhp
parent: ian.clatworthy at internode.on.net-20071204123937-aed28ifkryuvpl76
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-tweaks
timestamp: Tue 2007-12-04 22:56:31 +1000
message:
more feedback from jameinel
modified:
doc/en/user-guide/merging_changes.txt merging_changes.txt-20071122141511-0knao2lklsdsvb1q-3
doc/en/user-guide/resolving_conflicts.txt resolving_conflicts.-20071122141511-0knao2lklsdsvb1q-5
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/working_offline_central.txt working_offline_cent-20071123055134-k5x4ekduci2lbn36-5
------------------------------------------------------------
revno: 3074.1.2
revision-id:ian.clatworthy at internode.on.net-20071204123937-aed28ifkryuvpl76
parent: ian.clatworthy at internode.on.net-20071204115138-c2vbuwmnwhl1p4hp
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-tweaks
timestamp: Tue 2007-12-04 22:39:37 +1000
message:
feedback from jameinel
modified:
doc/en/user-guide/undoing_mistakes.txt undoing_mistakes.txt-20071121092300-8fyacngt1w98e5mp-1
------------------------------------------------------------
revno: 3074.1.1
revision-id:ian.clatworthy at internode.on.net-20071204115138-c2vbuwmnwhl1p4hp
parent: pqm at pqm.ubuntu.com-20071204035213-2kot5u403spjchen
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-tweaks
timestamp: Tue 2007-12-04 21:51:38 +1000
message:
feedback from mrevell
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
=== modified file 'doc/en/user-guide/core_concepts.txt'
--- a/doc/en/user-guide/core_concepts.txt 2007-11-30 03:38:22 +0000
+++ b/doc/en/user-guide/core_concepts.txt 2007-12-04 11:51:38 +0000
@@ -4,14 +4,19 @@
A simple user model
-------------------
-The user model on which Bazaar is based has 4 core concepts:
-
- * revisions
- * working trees
- * branches
- * repositories.
-
-These are explained below.
+To use Bazaar you need to understand four core concepts:
+
+ * **revision** - a snapshot of the files you're working with
+
+ * **working tree** - the directory containing your version controlled
+ files and sub-directories
+
+ * **branch** - an ordered set of revisions that describe the history of a
+ set of files
+
+ * **repository** - a store of revisions.
+
+Let's look at each in more detail.
Revision
--------
@@ -54,9 +59,21 @@
The last revision is known as the *head*.
Branches may split apart and be *merged* back together forming a
-so-called *directed acyclic graph* (DAG). The primary line of development
-within the DAG is called the *mainline*, *trunk* or simply the
-*left hand side* (LHS).
+*graph* of revisions. Technically, the graph shows directed relationships
+(between parent and child revisions) and there are no loops, so
+you may hear some people refer to it as a *directed acyclic graph* or DAG.
+
+If this name sound scary, don't worry. The important things
+to remembers are:
+
+* the primary line of development within the DAG is called
+ the *mainline*, *trunk* or simply the *left hand side* (LHS)
+
+* a branch might have other lines of development and if it does,
+ these other lines of development begin at some point and end at
+ another point.
+
+If you understand that, you understand branches.
.. *TODO: add diagram*
=== modified file 'doc/en/user-guide/introducing_bazaar.txt'
--- a/doc/en/user-guide/introducing_bazaar.txt 2007-11-30 04:43:59 +0000
+++ b/doc/en/user-guide/introducing_bazaar.txt 2007-12-04 11:51:38 +0000
@@ -4,23 +4,31 @@
What is Bazaar?
---------------
-Bazaar is a tool for helping people collaborate. It does this by
-tracking how a group of files evolves and using that information to help
-people merge their changes together as safely as possible.
-
-In general, tools that do this are known as revision control systems or
-version control systems (VCS). In the past, VCS tools have been popular
-with software developers. In the future, VCS tools will undoubtedly also be
-important for other groups of people looking to work together on
-files and documents, e.g. technical writers and translators.
+Bazaar is a tool for helping people collaborate. It tracks the changes
+that you and other people make to a group of files - such as software
+source code - to give you snapshots of each stage of their evolution.
+Using that information, Bazaar can effortlessly merge your work with
+other people's.
+
+Tools like Bazaar are called version control systems (VCS) and have
+long been popular with software developers. Bazaar's ease of use,
+flexibility and simple setup make it ideal not only for software
+developers but also for other groups who work together on files and
+documents, such as technical writers, web designers and translators.
+
+This guide takes you through installing Bazaar and how to use it,
+whether on your own or with a team of other people. If you're already
+familiar with distributed version control and want to dive straight in,
+you may wish to skim this section and jump straight to
+`Learning more`_.
A brief history of version control systems
------------------------------------------
-VCS tools have been evolving for several decades now. In simple terms,
-there have been 5 generations of tools:
+Version control tools have been evolving for several decades now. In
+simple terms, there have been 5 generations of tools:
- 1. file versioning tools, e.g. SCCS, VCS
+ 1. file versioning tools, e.g. SCCS, RCS
2. tree versioning tools - central style, e.g. CVS
3. tree versioning tools - central style, done right, e.g. Subversion
4. tree versioning tools - distributed style, e.g. Arch
@@ -40,7 +48,7 @@
users need to connect to the server and *checkout* the files. This gives
them a directory or *working tree* in which a person can make changes.
To record or *commit* these changes, the user needs access to the central
-server and they need to unsure they have merged their work with the latest
+server and they need to ensure they have merged their work with the latest
version stored before trying to commit. This approach is known as the
centralized model.
=== modified file 'doc/en/user-guide/merging_changes.txt'
--- a/doc/en/user-guide/merging_changes.txt 2007-11-27 21:17:06 +0000
+++ b/doc/en/user-guide/merging_changes.txt 2007-12-04 12:56:31 +0000
@@ -42,14 +42,14 @@
works as follows. Given an ancestor A and two branches B and C,
the following table provides the rules used.
- === === === ========================
- A B C Result
- === === === ========================
- x x x x (unchanged)
- x x y y (line from C)
- x y x y (line from B)
- x y z ? (conflict)
- === === === ========================
+ === === === ====== =================
+ A B C Result Comment
+ === === === ====== =================
+ x x x x unchanged
+ x x y y line from C
+ x y x y line from B
+ x y z ? conflict
+ === === === ====== =================
Note that some merges can only be completed with the assistance
of a human. Details on how to resolve these are given in
=== modified file 'doc/en/user-guide/resolving_conflicts.txt'
--- a/doc/en/user-guide/resolving_conflicts.txt 2007-11-22 14:15:37 +0000
+++ b/doc/en/user-guide/resolving_conflicts.txt 2007-12-04 12:56:31 +0000
@@ -58,8 +58,10 @@
bzr remerge --weave foo
where ``foo`` is the file and ``weave`` is one of the available
-merge algorithms. See the online help for ``remerge`` or the
-User Reference for further details.
+merge algorithms. This algorithm is particularly useful when a
+so-called ``criss-cross`` merge is detected, e.g. when two branches
+merge the same thing then merge each other. See the online help for
+``criss-cross`` and ``remerge`` for further details.
Using external tools to resolve conflicts
-----------------------------------------
=== modified file 'doc/en/user-guide/reusing_a_checkout.txt'
--- a/doc/en/user-guide/reusing_a_checkout.txt 2007-11-27 21:17:06 +0000
+++ b/doc/en/user-guide/reusing_a_checkout.txt 2007-12-04 12:56:31 +0000
@@ -34,10 +34,19 @@
3. Make your checkout a copy of the desired branch by using
the ``update`` command followed by the ``revert`` command.
-
Note that simply binding to a new branch
-and running ``update`` is not enough: you need the ``revert`` to
-throw away any local differences in the working tree.
+and running ``update`` merges in your local changes. You need
+to decide whether to keep them or not by running either ``revert``
+or ``commit``.
+
+An alternative to the bind+update recipe is:
+
+ 1. Use the ``unbind`` command to turn the checkout into a normal branch.
+
+ 2. Run ``bzr pull --overwrite URL`` to make the branch a mirror of
+ a new URL.
+
+ 3. Run ``bzr bind URL`` to bind to that URL.
Switching a lightweight checkout
--------------------------------
@@ -59,7 +68,7 @@
(hack away)
Note that X-trunk in this example will have a ``.bzr`` directory within it
-but their will be no working tree there as the branch was created in
+but there will be no working tree there as the branch was created in
a tree-less repository. You can grab or create as many branches as you
need there and switch between them as required. For example::
@@ -75,7 +84,8 @@
refreshes your working tree and merges in any local changes you
have made. The primary different is that ``switch`` requires
a branch location and it is only supported (currently) on
-lightweight checkouts.
+lightweight checkouts. ``switch`` also only preserves
+uncommitted changes while update keeps committed ones.
Note: The branches may be local only or they may be bound to
remote ones (by creating them with ``checkout`` or by using ``bind``
=== modified file 'doc/en/user-guide/undoing_mistakes.txt'
--- a/doc/en/user-guide/undoing_mistakes.txt 2007-11-21 09:23:18 +0000
+++ b/doc/en/user-guide/undoing_mistakes.txt 2007-12-04 12:39:37 +0000
@@ -20,16 +20,25 @@
don't want version controlled, you can use the ``remove``
command to tell Bazaar to forget about it.
-``remove`` has been designed to *Do the Right Thing* in
-that it will leave the file on disk if it hasn't been
-committed yet but delete it otherwise. For example::
+``remove`` has been designed to *Do the Safe Thing* in
+that it will not delete a modified file. For example::
bzr add foo.html
(oops - didn't mean that)
bzr remove foo.html
+
+This will complain about the file being modified or unknown.
+If you want to keep the file, use the ``--keep`` option.
+Alternatively, if you want to remove the file, use the ``--force`` option.
+For example::
+
+ bzr add foo.html
+ (oops - didn't mean that)
+ bzr remove --keep foo.html
(foo.html left on disk)
-On the other hand::
+On the other hand, the ``TODO`` file is deregistered and
+removed from disk without complaint in this example::
bzr add TODO
bzr commit -m "added TODO"
@@ -37,9 +46,6 @@
bzr remove TODO
(TODO file deleted)
-If you want to insist on keeping the file, use the ``--keep`` option.
-If you want to insist on removing the file, use the ``--force`` option.
-
Note: If you delete a file using your file manager, IDE or via an operating
system command, the ``commit`` command will implicitly treat it as removed.
@@ -53,8 +59,9 @@
bzr revert
-As a precaution, it is good practice to use ``bzr diff`` first to
-check that everything being thrown away really ought to be.
+As a precaution, it is good practice to use ``bzr status`` and
+``bzr diff`` first to check that everything being thrown away
+really ought to be.
Undoing changes to a file since the last commit
-----------------------------------------------
@@ -82,10 +89,21 @@
bzr uncommit
bzr commit -m "Fix bug #1"
-Undoing an earlier commit
--------------------------
-
-You can use the -r option to undo several commits like this:
+Another common reason for undoing a commit is because you forgot to add
+one or more files. Some users like to alias ``commit`` to ``commit --strict``
+so that commits fail if unknown files are found in the tree.
+
+Note: While the ``merge`` command is not introduced until the next
+chapter, it is worth noting now that ``uncommit`` restores any pending
+merges. (Running ``bzr status`` after ``uncommit`` will show these.)
+``merge`` can also be used to effectively undo just a selected commit
+earlier in history. For more information on ``merge``, see `Merging changes`_
+in the next chapter and the Bazaar User Reference.
+
+Undoing multiple commits
+------------------------
+
+You can use the -r option to undo several commits like this::
bzr uncommit -r -3
=== modified file 'doc/en/user-guide/working_offline_central.txt'
--- a/doc/en/user-guide/working_offline_central.txt 2007-11-23 07:35:30 +0000
+++ b/doc/en/user-guide/working_offline_central.txt 2007-12-04 12:56:31 +0000
@@ -42,7 +42,7 @@
does the following:
* it brings the latest revisions from the bound branch down and
- makes that the mainline of development without your checkout
+ makes that the mainline of development within your checkout
* it moves your local changes since you last updated into a logical
parallel branch
More information about the bazaar-commits
mailing list