← Back to branch summary

~bzr/ubuntu/lucid/bzr/beta-ppa

« back to all changes in this revision

Viewing changes to doc/en/tutorials/tutorial.txt

  • Committer: Martin Pool
  • Date: 2010-07-02 07:29:40 UTC
  • mfrom: (129.1.7 packaging-karmic)
  • Revision ID: mbp@sourcefrog.net-20100702072940-hpzq5elg8wjve8rh
http://bugs.debian.org/452024
http://bugs.debian.org/464688
http://bugs.debian.org/523595
http://bugs.debian.org/526233
http://bugs.debian.org/537708
http://bugs.debian.org/555336
http://bugs.debian.org/555343
https://launchpad.net/bugs/249452
https://launchpad.net/bugs/385074
* PPA rebuild.
* PPA rebuild for Karmic.
* PPA rebuild for Jaunty.
* PPA rebuild for Hardy.
* From postinst, actually remove the example bash completion scripts.
  (LP: #249452)
* New upstream release.
* New upstream release.
* New upstream release.
* Revert change to Build-depends: Dapper does not have python-central.
  Should be python-support..
* Target ppa..
* Target ppa..
* Target ppa..
* Target ppa..
* New upstream release.
* Switch to dpkg-source 3.0 (quilt) format.
* Bump standards version to 3.8.4.
* Remove embedded copy of python-configobj. Closes: #555336
* Remove embedded copy of python-elementtree. Closes: #555343
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* debian/control: Fix obsolete-relation-form-in-source
  lintian warning. 
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split out docs into bzr-doc package.
* New upstream release.
* Added John Francesco Ferlito to Uploaders.
* Fix install path to quick-reference guide
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again, again.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to path changes.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Bump standards version to 3.8.3.
* Remove unused patch system.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix copy and paste tab error in .install file
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
 + Fixes compatibility with Python 2.4. Closes: #537708
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream version.
* Bump standards version to 3.8.2.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add python-pyrex to build-deps to ensure C extensions are always build.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix API compatibility version. (Closes: #526233)
* New upstream release.
  + Fixes default format for upgrade command. (Closes: #464688)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add missing dependency on zlib development library. (Closes:
  #523595)
* Add zlib build-depends.
* Add zlib build-depends.
* Add zlib build-depends.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Move to section vcs.
* Bump standards version to 3.8.1.
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Recommend ca-certificates. (Closes: #452024)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Update watch file. bazaar now uses launchpad to host its sources.
* Remove patch for inventory root revision copy, applied upstream.
* New upstream release.
* New upstream release.
* New upstream release
* Force removal of files installed in error to /etc/bash_completion.d/
  (LP: #249452)
* New upstream release.
* New upstream release
* New upstream release.
* Bump standards version.
* Include patch for inventory root revision copy, required for bzr-svn.
* New upstream release.
* Remove unused lintian overrides.
* Correct the package version not to be native.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Final 1.5 release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add myself as a co-maintainer.
* Add a Dm-Upload-Allowed: yes header.
* New upstream bugfix release.
* New upstream release.
* Final 1.3 release.
* New upstream release.
* First release candidate of the upcoming 1.3 release.
* Rebuild to fix the problem caused by a build with a broken python-central.
* New upstream release.
* Rebuild for dapper PPA.
* Apply Lamont's patches to fix build-dependencies on dapper.
  (See: https://bugs.launchpad.net/bzr/+bug/189915)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/tutorials/tutorial.txt
 
1
.. This file is in Python ReStructuredText format - it can be formatted
 
2
.. into HTML or text.  In the future we plan to extract the example commands
 
3
.. and automatically test them.
 
4
 
 
5
.. This text was previously on the wiki at
 
6
.. http://bazaar.canonical.com/IntroductionToBzr
 
7
.. but has been moved into the source tree so it can be kept in sync with
 
8
.. the source and possibly automatically checked.
 
9
 
 
10
===============
 
11
Bazaar Tutorial
 
12
===============
 
13
 
 
14
 
 
15
Introduction
 
16
============
 
17
 
 
18
If you are already familiar with decentralized version control, then
 
19
please feel free to skip ahead to "Introducing Yourself to Bazaar". If,
 
20
on the other hand, you are familiar with version control but not
 
21
decentralized version control, then please start at "How DVCS is
 
22
different." Otherwise, get some coffee or tea, get comfortable and get
 
23
ready to catch up.
 
24
 
 
25
The purpose of version control
 
26
==============================
 
27
 
 
28
Odds are that you have worked on some sort of textual data -- the sources
 
29
to a program, web sites or the config files that Unix system
 
30
administrators have to deal with in /etc. The chances are also good that
 
31
you have made some sort of mistake that you deeply regretted. Perhaps you
 
32
deleted the configuration file for your mailserver or perhaps mauled the
 
33
source code for a pet project. Whatever happened, you have just deleted
 
34
important information that you would desperately like to get back. If this
 
35
has ever happened to you, then you are probably ready for Bazaar.
 
36
 
 
37
Version control systems (which I'll henceforth call VCS) such as
 
38
Bazaar give you the ability to track changes for a directory by turning
 
39
it into something slightly more complicated than a directory that we call
 
40
a **branch**. The branch not only stores how the directory looks right
 
41
now, but also how it looked at various points in the past. Then, when you
 
42
do something you wish you hadn't, you can restore the directory to the way
 
43
it looked at some point in the past.
 
44
 
 
45
Version control systems give users the ability to save changes to a
 
46
branch by "committing a **revision**". The revision created is essentially
 
47
a summary of the changes that were made since the last time the tree was
 
48
saved.
 
49
 
 
50
These revisions have other uses as well. For example, one can comment
 
51
revisions to record what the recent set of changes meant by providing an
 
52
optional log message. Real life log messages include things like "Fixed
 
53
the web template to close the table" and "Added sftp suppport. Fixes #595"
 
54
        
 
55
We keep these logs so that if later there is some sort of problem with
 
56
sftp, we can figure out when the problem probably happened.
 
57
 
 
58
How DVCS is different
 
59
=====================
 
60
 
 
61
Many Version Control Systems (VCS) are stored on servers. If one wants to
 
62
work on the code stored within a VCS, then one needs to connect to the
 
63
server and "checkout" the code. Doing so gives one a directory in which a
 
64
person can make changes and then commit. The VCS client then connects to
 
65
the VCS server and stores the changes. This method is known as the
 
66
centralized model.
 
67
 
 
68
The centralized model can have some drawbacks. A centralized VCS requires
 
69
that one is able to connect to the server whenever one wants to do version
 
70
control work. This can be a bit of a problem if your server is on some other
 
71
machine on the internet and you are not. Or, worse yet, you **are** on the
 
72
internet but the server is missing!
 
73
 
 
74
Decentralized Version Control Systems (which I'll call DVCS after this
 
75
point) deal with this problem by keeping branches on the same machine as
 
76
the client. In Bazaar's case, the branch is kept in the same place as
 
77
the code that is being version controlled. This allows the user to save
 
78
his changes (**commit**) whenever he wants -- even if he is offline. The
 
79
user only needs internet access when he wants to access the changes in
 
80
someone else's branch that are somewhere else.
 
81
 
 
82
 
 
83
A common requirement that many people have is the need to keep track of
 
84
the changes for a directory such as file and subdirectory changes.
 
85
Performing this tracking by hand is a awkward process that over time
 
86
becomes unwieldy. That is, until one considers version control tools such
 
87
as Bazaar. These tools automate the process of storing data by creating
 
88
a **revision** of the directory tree whenever the user asks.
 
89
 
 
90
Version control software such as Bazaar can do much more than just
 
91
storage and performing undo.  For example, with Bazaar a developer can
 
92
take the modifications in one branch of software and apply them to a
 
93
related branch -- even if those changes exist in a branch owned by
 
94
somebody else. This allows developers to cooperate without giving
 
95
write access to the repository.
 
96
 
 
97
Bazaar remembers the ''ancestry'' of a revision: the previous revisions
 
98
that it is based upon.  A single revision may have more than one direct
 
99
descendant, each with different changes, representing a divergence in the
 
100
evolution of the tree. By branching, Bazaar allows multiple people to
 
101
cooperate on the evolution of a project, without all needing to work in
 
102
strict lock-step.  Branching can be useful even for a single developer.
 
103
 
 
104
Introducing yourself to Bazaar
 
105
==============================
 
106
 
 
107
Bazaar installs a single new command, **bzr**.  Everything else is a
 
108
subcommand of this.  You can get some help with ``bzr help``. Some arguments
 
109
are grouped in topics: ``bzr help topics`` to see which topics are available.
 
110
 
 
111
One function of a version control system is to keep track of who changed
 
112
what.  In a decentralized system, that requires an identifier for each
 
113
author that is globally unique.  Most people already have one of these: an
 
114
email address. Bazaar is smart enough to automatically generate an email
 
115
address by looking up your username and hostname. If you don't like the
 
116
guess that Bazaar makes, then three options exist:
 
117
 
 
118
1. Set an email address via ``bzr whoami``.  This is the simplest way.
 
119
 
 
120
   To set a global identity, use::
 
121
 
 
122
   % bzr whoami "Your Name <email@example.com>"
 
123
 
 
124
   If you'd like to use a different address for a specific branch, enter
 
125
   the branch folder and use::
 
126
 
 
127
   % bzr whoami --branch "Your Name <email@example.com>"
 
128
 
 
129
#. Setting the email address in the ``~/.bazaar/bazaar.conf`` [1]_ by
 
130
   adding the following lines.  Please note that  ``[DEFAULT]`` is case
 
131
   sensitive::
 
132
 
 
133
       [DEFAULT]
 
134
       email=Your Name <email@isp.com>
 
135
 
 
136
   As above, you can override this settings on a branch by branch basis
 
137
   by creating a branch section in ``~/.bazaar/locations.conf`` and
 
138
   adding the following lines::
 
139
 
 
140
       [/the/path/to/the/branch]
 
141
       email=Your Name <email@isp.com>
 
142
 
 
143
 
 
144
#. Overriding the two previous options by setting the global environment
 
145
   variable ``$BZR_EMAIL`` or ``$EMAIL`` (``$BZR_EMAIL`` will take
 
146
   precedence) to your full email address.
 
147
 
 
148
.. [1] On Windows, the users configuration files can be found in the
 
149
   application data directory. So instead of ``~/.bazaar/branch.conf``
 
150
   the configuration file can be found as:
 
151
   ``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0\branch.conf``.
 
152
   The same is true for ``locations.conf``, ``ignore``, and the
 
153
   ``plugins`` directory.
 
154
 
 
155
Creating a branch
 
156
=================
 
157
 
 
158
History is by default stored in the .bzr directory of the branch. In a
 
159
future version of Bazaar, there will be a facility to store it in a
 
160
separate repository, which may be remote.
 
161
 
 
162
We create a new branch by running ``bzr init`` in an existing directory::
 
163
 
 
164
    % mkdir tutorial
 
165
    % cd tutorial
 
166
    % ls -a
 
167
    ./  ../
 
168
    % pwd
 
169
    /home/mbp/work/bzr.test/tutorial
 
170
    %
 
171
    % bzr init
 
172
    % ls -aF
 
173
    ./  ../  .bzr/
 
174
    %
 
175
 
 
176
As with CVS, there are three classes of file: unknown, ignored, and
 
177
versioned.  The **add** command makes a file versioned: that is, changes
 
178
to it will be recorded by the system::
 
179
 
 
180
    % echo 'hello world' > hello.txt
 
181
    % bzr status
 
182
    unknown:
 
183
      hello.txt
 
184
    % bzr add hello.txt
 
185
    added hello.txt
 
186
    % bzr status
 
187
    added:
 
188
      hello.txt
 
189
 
 
190
 
 
191
If you add the wrong file, simply use ``bzr remove`` to make it
 
192
unversioned again.  This does not delete the working copy in this case,
 
193
though it may in others [2]_.
 
194
 
 
195
.. [2] ``bzr remove`` will remove the working copy if it is currently
 
196
   versioned, but has no changes from the last committed version.  You
 
197
   can force the file to always be kept with the ``--keep`` option to
 
198
   ``bzr remove``, or force it to always be deleted with ``--force``.
 
199
 
 
200
Branch locations
 
201
================
 
202
 
 
203
All history is stored in a branch, which is just an on-disk directory
 
204
containing control files.  By default there is no separate repository or
 
205
database as used in svn or svk. You can choose to create a repository if
 
206
you want to (see the ``bzr init-repo`` command). You may wish to do this
 
207
if you have very large branches, or many branches of a moderately sized
 
208
project.
 
209
 
 
210
You'll usually refer to branches on your computer's filesystem just by
 
211
giving the name of the directory containing the branch.  bzr also supports
 
212
accessing branches over http and sftp, for example::
 
213
 
 
214
    % bzr log http://bazaar-vcs.org/bzr/bzr.dev/
 
215
    % bzr log sftp://bazaar-vcs.org/bzr/bzr.dev/
 
216
 
 
217
By installing bzr plugins you can also access branches using the rsync
 
218
protocol.
 
219
 
 
220
See the `Publishing your branch`_ section for more about how to put your
 
221
branch at a given location.
 
222
 
 
223
Reviewing changes
 
224
=================
 
225
 
 
226
Once you have completed some work, you will want to **commit** it to the
 
227
version history.  It is good to commit fairly often: whenever you get a
 
228
new feature working, fix a bug, or improve some code or documentation.
 
229
It's also a good practice to make sure that the code compiles and passes
 
230
its test suite before committing, to make sure that every revision is a
 
231
known-good state.  You can also review your changes, to make sure you're
 
232
committing what you intend to, and as a chance to rethink your work before
 
233
you permanently record it.
 
234
 
 
235
Two bzr commands are particularly useful here: **status** and **diff**.
 
236
 
 
237
bzr status
 
238
----------
 
239
 
 
240
The **status** command tells you what changes have been made to the
 
241
working directory since the last revision::
 
242
 
 
243
    % bzr status
 
244
    modified:
 
245
       foo
 
246
 
 
247
``bzr status`` hides "boring" files that are either unchanged or ignored.
 
248
The status command can optionally be given the name of some files or
 
249
directories to check.
 
250
 
 
251
bzr diff
 
252
--------
 
253
 
 
254
The **diff** command shows the full text of changes to all files as a
 
255
standard unified diff.  This can be piped through many programs such as
 
256
''patch'', ''diffstat'', ''filterdiff'' and ''colordiff''::
 
257
 
 
258
    % bzr diff
 
259
    === added file 'hello.txt'
 
260
    --- hello.txt   1970-01-01 00:00:00 +0000
 
261
    +++ hello.txt   2005-10-18 14:23:29 +0000
 
262
    @@ -0,0 +1,1 @@
 
263
    +hello world
 
264
 
 
265
 
 
266
With the ``-r`` option, the tree is compared to an earlier revision, or
 
267
the differences between two versions are shown::
 
268
 
 
269
    % bzr diff -r 1000..          # everything since r1000
 
270
    % bzr diff -r 1000..1100      # changes from 1000 to 1100
 
271
 
 
272
The ``--diff-options`` option causes bzr to run the external diff program,
 
273
passing options.  For example::
 
274
 
 
275
    % bzr diff --diff-options --side-by-side foo
 
276
 
 
277
Some projects prefer patches to show a prefix at the start of the path
 
278
for old and new files.  The ``--prefix`` option can be used to provide
 
279
such a prefix.
 
280
As a shortcut, ``bzr diff -p1`` produces a form that works with the
 
281
command ``patch -p1``.
 
282
 
 
283
 
 
284
Committing changes
 
285
==================
 
286
 
 
287
When the working tree state is satisfactory, it can be **committed** to
 
288
the branch, creating a new revision holding a snapshot of that state.
 
289
 
 
290
bzr commit
 
291
----------
 
292
 
 
293
The **commit** command takes a message describing the changes in the
 
294
revision.  It also records your userid, the current time and timezone, and
 
295
the inventory and contents of the tree.  The commit message is specified
 
296
by the ``-m`` or ``--message`` option. You can enter a multi-line commit
 
297
message; in most shells you can enter this just by leaving the quotes open
 
298
at the end of the line.
 
299
 
 
300
::
 
301
 
 
302
    % bzr commit -m "added my first file"
 
303
 
 
304
You can also use the ``-F`` option to take the message from a file.  Some
 
305
people like to make notes for a commit message while they work, then
 
306
review the diff to make sure they did what they said they did.  (This file
 
307
can also be useful when you pick up your work after a break.)
 
308
 
 
309
Message from an editor
 
310
----------------------
 
311
 
 
312
If you use neither the ``-m`` nor the ``-F`` option then bzr will open an
 
313
editor for you to enter a message.  The editor to run is controlled by
 
314
your ``$VISUAL`` or ``$EDITOR`` environment variable, which can be overridden
 
315
by the ``editor`` setting in ``~/.bazaar/bazaar.conf``; ``$BZR_EDITOR`` will
 
316
override either of the above mentioned editor options.  If you quit the
 
317
editor without making any changes, the commit will be cancelled.
 
318
 
 
319
The file that is opened in the editor contains a horizontal line. The part
 
320
of the file below this line is included for information only, and will not
 
321
form part of the commit message. Below the separator is shown the list of
 
322
files that are changed in the commit. You should write your message above
 
323
the line, and then save the file and exit.
 
324
 
 
325
If you would like to see the diff that will be committed as you edit the
 
326
message you can use the ``--show-diff`` option to ``commit``. This will include
 
327
the diff in the editor when it is opened, below the separator and the
 
328
information about the files that will be committed. This means that you can
 
329
read it as you write the message, but the diff itself wont be seen in the
 
330
commit message when you have finished. If you would like parts to be
 
331
included in the message you can copy and paste them above the separator.
 
332
 
 
333
Marking bugs as fixed
 
334
---------------------
 
335
 
 
336
Many changes to a project are as a result of fixing bugs. Bazaar can keep
 
337
metadata about bugs you fixed when you commit them. To do this you use the
 
338
``--fixes`` option. This option takes an argument that looks like this::
 
339
 
 
340
    % bzr commit --fixes <tracker>:<id>
 
341
 
 
342
Where ``<tracker>`` is an identifier for a bug tracker and ``<id>`` is an
 
343
identifier for a bug that is tracked in that bug tracker. ``<id>`` is usually
 
344
a number. Bazaar already knows about a few popular bug trackers. They are 
 
345
bugs.launchpad.net, bugs.debian.org, and bugzilla.gnome.org. These trackers
 
346
have their own identifiers: lp, deb, and gnome respectively. For example,
 
347
if you made a change to fix the bug #1234 on bugs.launchpad.net, you would
 
348
use the following command to commit your fix::
 
349
 
 
350
    % bzr commit -m "fixed my first bug" --fixes lp:1234
 
351
 
 
352
For more information on this topic or for information on how to configure
 
353
other bug trackers please read `Bug Tracker Settings`_.
 
354
 
 
355
.. _Bug Tracker Settings: ../user-reference/index.html#bug-tracker-settings
 
356
 
 
357
Selective commit
 
358
----------------
 
359
 
 
360
If you give file or directory names on the commit command line then only
 
361
the changes to those files will be committed.  For example::
 
362
 
 
363
    % bzr commit -m "documentation fix" commit.py
 
364
 
 
365
By default bzr always commits all changes to the tree, even if run from a
 
366
subdirectory.  To commit from only the current directory down, use::
 
367
 
 
368
    % bzr commit .
 
369
 
 
370
 
 
371
Removing uncommitted changes
 
372
============================
 
373
 
 
374
If you've made some changes and don't want to keep them, use the
 
375
**revert** command to go back to the previous head version.  It's a good
 
376
idea to use ``bzr diff`` first to see what will be removed. By default the
 
377
revert command reverts the whole tree; if file or directory names are
 
378
given then only those ones will be affected. ``bzr revert`` also clears the
 
379
list of pending merges revisions.
 
380
 
 
381
 
 
382
Ignoring files
 
383
==============
 
384
 
 
385
The .bzrignore file
 
386
-------------------
 
387
 
 
388
Many source trees contain some files that do not need to be versioned,
 
389
such as editor backups, object or bytecode files, and built programs.  You
 
390
can simply not add them, but then they'll always crop up as unknown files.
 
391
You can also tell bzr to ignore these files by adding them to a file
 
392
called ``.bzrignore`` at the top of the tree.
 
393
 
 
394
This file contains a list of file wildcards (or "globs"), one per line.
 
395
Typical contents are like this::
 
396
 
 
397
    *.o
 
398
    *~
 
399
    *.tmp
 
400
    *.py[co]
 
401
 
 
402
If a glob contains a slash, it is matched against the whole path from the
 
403
top of the tree; otherwise it is matched against only the filename.  So
 
404
the previous example ignores files with extension ``.o`` in all
 
405
subdirectories, but this example ignores only ``config.h`` at the top level
 
406
and HTML files in ``doc/``::
 
407
 
 
408
    ./config.h
 
409
    doc/*.html
 
410
 
 
411
To get a list of which files are ignored and what pattern they matched,
 
412
use ``bzr ignored``::
 
413
 
 
414
    % bzr ignored
 
415
    config.h                 ./config.h
 
416
    configure.in~            *~
 
417
 
 
418
It is OK to have either an ignore pattern match a versioned file, or to
 
419
add an ignored file.  Ignore patterns have no effect on versioned files;
 
420
they only determine whether unversioned files are reported as unknown or
 
421
ignored.
 
422
 
 
423
The ``.bzrignore`` file should normally be versioned, so that new copies
 
424
of the branch see the same patterns::
 
425
 
 
426
    % bzr add .bzrignore
 
427
    % bzr commit -m "Add ignore patterns"
 
428
 
 
429
 
 
430
bzr ignore
 
431
----------
 
432
 
 
433
As an alternative to editing the ``.bzrignore`` file, you can use the
 
434
``bzr ignore`` command. The ``bzr ignore`` command takes filenames and/or
 
435
patterns as arguments and then adds them to the ``.bzrignore`` file. If a
 
436
``.bzrignore`` file does not exist the ``bzr ignore`` command will
 
437
automatically create one for you, and implicitly add it to be versioned::
 
438
 
 
439
    % bzr ignore tags
 
440
    % bzr status
 
441
    added:
 
442
      .bzrignore
 
443
 
 
444
Just like when editing the ``.bzrignore`` file on your own, you should
 
445
commit the automatically created ``.bzrignore`` file::
 
446
 
 
447
    % bzr commit -m "Added tags to ignore file"
 
448
 
 
449
 
 
450
Global ignores
 
451
--------------
 
452
 
 
453
There are some ignored files which are not project specific, but more user
 
454
specific. Things like editor temporary files, or personal temporary files.
 
455
Rather than add these ignores to every project, bzr supports a global
 
456
ignore file in ``~/.bazaar/ignore`` [1]_. It has the same syntax as the
 
457
per-project ignore file.
 
458
 
 
459
 
 
460
Examining history
 
461
=================
 
462
 
 
463
bzr log
 
464
-------
 
465
 
 
466
The ``bzr log`` command shows a list of previous revisions. The ``bzr log
 
467
--forward`` command does the same in chronological order to get most
 
468
recent revisions printed at last.
 
469
 
 
470
As with ``bzr diff``, ``bzr log`` supports the ``-r`` argument::
 
471
 
 
472
    % bzr log -r 1000..          # Revision 1000 and everything after it
 
473
    % bzr log -r ..1000          # Everything up to and including r1000
 
474
    % bzr log -r 1000..1100      # changes from 1000 to 1100
 
475
    % bzr log -r 1000            # The changes in only revision 1000
 
476
 
 
477
 
 
478
Branch statistics
 
479
=================
 
480
 
 
481
The ``bzr info`` command shows some summary information about the working
 
482
tree and the branch history.
 
483
 
 
484
 
 
485
Versioning directories
 
486
======================
 
487
 
 
488
bzr versions files and directories in a way that can keep track of renames
 
489
and intelligently merge them::
 
490
 
 
491
    % mkdir src
 
492
    % echo 'int main() {}' > src/simple.c
 
493
    % bzr add src
 
494
    added src
 
495
    added src/simple.c
 
496
    % bzr status
 
497
    added:
 
498
      src/
 
499
      src/simple.c
 
500
 
 
501
 
 
502
Deleting and removing files
 
503
===========================
 
504
 
 
505
You can delete files or directories by just deleting them from the working
 
506
directory.  This is a bit different to CVS, which requires that you also
 
507
do ``cvs remove``.
 
508
 
 
509
``bzr remove`` makes the file un-versioned, but may or may not delete the
 
510
working copy [2]_.  This is useful when you add the wrong file, or decide that
 
511
a file should actually not be versioned.
 
512
 
 
513
::
 
514
 
 
515
    % rm -r src
 
516
    % bzr remove -v hello.txt
 
517
    ?       hello.txt
 
518
    % bzr status
 
519
    removed:
 
520
      hello.txt
 
521
      src/
 
522
      src/simple.c
 
523
    unknown:
 
524
      hello.txt
 
525
 
 
526
If you remove the wrong file by accident, you can use ``bzr revert`` to
 
527
restore it.
 
528
 
 
529
 
 
530
Branching
 
531
=========
 
532
 
 
533
Often rather than starting your own project, you will want to submit a
 
534
change to an existing project.  To do this, you'll need to get a copy of
 
535
the existing branch.  Because this new copy is potentially a new branch,
 
536
the command is called **branch**::
 
537
 
 
538
    % bzr branch http://bazaar-vcs.org/bzr/bzr.dev
 
539
    % cd bzr.dev
 
540
 
 
541
This copies down the complete history of this branch, so we can do all
 
542
operations on it locally: log, annotate, making and merging branches.
 
543
There will be an option to get only part of the history if you wish.
 
544
 
 
545
You can also get a copy of an existing branch by copying its directory,
 
546
expanding a tarball, or by a remote copy using something like rsync.
 
547
 
 
548
Following upstream changes
 
549
==========================
 
550
 
 
551
You can stay up-to-date with the parent branch by "pulling" in their
 
552
changes::
 
553
 
 
554
    % bzr pull
 
555
 
 
556
After this change, the local directory will be a mirror of the source. This
 
557
includes the ''revision-history'' - which is a list of the commits done in
 
558
this branch, rather than merged from other branches.
 
559
 
 
560
This command only works if your local (destination) branch is either an
 
561
older copy of the parent branch with no new commits of its own, or if the
 
562
most recent commit in your local branch has been merged into the parent
 
563
branch.
 
564
 
 
565
Merging from related branches
 
566
=============================
 
567
 
 
568
If two branches have diverged (both have unique changes) then ``bzr
 
569
merge`` is the appropriate command to use. Merge will automatically
 
570
calculate the changes that exist in the branch you're merging from that
 
571
are not in your branch and attempt to apply them in your branch.
 
572
 
 
573
::
 
574
 
 
575
  % bzr merge URL
 
576
 
 
577
 
 
578
If there is a conflict during a merge, 3 files with the same basename
 
579
are created. The filename of the common base is appended with ".BASE",
 
580
the filename of the file containing your changes is appended with
 
581
".THIS" and the filename with the changes from the other tree is
 
582
appended with ".OTHER".  Using a program such as kdiff3, you can now
 
583
comfortably merge them into one file.  In order to commit you have to
 
584
rename the merged file (".THIS") to the original file name.  To
 
585
complete the conflict resolution you must use the resolve command,
 
586
which will remove the ".OTHER" and ".BASE" files.  As long as there
 
587
exist files with .BASE, .THIS or .OTHER the commit command will
 
588
report an error.
 
589
 
 
590
::
 
591
 
 
592
  % kdiff3 file.BASE file.OTHER file.THIS
 
593
  % mv file.THIS file
 
594
  % bzr resolve file
 
595
 
 
596
[**TODO**: explain conflict markers within files]
 
597
 
 
598
 
 
599
Publishing your branch
 
600
======================
 
601
 
 
602
You don't need a special server to publish a bzr branch, just a normal web
 
603
server.  Just mirror the files to your server, including the .bzr
 
604
directory.  One can push a branch (or the changes for a branch) by one of
 
605
the following three methods:
 
606
 
 
607
* The best method is to use bzr itself to do it.
 
608
 
 
609
  ::
 
610
 
 
611
    % bzr push sftp://servername.com/path/to/directory
 
612
 
 
613
  (The destination directory must already exist unless the
 
614
  ``--create-prefix`` option is used.)
 
615
 
 
616
* Another option is the ``rspush`` plugin that comes with BzrTools, which
 
617
  uses rsync to push the changes to the revision history and the working
 
618
  tree.
 
619
 
 
620
* You can also copy the files around manually, by sending a tarball, or using
 
621
  rsync, or other related file transfer methods.  This is usually less safe
 
622
  than using ``push``, but may be faster or easier in some situations.
 
623
 
 
624
 
 
625
Moving changes between trees
 
626
============================
 
627
 
 
628
It happens to the best of us: sometimes you'll make changes in the wrong
 
629
tree.  Maybe because you've accidentally started work in the wrong directory,
 
630
maybe because as you're working, the change turns out to be bigger than you
 
631
expected, so you start a new branch for it.
 
632
 
 
633
To move your changes from one tree to another, use
 
634
 
 
635
::
 
636
 
 
637
  % cd NEWDIR
 
638
  % bzr merge --uncommitted OLDDIR
 
639
 
 
640
This will apply all of the uncommitted changes you made in OLDDIR to NEWDIR.
 
641
It will not apply committed changes, even if they could be applied to NEWDIR
 
642
with a regular merge.  The changes will remain in OLDDIR, but you can use ``bzr
 
643
revert OLDDIR`` to remove them, once you're satisfied with NEWDIR.
 
644
 
 
645
NEWDIR does not have to be a copy of OLDDIR, but they should be related.
 
646
The more different they are, the greater the chance of conflicts.