~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to tutorial.txt

  • Committer: Robert Collins
  • Date: 2005-10-06 12:14:01 UTC
  • mfrom: (1393.1.67)
  • Revision ID: robertc@robertcollins.net-20051006121401-ce87bcb93909bbdf
merge martins latest

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
==================
 
2
Bazaar-NG Tutorial
 
3
==================
 
4
 
 
5
current for bzr 0.0.6pre, July 2005
 
6
 
 
7
 
 
8
*NOTE* For a more current and user-editable version of this 
 
9
document, see the wiki at http://bazaar.canonical.com/IntroductionToBzr
 
10
 
 
11
 
 
12
Introduction
 
13
============
 
14
 
 
15
Bazaar-NG is a version control tool.  It manages trees of files and subdirectories.  In particular, it records *revisions* of trees, representing their state at a particular point in time, and information about those revisions and their relationships.  Recording and retrieving tree revisions is useful in several ways if you are writing software or documents or doing similar creative work.
 
16
 
 
17
 * Keeping previous revisions lets you go back if you make a mistake or want to check your work.  It acts as a high-level unlimited undo.
 
18
 
 
19
 * By recording comments on every revision, you produce an annotated history of the project, describing what, who, why, and when.
 
20
 
 
21
 * Using a version control tool can be an aid to thinking about a project: getting to a stable state at regular intervals and then writing a description of what you did is an easy way to stay organized and on track.
 
22
 
 
23
Bazaar-NG remembers the *ancestry* of a revision: the previous revisions that it is based upon.  A single revision may have more than one direct descendant, each with different changes, representing a divergence in the evolution of the tree.  
 
24
By branching, Bazaar-NG allows multiple people to cooperate on the evolution of a project, without all needing to work in strict
 
25
lock-step.  Branching can be useful even for a single developer.
 
26
 
 
27
Bazaar-NG installs a single new command,
 
28
*bzr*.  Everything else is a subcommand of this.  You can get
 
29
some help with ``bzr help``.  There will be more in the future.
 
30
 
 
31
 
 
32
 
 
33
Introducing yourself to bzr
 
34
===========================
 
35
 
 
36
One function of a version control system is to keep track of who
 
37
changed what.  In a distributed system that requires an identifier for
 
38
each author that is globally unique.  Most people already have one of
 
39
these: an email address.
 
40
 
 
41
[after 0.0.4] To tell bzr which email address to use, put it in the file
 
42
``$HOME/.bzr.conf/email``, or the environment variable ``$BZREMAIL``.
 
43
If neither of these are set, bzr will use the ``$EMAIL``
 
44
variable, or use your username and hostname.
 
45
 
 
46
To check this has taken effect, or if you forget your own name, use
 
47
the ``whoami`` ("who am i?") command::
 
48
 
 
49
  % bzr whoami
 
50
 
 
51
Some people want to avoid sharing their email address so as not to
 
52
get spam.  bzr will never
 
53
disclose your email address unless you tell it to by publishing an
 
54
archive or transmitting a changeset.  It's recommended that you do use
 
55
a real address, so that people can contact you about your work, but
 
56
it's not required.  You can use an address which is obfuscated, which
 
57
bounces, or which goes through an anti-spam service such as spamgourmet.com.
 
58
 
 
59
 
 
60
 
 
61
Creating a branch
 
62
==================
 
63
 
 
64
 
 
65
History is by default stored in the .bzr directory of the branch.
 
66
There will be a facility to store it in a separate repository, which
 
67
may be remote.  We create a new branch by running *bzr init* in
 
68
an existing directory::
 
69
 
 
70
    % mkdir tutorial
 
71
    % cd tutorial
 
72
    % ls -a
 
73
    ls -a
 
74
    ./  ../
 
75
    % pwd
 
76
    /home/mbp/work/bzr.test/tutorial
 
77
    %
 
78
    % bzr init
 
79
    % ls -aF
 
80
    ./  ../  .bzr/
 
81
    %
 
82
 
 
83
As for CVS, there are three classes of file: unknown, ignored, and
 
84
versioned.  The *add* command makes a file versioned: that is,
 
85
changes to it will be recorded by the system::
 
