← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/tutorial.txt

  • Committer: Aaron Bentley
  • Date: 2007-06-14 04:36:50 UTC
  • mfrom: (2527 +trunk)
  • mto: This revision was merged to the branch mainline in revision 2528.
  • Revision ID: aaron.bentley@utoronto.ca-20070614043650-q2yb3mo03kcr8l2p
Merge bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/tutorial.txt
129
129
 
130
130
    % bzr whoami --branch "Your Name <email@example.com>"
131
131
 
132
 
 #. Setting the email address in the ``~/.bazaar/bazaar.conf`` [1]_ by adding the following lines.
133
 
    Please note that  ``[DEFAULT]`` is case sensitive::
134
 
    [DEFAULT]
135
 
    email= Your Name <email@isp.com>
136
 
 
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
139
 
    following lines::
140
 
    [/the/path/to/the/branch]
141
 
    email=Your Name <email@isp.com>
 
132
 #. Setting the email address in the ``~/.bazaar/bazaar.conf`` [1]_ by
 
133
    adding the following lines.  Please note that  ``[DEFAULT]`` is case
 
134
    sensitive::
 
135
 
 
136
        [DEFAULT]
 
137
        email=Your Name <email@isp.com>
 
138
 
 
139
    As above, you can override this settings on a branch by branch basis
 
140
    by creating a branch section in ``~/.bazaar/locations.conf`` and
 
141
    adding the following lines::
 
142
 
 
143
        [/the/path/to/the/branch]
 
144
        email=Your Name <email@isp.com>
142
145
 
143
146
 
144
147
 #. 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.
 
148
    variable ``$BZR_EMAIL`` or ``$EMAIL`` (``$BZR_EMAIL`` will take
 
149
    precedence) to your full email address.
147
150
 
148
151
.. [1] On Windows, the users configuration files can be found in the
149
152
   application data directory. So instead of ``~/.bazaar/branch.conf``
187
190
      hello.txt
188
191
 
189
192
 
190
 
If you add the wrong file, simply use **bzr remove** to make it
 
193
If you add the wrong file, simply use ``bzr remove`` to make it
191
194
unversioned again.  This does not delete the working copy in this case,
192
195
though it may in others [2]_.
193
196
 
202
205
All history is stored in a branch, which is just an on-disk directory
203
206
containing control files.  By default there is no separate repository or
204
207
database as used in svn or svk. You can choose to create a repository if
205
 
you want to (see the **bzr init-repo** command). You may wish to do this
 
208
you want to (see the ``bzr init-repo`` command). You may wish to do this
206
209
if you have very large branches, or many branches of a moderately sized
207
210
project.
208
211
 
243
246
    modified:
244
247
       foo
245
248
 
246
 
**bzr status** hides "boring" files that are either unchanged or ignored.
 
249
``bzr status`` hides "boring" files that are either unchanged or ignored.
247
250
The status command can optionally be given the name of some files or
248
251
directories to check.
249
252
 
262
265
    +hello world
263
266
 
264
267
 
265
 
With the ''-r'' option, the tree is compared to an earlier revision, or
 
268
With the ``-r`` option, the tree is compared to an earlier revision, or
266
269
the differences between two versions are shown::
267
270
 
268
271
    % bzr diff -r 1000..          # everything since r1000
269
272
    % bzr diff -r 1000..1100      # changes from 1000 to 1100
270
273
 
271
 
The --diff-options option causes bzr to run the external diff program,
 
274
The ``--diff-options`` option causes bzr to run the external diff program,
272
275
passing options.  For example::
273
276
 
274
277
    % bzr diff --diff-options --side-by-side foo
275
278
 
276
 
Some projects prefer patches to show a prefix at the start of the path for
277
 
old and new files.  The --prefix option can be used to provide such a prefix. 
 
279
Some projects prefer patches to show a prefix at the start of the path
 
280
for old and new files.  The ``--prefix`` option can be used to provide
 
281
such a prefix.
278
282
As a shortcut, ``bzr diff -p1`` produces a form that works with the 
279
283
command ``patch -p1``.
280
284
 
290
294
The **commit** command takes a message describing the changes in the
291
295
revision.  It also records your userid, the current time and timezone, and
292
296
the inventory and contents of the tree.  The commit message is specified
293
 
by the ''-m'' or ''--message'' option. You can enter a multi-line commit
 
297
by the ``-m`` or ``--message`` option. You can enter a multi-line commit
294
298
message; in most shells you can enter this just by leaving the quotes open
295
299
at the end of the line.
296
300
 
298
302
 
299
303
    % bzr commit -m "added my first file"
300
304
 
301
 
You can also use the -F option to take the message from a file.  Some
 
305
You can also use the ``-F`` option to take the message from a file.  Some
302
306
people like to make notes for a commit message while they work, then
303
307
review the diff to make sure they did what they said they did.  (This file
304
308
can also be useful when you pick up your work after a break.)
306
310
Message from an editor
307
311
======================
308
312
 
309
 
If you use neither the `-m` nor the `-F` option then bzr will open an
 
313
If you use neither the ``-m`` nor the ``-F`` option then bzr will open an
310
314
editor for you to enter a message.  The editor to run is controlled by
311
 
your `$VISUAL` or `$EDITOR` environment variable, which can be overridden
312
 
