27
34
deleted the configuration file for your mailserver or perhaps mauled the
28
35
source code for a pet project. Whatever happened, you have just deleted
29
36
important information that you would desperately like to get back. If this
30
has ever happened to you, then you are probably ready for Breezy.
37
has ever happened to you, then you are probably ready for Bazaar.
32
Version control systems (which I'll henceforth call VCS) such as
33
Breezy give you the ability to track changes for a directory by turning
39
Revision control systems (which I'll henceforth call RCS) such as
40
Bazaar give you the ability to track changes for a directory by turning
34
41
it into something slightly more complicated than a directory that we call
35
42
a **branch**. The branch not only stores how the directory looks right
36
43
now, but also how it looked at various points in the past. Then, when you
37
44
do something you wish you hadn't, you can restore the directory to the way
38
45
it looked at some point in the past.
40
Version control systems give users the ability to save changes to a
47
Revision control systems give users the ability to save changes to a
41
48
branch by "committing a **revision**". The revision created is essentially
42
49
a summary of the changes that were made since the last time the tree was
45
52
These revisions have other uses as well. For example, one can comment
46
53
revisions to record what the recent set of changes meant by providing an
47
54
optional log message. Real life log messages include things like "Fixed
48
the web template to close the table" and "Added SFTP suppport. Fixes #595"
55
the web template to close the table" and "Added sftp suppport. Fixes #595"
50
57
We keep these logs so that if later there is some sort of problem with
51
SFTP, we can figure out when the problem probably happened.
56
Many Version Control Systems (VCS) are stored on servers. If one wants to
57
work on the code stored within a VCS, then one needs to connect to the
58
sftp, we can figure out when the problem probably happened.
63
Many Revision Control Systems (RCS) are stored on servers. If one wants to
64
work on the code stored within an RCS, then one needs to connect to the
58
65
server and "checkout" the code. Doing so gives one a directory in which a
59
person can make changes and then commit. The VCS client then connects to
60
the VCS server and stores the changes. This method is known as the
66
person can make changes and then commit. The RCS client then connects to
67
the RCS server and stores the changes. This method is known as the
63
The centralized model can have some drawbacks. A centralized VCS requires
70
The centralized model can have some drawbacks. A centralized RCS requires
64
71
that one is able to connect to the server whenever one wants to do version
65
72
control work. This can be a bit of a problem if your server is on some other
66
73
machine on the internet and you are not. Or, worse yet, you **are** on the
67
74
internet but the server is missing!
69
Decentralized Version Control Systems (which I'll call DVCS after this
76
Decentralized Revision Control Systems (which I'll call DRCS after this
70
77
point) deal with this problem by keeping branches on the same machine as
71
the client. In Breezy's case, the branch is kept in the same place as
78
the client. In Bazaar's case, the branch is kept in the same place as
72
79
the code that is being version controlled. This allows the user to save
73
80
his changes (**commit**) whenever he wants -- even if he is offline. The
74
81
user only needs internet access when he wants to access the changes in
75
82
someone else's branch that are somewhere else.
78
85
A common requirement that many people have is the need to keep track of
79
86
the changes for a directory such as file and subdirectory changes.
80
87
Performing this tracking by hand is a awkward process that over time
81
88
becomes unwieldy. That is, until one considers version control tools such
82
as Breezy. These tools automate the process of storing data by creating
83
a **revision** of the directory tree whenever the user asks.
89
as Bazaar. These tools automate the process of storing data by creating
90
a **revision** of the directory tree whenever the user asks.
85
Version control software such as Breezy can do much more than just
86
storage and performing undo. For example, with Breezy a developer can
92
Revision control software such as Bazaar can do much more than just
93
storage and performing undo. For example, with Bazaar a developer can
87
94
take the modifications in one branch of software and apply them to a
88
95
related branch -- even if those changes exist in a branch owned by
89
96
somebody else. This allows developers to cooperate without giving
90
97
write access to the repository.
92
Breezy remembers the ''ancestry'' of a revision: the previous revisions
99
Bazaar remembers the ''ancestry'' of a revision: the previous revisions
93
100
that it is based upon. A single revision may have more than one direct
94
101
descendant, each with different changes, representing a divergence in the
95
evolution of the tree. By branching, Breezy allows multiple people to
102
evolution of the tree. By branching, Bazaar allows multiple people to
96
103
cooperate on the evolution of a project, without all needing to work in
97
104
strict lock-step. Branching can be useful even for a single developer.
99
Introducing yourself to Breezy
106
Introducing yourself to Bazaar
100
107
==============================
102
Breezy installs a single new command, **brz**. Everything else is a
103
subcommand of this. You can get some help with ``brz help``. Some arguments
104
are grouped in topics: ``brz help topics`` to see which topics are available.
109
Bazaar installs a single new command, **bzr**. Everything else is a
110
subcommand of this. You can get some help with ``bzr help``. Some arguments
111
are grouped in topics: ``bzr help topics`` to see which topics are available.
112
There will be more in the future.
106
114
One function of a version control system is to keep track of who changed
107
115
what. In a decentralized system, that requires an identifier for each
108
116
author that is globally unique. Most people already have one of these: an
109
email address. Breezy is smart enough to automatically generate an email
117
email address. Bzr is smart enough to automatically generate an email
110
118
address by looking up your username and hostname. If you don't like the
111
guess that Breezy makes, then three options exist:
113
1. Set an email address via ``brz whoami``. This is the simplest way.
115
To set a global identity, use::
117
% brz whoami "Your Name <email@example.com>"
119
If you'd like to use a different address for a specific branch, enter
120
the branch folder and use::
122
% brz whoami --branch "Your Name <email@example.com>"
124
#. Setting the email address in the ``~/.config/breezy/breezy.conf`` [1]_ by
125
adding the following lines. Please note that ``[DEFAULT]`` is case
129
email=Your Name <email@isp.com>
131
As above, you can override this settings on a branch by branch basis
132
by creating a branch section in ``~/.config/breezy/locations.conf`` and
133
adding the following lines::
135
[/the/path/to/the/branch]
136
email=Your Name <email@isp.com>
139
#. Overriding the two previous options by setting the global environment
140
variable ``$brz_EMAIL`` or ``$EMAIL`` (``$brz_EMAIL`` will take
141
precedence) to your full email address.
119
guess that Bazaar makes, then three options exist:
121
1. Set an email address via ``bzr whoami``. This is the simplest way.
123
To set a global identity, use::
125
% bzr whoami "Your Name <email@example.com>"
127
If you'd like to use a different address for a specific branch, enter
128
the branch folder and use::
130
% bzr whoami --branch "Your Name <email@example.com>"
132
#. Setting the email address in the ``~/.bazaar/bazaar.conf`` [1]_ by adding the following lines.
133
Please note that ``[DEFAULT]`` is case sensitive::
135
email= Your Name <email@isp.com>
137
As above, you can override this settings on a branch by branch basis by
138
creating a branch section in ``~/.bazaar/locations.conf`` and adding the
140
[/the/path/to/the/branch]
141
email=Your Name <email@isp.com>
144
#. Overriding the two previous options by setting the global environment
145
variable ``$BZREMAIL`` or ``$EMAIL`` (``$BZREMAIL`` will take precedence)
146
to your full email address.
143
148
.. [1] On Windows, the users configuration files can be found in the
144
application data directory. So instead of ``~/.config/breezy/breezy.conf``
145
the configuration file can be found as:
146
``C:\Documents and Settings\<username>\Application Data\Breezy\2.0\breezy.conf``.
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``.
147
152
The same is true for ``locations.conf``, ``ignore``, and the
148
153
``plugins`` directory.
226
220
its test suite before committing, to make sure that every revision is a
227
221
known-good state. You can also review your changes, to make sure you're
228
222
committing what you intend to, and as a chance to rethink your work before
229
you permanently record it.
231
Two brz commands are particularly useful here: **status** and **diff**.
223
you permanently record it.
225
Two bzr commands are particularly useful here: **status** and **diff**.
236
230
The **status** command tells you what changes have been made to the
237
231
working directory since the last revision::
243
``brz status`` hides "boring" files that are either unchanged or ignored.
244
The status command can optionally be given the name of some files or
245
directories to check.
237
By default **bzr status** hides "boring" files that are either unchanged
238
or ignored. To see them too, use the --all option. The status command
239
can optionally be given the name of some files or directories to check.
250
244
The **diff** command shows the full text of changes to all files as a
251
245
standard unified diff. This can be piped through many programs such as
252
246
''patch'', ''diffstat'', ''filterdiff'' and ''colordiff''::
255
=== added file 'hello.txt'
256
--- hello.txt 1970-01-01 00:00:00 +0000
257
+++ hello.txt 2005-10-18 14:23:29 +0000
249
*** added file 'hello.txt'
262
With the ``-r`` option, the tree is compared to an earlier revision, or
256
With the ''-r'' option, the tree is compared to an earlier revision, or
263
257
the differences between two versions are shown::
265
% brz diff -r 1000.. # everything since r1000
266
% brz diff -r 1000..1100 # changes from 1000 to 1100
259
% bzr diff -r 1000.. # everything since r1000
260
% bzr diff -r 1000..1100 # changes from 1000 to 1100
268
The ``--diff-options`` option causes brz to run the external diff program,
262
The --diff-options option causes bzr to run the external diff program,
269
263
passing options. For example::
271
% brz diff --diff-options --side-by-side foo
265
% bzr diff --diff-options --side-by-side foo
273
Some projects prefer patches to show a prefix at the start of the path
274
for old and new files. The ``--prefix`` option can be used to provide
276
As a shortcut, ``brz diff -p1`` produces a form that works with the
267
Some projects prefer patches to show a prefix at the start of the path for
268
old and new files. The --prefix option can be used to provide such a prefix.
269
As a shortcut, ``bzr diff -p1`` produces a form that works with the
277
270
command ``patch -p1``.
280
272
Committing changes
281
273
==================
283
275
When the working tree state is satisfactory, it can be **committed** to
284
the branch, creating a new revision holding a snapshot of that state.
276
the branch, creating a new revision holding a snapshot of that state.
289
281
The **commit** command takes a message describing the changes in the
290
282
revision. It also records your userid, the current time and timezone, and
291
283
the inventory and contents of the tree. The commit message is specified
292
by the ``-m`` or ``--message`` option. You can enter a multi-line commit
284
by the ''-m'' or ''--message'' option. You can enter a multi-line commit
293
285
message; in most shells you can enter this just by leaving the quotes open
294
286
at the end of the line.
298
% brz commit -m "added my first file"
290
% bzr commit -m "added my first file"
300
You can also use the ``-F`` option to take the message from a file. Some
292
You can also use the -F option to take the message from a file. Some
301
293
people like to make notes for a commit message while they work, then
302
294
review the diff to make sure they did what they said they did. (This file
303
295
can also be useful when you pick up your work after a break.)
305
297
Message from an editor
306
----------------------
298
======================
308
If you use neither the ``-m`` nor the ``-F`` option then brz will open an
300
If you use neither the `-m` nor the `-F` option then bzr will open an
309
301
editor for you to enter a message. The editor to run is controlled by
310
your ``$VISUAL`` or ``$EDITOR`` environment variable, which can be overridden
311
by the ``editor`` setting in ``~/.config/breezy/breezy.conf``; ``$BRZ_EDITOR``
312
will override either of the above mentioned editor options. If you quit the
302
your `$VISUAL` or `$EDITOR` environment variable, which can be overridden
303
by the `editor` setting in to ~/.bazaar/bazaar.conf; `$BZR_EDITOR` will
304
override either of the above mentioned editor options. If you quit the
313
305
editor without making any changes, the commit will be cancelled.
315
The file that is opened in the editor contains a horizontal line. The part
316
of the file below this line is included for information only, and will not
317
form part of the commit message. Below the separator is shown the list of
318
files that are changed in the commit. You should write your message above
319
the line, and then save the file and exit.
321
If you would like to see the diff that will be committed as you edit the
322
message you can use the ``--show-diff`` option to ``commit``. This will include
323
the diff in the editor when it is opened, below the separator and the
324
information about the files that will be committed. This means that you can
325
read it as you write the message, but the diff itself wont be seen in the
326
commit message when you have finished. If you would like parts to be
327
included in the message you can copy and paste them above the separator.
329
Marking bugs as fixed
330
---------------------
332
Many changes to a project are as a result of fixing bugs. Breezy can keep
333
metadata about bugs you fixed when you commit them. To do this you use the
334
``--fixes`` option. This option takes an argument that looks like this::
336
% brz commit --fixes <tracker>:<id>
338
Where ``<tracker>`` is an identifier for a bug tracker and ``<id>`` is an
339
identifier for a bug that is tracked in that bug tracker. ``<id>`` is usually
340
a number. Breezy already knows about a few popular bug trackers. They are
341
bugs.launchpad.net, bugs.debian.org, and bugzilla.gnome.org. These trackers
342
have their own identifiers: lp, deb, and gnome respectively. For example,
343
if you made a change to fix the bug #1234 on bugs.launchpad.net, you would
344
use the following command to commit your fix::
346
% brz commit -m "fixed my first bug" --fixes lp:1234
348
For more information on this topic or for information on how to configure
349
other bug trackers please read `Bug Tracker Settings`_.
351
.. _Bug Tracker Settings: ../user-reference/index.html#bug-tracker-settings
356
310
If you give file or directory names on the commit command line then only
357
311
the changes to those files will be committed. For example::
359
% brz commit -m "documentation fix" commit.py
313
% bzr commit -m "documentation fix" commit.py
361
By default brz always commits all changes to the tree, even if run from a
315
By default bzr always commits all changes to the tree, even if run from a
362
316
subdirectory. To commit from only the current directory down, use::
367
321
Removing uncommitted changes
419
369
The ``.bzrignore`` file should normally be versioned, so that new copies
420
370
of the branch see the same patterns::
423
% brz commit -m "Add ignore patterns"
429
As an alternative to editing the ``.bzrignore`` file, you can use the
430
``brz ignore`` command. The ``brz ignore`` command takes filenames and/or
431
patterns as arguments and then adds them to the ``.bzrignore`` file. If a
432
``.bzrignore`` file does not exist the ``brz ignore`` command will
433
automatically create one for you, and implicitly add it to be versioned::
440
Just like when editing the ``.bzrignore`` file on your own, you should
441
commit the automatically created ``.bzrignore`` file::
443
% brz commit -m "Added tags to ignore file"
373
% bzr commit -m "Add ignore patterns"
449
379
There are some ignored files which are not project specific, but more user
450
380
specific. Things like editor temporary files, or personal temporary files.
451
Rather than add these ignores to every project, brz supports a global
452
ignore file in ``~/.config/breezy/ignore`` [1]_. It has the same syntax as the
381
Rather than add these ignores to every project, bzr supports a global
382
ignore file in ``~/.bazaar/ignore`` [1]_. It has the same syntax as the
453
383
per-project ignore file.
456
386
Examining history
457
387
=================
462
The ``brz log`` command shows a list of previous revisions. The ``brz log
463
--forward`` command does the same in chronological order to get most
392
The **bzr log** command shows a list of previous revisions. The **bzr log
393
--forward** command does the same in chronological order to get most
464
394
recent revisions printed at last.
466
As with ``brz diff``, ``brz log`` supports the ``-r`` argument::
396
As with bzr diff, bzr log supports the -r argument::
468
% brz log -r 1000.. # Revision 1000 and everything after it
469
% brz log -r ..1000 # Everything up to and including r1000
470
% brz log -r 1000..1100 # changes from 1000 to 1100
471
% brz log -r 1000 # The changes in only revision 1000
398
% bzr log -r 1000.. # Revision 1000 and everything after it
399
% bzr log -r ..1000 # Everything up to and including r1000
400
% bzr log -r 1000..1100 # changes from 1000 to 1100
401
% bzr log -r 1000 # The changes in only revision 1000
474
404
Branch statistics
475
405
=================
477
The ``brz info`` command shows some summary information about the working
478
tree and the branch history.
407
The **bzr info** command shows some summary information about the working
408
tree and the branch history.
481
411
Versioning directories
482
412
======================
484
brz versions files and directories in a way that can keep track of renames
414
bzr versions files and directories in a way that can keep track of renames
485
415
and intelligently merge them::
488
418
% echo 'int main() {}' > src/simple.c
491
421
added src/simple.c
529
459
Often rather than starting your own project, you will want to submit a
530
change to an existing project. To do this, you'll need to get a copy of
531
the existing branch. Because this new copy is potentially a new branch,
532
the command is called **branch**::
460
change to an existing project. You can get a copy of an existing branch
461
by copying its directory, expanding a tarball, or by a remote copy using
462
something like rsync. You can also use bzr to fetch a copy. Because this
463
new copy is potentially a new branch, the command is called *branch*::
534
% brz branch lp:brz brz.dev
465
% bzr branch http://bazaar-vcs.org/bzr/bzr.dev
537
468
This copies down the complete history of this branch, so we can do all
538
469
operations on it locally: log, annotate, making and merging branches.
539
470
There will be an option to get only part of the history if you wish.
541
You can also get a copy of an existing branch by copying its directory,
542
expanding a tarball, or by a remote copy using something like rsync.
544
472
Following upstream changes
545
473
==========================
547
475
You can stay up-to-date with the parent branch by "pulling" in their
552
480
After this change, the local directory will be a mirror of the source. This
553
includes the ''revision-history'' - which is a list of the commits done in
481
includes the ''revision-history'' - which is a list of the commits done in
554
482
this branch, rather than merged from other branches.
556
484
This command only works if your local (destination) branch is either an
added
removed
doc/tutorial.txt