86
 
 
87
    % echo 'hello world' > hello.txt
 
88
    % bzr status
 
89
    ?       hello.txt
 
90
    % bzr unknowns
 
91
    hello.txt
 
92
    % bzr add -v hello.txt
 
93
    A       hello.txt
 
94
    % bzr unknowns
 
95
 
 
96
 
 
97
If you add the wrong file, simply use ``bzr remove`` to make
 
98
it unversioned again.  This does not delete the working copy.
 
99
 
 
100
 
 
101
Reviewing changes
 
102
=================
 
103
 
 
104
Once you have completed some work, you will want to *commit*
 
105
it to the version history.  It is good to commit fairly often:
 
106
whenever you get a new feature working, fix a bug, or improve some
 
107
code or documentation.  It's also a good practice to make sure that
 
108
the code compiles and passes its test suite before committing, to make
 
109
sure that every revision is a known-good state.  You can also review
 
110
your changes, to make sure you're committing what you intend to, and
 
111
as a chance to rethink your work before you permanently record it. 
 
112
 
 
113
Two bzr commands are particularly useful here: *status* and
 
114
*diff*.  The *status* command
 
115
shows a listing with one line per file, indicating whether it has been
 
116
Added, Deleted, Modified, or Renamed in the current revision.  Unknown
 
117
files are shown as '?'.  With the ``--all`` option, the status
 
118
command also shows unmodified versioned files as '.', and ignored
 
119
files as 'I'::
 
120
 
 
121
    % bzr status
 
122
    A       hello.txt
 
123
 
 
124
The *diff* command shows the full text of changes to all
 
125
files as a standard unified diff.  This can be piped through many
 
126
programs such as ``patch``, ``diffstat``,
 
127
``filterdiff`` and ``colordiff``::
 
128
 
 
129
    % bzr diff
 
130
    *** added file 'hello.txt'
 
131
    --- /dev/null 
 
132
    +++ hello.txt 
 
133
    @@ -1,0 +1,1 @@
 
134
    +hello world
 
135
 
 
136
With the ``-r`` option, the tree is compared to an earlier
 
137
revision.
 
138
 
 
139
[TODO: options to run external diff; to get context diff or other
 
140
formats; to diff only selected files; to compare two historical
 
141
revisions.]
 
142
 
 
143
 
 
144
 
 
145
Committing changes
 
146
==================
 
147
 
 
148
When the working tree state is satisfactory, it can be
 
149
*committed* to the branch, creating a new revision holding a
 
150
snapshot of that state.  
 
151
 
 
152
The ``commit`` command takes a message describing the changes
 
153
in the revision.  It also records your userid, the current time and
 
154
timezone, and the inventory and contents of the tree.  The commit
 
155
message is specified by the ``-m`` or ``--message`` option.
 
156
You can enter a multi-line commit message; in most shells you can
 
157
enter this just by leaving the quotes open at the end of the line. ::
 
158
 
 
159
    % bzr commit -m "added my first file"
 
160
 
 
161
[TODO: commit message interactively, through an editor or from a
 
162
file.]
 
163
 
 
164
[TODO: commit only selected files, including renamed/added/deleted
 
165
files.]
 
166
 
 
167
 
 
168
 
 
169
Removing uncommitted changes
 
170
============================
 
171
 
 
172
If you've made some changes and don't want to keep them, use the
 
173
``revert`` command to go back to the previous head version.  It's a
 
174
good idea to use ``bzr diff`` first to see what will be removed. 
 
175
By default the revert command reverts the whole tree; if file or
 
176
directory names are given then only those ones will be affected.
 
177
revert also clears the list of pending merges revisions.
 
178
 
 
179
 
 
180
 
 
181
 
 
182
 
 
183
Ignoring files
 
184
==============
 
185
 
 
186
Many source trees contain some files that do not need to be
 
187
versioned, such as editor backups, object or bytecode files, and built
 
188
programs.  You can simply not add them, but then they'll always crop
 
189
up as unknown files.  You can also tell bzr to ignore these files by
 
190
adding them to a file called ``.bzrignore`` at the top of the
 
191
tree.
 