by the `editor` setting in to ~/.bazaar/bazaar.conf; `$BZR_EDITOR` will
 
315
your ``$VISUAL`` or ``$EDITOR`` environment variable, which can be overridden
 
316
by the ``editor`` setting in ``~/.bazaar/bazaar.conf``; ``$BZR_EDITOR`` will
313
317
override either of the above mentioned editor options.  If you quit the
314
318
editor without making any changes, the commit will be cancelled.
315
319
 
332
336
 
333
337
If you've made some changes and don't want to keep them, use the
334
338
**revert** command to go back to the previous head version.  It's a good
335
 
idea to use **bzr diff** first to see what will be removed. By default the
 
339
idea to use ``bzr diff`` first to see what will be removed. By default the
336
340
revert command reverts the whole tree; if file or directory names are
337
 
given then only those ones will be affected. **revert** also clears the
 
341
given then only those ones will be affected. ``bzr revert`` also clears the
338
342
list of pending merges revisions.
339
343
 
340
344
Ignoring files
344
348
such as editor backups, object or bytecode files, and built programs.  You
345
349
can simply not add them, but then they'll always crop up as unknown files.
346
350
You can also tell bzr to ignore these files by adding them to a file
347
 
called ''.bzrignore'' at the top of the tree.
 
351
called ``.bzrignore`` at the top of the tree.
348
352
 
349
353
This file contains a list of file wildcards (or "globs"), one per line.
350
354
Typical contents are like this::
357
361
If a glob contains a slash, it is matched against the whole path from the
358
362
top of the tree; otherwise it is matched against only the filename.  So
359
363
the previous example ignores files with extension ``.o`` in all
360
 
subdirectories, but this example ignores only config.h at the top level
 
364
subdirectories, but this example ignores only ``config.h`` at the top level
361
365
and HTML files in ``doc/``::
362
366
 
363
367
    ./config.h
364
368
    doc/*.html
365
369
 
366
370
To get a list of which files are ignored and what pattern they matched,
367
 
use ''bzr ignored''::
 
371
use ``bzr ignored``::
368
372
 
369
373
    % bzr ignored
370
374
    config.h                 ./config.h
398
402
bzr log
399
403
-------
400
404
 
401
 
The **bzr log** command shows a list of previous revisions. The **bzr log
402
 
--forward** command does the same in chronological order to get most
 
405
The ``bzr log`` command shows a list of previous revisions. The ``bzr log
 
406
--forward`` command does the same in chronological order to get most
403
407
recent revisions printed at last.
404
408
 
405
 
As with bzr diff, bzr log supports the -r argument::
 
409
As with ``bzr diff``, ``bzr log`` supports the ``-r`` argument::
406
410
 
407
411
    % bzr log -r 1000..          # Revision 1000 and everything after it
408
412
    % bzr log -r ..1000          # Everything up to and including r1000
413
417
Branch statistics
414
418
=================
415
419
 
416
 
The **bzr info** command shows some summary information about the working
 
420
The ``bzr info`` command shows some summary information about the working
417
421
tree and the branch history.  
418
422
 
419
423
 
439
443
 
440
444
You can delete files or directories by just deleting them from the working
441
445
directory.  This is a bit different to CVS, which requires that you also
442
 
do **cvs remove**.
 
446
do ``cvs remove``.
443
447
 
444
 
    **bzr remove** makes the file un-versioned, but may or may not delete
 
448
    ``bzr remove`` makes the file un-versioned, but may or may not delete
445
449
    the working copy [2]_.  This is useful when you add the wrong file,
446
450
    or decide that a file should actually not be versioned. 
447
451
 
458
462
    unknown:
459
463
      hello.txt
460
464
 
461
 
If you remove the wrong file by accident, you can use **bzr revert** to
 
465
If you remove the wrong file by accident, you can use ``bzr revert`` to
462
466
restore it.
463
467
 
464
468
 
500
504
Merging from related branches
501
505
=============================
502
506
 
503
 
If two branches have diverged (both have unique changes) then **bzr
504
 
merge** is the appropriate command to use. Merge will automatically
 
507
If two branches have diverged (both have unique changes) then ``bzr
 
508
merge`` is the appropriate command to use. Merge will automatically
505
509
calculate the changes that exist in the branch you're merging from that
506
510
are not in your branch and attempt to apply them in your branch.
507
511
 
548
552
  (The destination directory must already exist unless the
549
553
  ``--create-prefix`` option is used.)
550
554
 
551
 
* Another option is the rspush plugin that comes with BzrTools, which
 
555
* Another option is the ``rspush`` plugin that comes with BzrTools, which
552
556
  uses rsync to push the changes to the revision history and the working
553
557
  tree.
554
558
 
574
578
 
575
579
This will apply all of the uncommitted changes you made in OLDDIR to NEWDIR.
576
580
It will not apply committed changes, even if they could be applied to NEWDIR
577
 
with a regular merge.  The changes will remain in OLDDIR, but you can use **bzr
578
 
revert OLDDIR** to remove them, once you're satisfied with NEWDIR.
 
581
with a regular merge.  The changes will remain in OLDDIR, but you can use ``bzr
 
582
revert OLDDIR`` to remove them, once you're satisfied with NEWDIR.
579
583
 
580
584
NEWDIR does not have to be a copy of OLDDIR, but they should be related.
581
585
The more different they are, the greater the chance of conflicts.