192
 
 
193
This file contains a list of file wildcards (or "globs"), one
 
194
per line.  Typical contents are like this::
 
195
 
 
196
    *.o
 
197
    *~
 
198
    *.tmp
 
199
    *.py[co]
 
200
 
 
201
If a glob contains a slash, it is matched against the whole path
 
202
from the top of the tree; otherwise it is matched against only the
 
203
filename.  So the previous example ignores ``*.o`` in all
 
204
subdirectories, but this example ignores only config.h at the top
 
205
level and HTML files in ``doc/``::
 
206
 
 
207
    ./config.h
 
208
    doc/*.html
 
209
 
 
210
To get a list of which files are ignored and what pattern they matched, use ``bzr ignored``::
 
211
 
 
212
    % bzr ignored
 
213
    config.h                                           ./config.h
 
214
    configure.in~                                      *~
 
215
 
 
216
It is OK to have an ignore pattern match a versioned file, or to
 
217
add an ignored file.  Ignore patterns have no effect on versioned
 
218
files; they only determine whether unversioned files are reported as
 
219
unknown or ignored.
 
220
 
 
221
The ``.bzrignore`` file should normally be versioned, so that new
 
222
copies of the branch see the same patterns::
 
223
 
 
224
    % bzr add .bzrignore
 
225
    % bzr commit -m "Add ignore patterns"
 
226
 
 
227
 
 
228
Examining history
 
229
=================
 
230
 
 
231
bzr log
 
232
-------
 
233
 
 
234
The ``log`` command shows a list of previous revisions.
 
235
 
 
236
 
 
237
Branch statistics
 
238
=================
 
239
 
 
240
The ``bzr info`` command shows some summary information about
 
241
the working tree and the branch history.  
 
242
 
 
243
 
 
244
Versioning directories
 
245
======================
 
246
 
 
247
bzr versions files and directories in a way that can keep track of
 
248
renames and intelligently merge them::
 
249
 
 
250
    % mkdir src
 
251
    % echo 'int main() {}' > src/simple.c
 
252
    % bzr add src
 
253
    % bzr status
 
254
    A       src/
 
255
    ?       src/simple.c
 
256
    % bzr add src/simple.c
 
257
    % bzr status
 
258
    A       src/
 
259
    A       src/simple.c
 
260
 
 
261
 
 
262
Deleting and removing files
 
263
===========================
 
264
 
 
265
You can delete files or directories by just deleting them from the
 
266
working directory.  This is a bit different to CVS, which requires
 
267
that you also do *cvs remove*.
 
268
 
 
269
*bzr remove* makes the file un-versioned, but does not
 
270
delete the working copy.  This is useful when you add the wrong file,
 
271
or decide that a file should actually not be versioned. ::
 
272
 
 
273
    % rm -r src
 
274
    % bzr remove -v hello.txt
 
275
    ?       hello.txt
 
276
    % bzr status
 
277
    ?       hello.txt
 
278
    D       src/
 
279
    D       src/simple.c
 
280
 
 
281
 
 
282
Branching
 
283
=========
 
284
 
 
285
Often rather than starting your own project, you will want to
 
286
submit a change to an existing project.  You can get a copy of an
 
287
existing branch by copying its directory, expanding a tarball, or by a
 
288
remote copy using something like rsync.  You can also use bzr to fetch
 
289
a copy.  Because this new copy is potentially a new branch, the
 
290
command is called *branch*::
 
291
 
 
292
    % bzr branch http://bazaar-ng.org/bzr/bzr.dev
 
293
    % cd bzr.dev
 
294
 
 
295
This copies down the complete history of this branch, so we can
 
296
do all operations on it locally: log, annotate, making and merging
 
297
branches.  There will be an option to get only part of the history if
 
298
you wish.
 
299
 
 
300
 
 
301
 
 
302
Following upstream changes
 
303
==========================
 
304
 
 
305
You can stay up-to-date with the parent branch by *pulling*
 
306
in their changes::
 
307
 
 
308
    % bzr pull
 
309
 
 
310
This only works if your local branch includes only changes from the
 
311
parent branch.  Otherwise, the branches are said to have *diverged*,
 
312
and they must be merged instead.