28
28
================================
30
30
Odds are that you have worked on some sort of textual data -- the sources
31
to a program, web sites or the config files that Unix system administrators
32
have to deal with in /etc. The chances are also good that you have made
33
some sort of mistake that you deeply regretted. Perhaps you deleted the
34
configuration file for your mailserver or perhaps mauled the source code
35
for a pet project. Whatever happened, you have just deleted important
36
information that you would desperately like to get back. If this has ever
37
happened to you, then you are probably ready for Bazaar-NG.
39
Revision control systems (which I'll henceforth call RCS) such as Bazaar-NG
40
give you the ability to track changes for a directory by turning it into
41
something slightly more complicated than a directory that we call a
42
**branch**. The branch not only stores how the directory looks right now,
43
but also how it looked at various points in the past. Then, when you do
44
something you wish you hadn't, you can restore the directory to the way it
45
looked at some point in the past.
47
Revision control systems give users the ability to save changes to a branch
48
by "committing a **revision**". The revision created is essentially a
49
summary of the changes that were made since the last time the tree was
31
to a program, web sites or the config files that Unix system
32
administrators have to deal with in /etc. The chances are also good that
33
you have made some sort of mistake that you deeply regretted. Perhaps you
34
deleted the configuration file for your mailserver or perhaps mauled the
35
source code for a pet project. Whatever happened, you have just deleted
36
important information that you would desperately like to get back. If this
37
has ever happened to you, then you are probably ready for Bazaar-NG.
39
Revision control systems (which I'll henceforth call RCS) such as
40
Bazaar-NG give you the ability to track changes for a directory by turning
41
it into something slightly more complicated than a directory that we call
42
a **branch**. The branch not only stores how the directory looks right
43
now, but also how it looked at various points in the past. Then, when you
44
do something you wish you hadn't, you can restore the directory to the way
45
it looked at some point in the past.
47
Revision control systems give users the ability to save changes to a
48
branch by "committing a **revision**". The revision created is essentially
49
a summary of the changes that were made since the last time the tree was
52
52
These revisions have other uses as well. For example, one can comment
53
53
revisions to record what the recent set of changes meant by providing an
54
optional log message. Real life log messages include things like "Fixed the
55
web template to close the table" and "Added sftp suppport. Fixes #595"
54
optional log message. Real life log messages include things like "Fixed
55
the web template to close the table" and "Added sftp suppport. Fixes #595"
57
57
We keep these logs so that if later there is some sort of problem with
58
58
sftp, we can figure out when the problem probably happened.
76
76
Decentralized Revision Control Systems (which I'll call DRCS after this
77
77
point) deal with this problem by keeping branches on the same machine as
78
78
the client. In Bazaar-NG's case, the branch is kept in the same place as
79
the code that is being version controlled. This allows the user to save his
80
changes (**commit**) whenever he wants -- even if he is offline. The user
81
only needs internet access when he wants to access the changes in someone
82
else's branch that are somewhere else.
79
the code that is being version controlled. This allows the user to save
80
his changes (**commit**) whenever he wants -- even if he is offline. The
81
user only needs internet access when he wants to access the changes in
82
someone else's branch that are somewhere else.
85
A common requirement that many people have is the need to keep track of the
86
changes for a directory such as file and subdirectory changes. Performing
87
this tracking by hand is a awkward process that over time becomes unwieldy.
88
That is, until one considers version control tools such as Bazaar-NG. These
89
tools automate the process of storing data by creating a **revision** of
90
the directory tree whenever the user asks.
85
A common requirement that many people have is the need to keep track of
86
the changes for a directory such as file and subdirectory changes.
87
Performing this tracking by hand is a awkward process that over time
88
becomes unwieldy. That is, until one considers version control tools such
89
as Bazaar-NG. These tools automate the process of storing data by creating
90
a **revision** of the directory tree whenever the user asks.
92
92
Revision control software such as Bazaar-NG can do much more than just
93
93
storage and performing undo. For example, with Bazaar-NG developer can
94
take the modifications in one branch of software and apply them to another,
95
related, branch -- even if those changes exist in a branch owned by
96
somebody else. This allows developers to cooperate without giving write
94
take the modifications in one branch of software and apply them to
95
another, related, branch -- even if those changes exist in a branch owned
96
by somebody else. This allows developers to cooperate without giving write
97
97
access to repository.
99
99
Bazaar-NG remembers the ''ancestry'' of a revision: the previous revisions
294
298
Removing uncommitted changes
295
299
============================
297
If you've made some changes and don't want to keep them, use the **revert**
298
command to go back to the previous head version. It's a good idea to use
299
**bzr diff** first to see what will be removed. By default the revert
300
command reverts the whole tree; if file or directory names are given then
301
only those ones will be affected. **revert** also clears the list of
302
pending merges revisions.
301
If you've made some changes and don't want to keep them, use the
302
**revert** command to go back to the previous head version. It's a good
303
idea to use **bzr diff** first to see what will be removed. By default the
304
revert command reverts the whole tree; if file or directory names are
305
given then only those ones will be affected. **revert** also clears the
306
list of pending merges revisions.
307
Many source trees contain some files that do not need to be versioned, such
308
as editor backups, object or bytecode files, and built programs. You can
309
simply not add them, but then they'll always crop up as unknown files. You
310
can also tell bzr to ignore these files by adding them to a file called
311
''.bzrignore'' at the top of the tree.
311
Many source trees contain some files that do not need to be versioned,
312
such as editor backups, object or bytecode files, and built programs. You
313
can simply not add them, but then they'll always crop up as unknown files.
314
You can also tell bzr to ignore these files by adding them to a file
315
called ''.bzrignore'' at the top of the tree.
313
317
This file contains a list of file wildcards (or "globs"), one per line.
314
318
Typical contents are like this::
427
434
operations on it locally: log, annotate, making and merging branches.
428
435
There will be an option to get only part of the history if you wish.
433
Another thing that gives you files to edit is a checkout. A checkout is
434
always associated with another branch. One of the purposes of checkouts is
435
to get multiple working trees for a branch. Another reason for checkouts is
436
to get access to the files in a branch without keeping a full copy of the
437
branch available locally. Getting a checkout looks like this::
439
% bzr checkout http://bazaar-ng.org/bzr/bzr.dev
442
Checkouts have several advantages and drawbacks. A checkout does not have
443
any RCS history as the history is stored in the branch for which a checkout
444
is assocated with. This behaviour results in two general rules:
446
1. checkouts take much less space than a full branch
447
2. checkouts are much faster if the branch is on a local filesystem.
450
437
Following upstream changes
451
438
==========================
453
You can stay up-to-date with the parent branch by "pulling" in their changes
440
You can stay up-to-date with the parent branch by "pulling" in their
458
After this change, the local directory will be a mirror of the source.
445
After this change, the local directory will be a mirror of the source. This
446
includes the ''revision-history'' - which is a list of the commits done in
447
this branch, rather than merged from other branches.
460
This command only works if your local (destination) branch includes only
461
changes from the parent branch and no commits of its own. Otherwise, the
462
branches are said to have ''diverged'', and they must be merged instead.
449
This command only works if your local (destination) branch is either an
450
older copy of the parent branch with no new commits of its own, or if the
451
most recent commit in your local branch has been merged into the parent
464
454
Merging from related branches
465
455
=============================
467
If two branches have diverged (both have unique changes) then **bzr merge**
468
is the appropriate command to use. Merge will automatically calculate the
469
changes that exist in the branch you're merging from that are not in your
470
branch and attempt to apply them in your branch. ::
457
If two branches have diverged (both have unique changes) then **bzr
458
merge** is the appropriate command to use. Merge will automatically
459
calculate the changes that exist in the branch you're merging from that
460
are not in your branch and attempt to apply them in your branch.
475
Conflicts during merge
476
======================
478
Sometimes two branches modify the same lines in the same files at the same
479
time. The result of this collision is called a "conflict". These conflicts
480
must be resolved by hand as Bazaar-NG can not tell which change you would
481
prefer to keep. You are, however, provided with some information which
482
makes the job easier for you to deal with.
484
The first thing that Bazaar-NG does is to merge in the parts that it can.
485
The parts that can not be merged are put into the file for you to decide
488
The second thing that Bazaar-NG does is to provide you with three extra
489
files for each file that is conflicted. The names of these files are the
490
same as the original filename with ".BASE", ".THIS" and ".OTHER" appended.
491
Each of these files serves a different purpose:
493
+------------------+-----------------------------------------------------+
494
| filename.BASE | filename as it looked back when filename was |
495
| | identical in both branches. |
496
+-----------------+------------------------------------------------------+
497
| filename.THIS | The version of filename for this branch. All of the |
498
| | parts of the merge with the other branch that can be |
499
| | merged from the other branch without conflicts are |
500
| | accepted. The parts which conflict are thrown away |
501
+-----------------+------------------------------------------------------+
502
| filename.OTHER | The version of filename for the other branch. All of |
503
| | parts of the merge from this branch that can be |
504
| | successfully merged are accepted. The parts of the |
505
| | merge which conflict are thrown away |
506
+-----------------+------------------------------------------------------+
509
For example, imagine that you and another developer were working on on a
510
simple branch that only contained hello.c. Both of you agree that saying
511
"Yo" to users is a little _too_ informal. Both of you also decide to fix
512
the problem at the same time, but take slightly different approaches. You
513
decide upon saying "Hi", while your compatriot decides upon a slightly more
514
formal "Hello". You both make the respective change and commit. Then, you
515
merge his change. The result would look something like this:
517
+----------------------+------------------------+
518
| hello.c.THIS | hello.c.THAT |
519
+----------------------+------------------------+
520
| | #include <stdio.h> | | #include <stdio.h> |
522
| | main() | | main() |
524
| | printf("Hi"); | | printf("Hello"); |
527
+----------------------+------------------------+
528
| hello.c.BASE | hello.c |
529
+----------------------+------------------------+
530
| | #include <stdio.h> | | #include <stdio.h> |
532
| | main() | | main() |
534
| | printf("Yo"); | | <<<<<<< TREE |
535
| | } | | printf("Hi"); |
537
| | | printf("Hello"); |
538
| | | <<<<<<< MERGE-SOURCE |
541
+----------------------+------------------------+
543
Your job as a developer is to decide which better. A multitude of options
544
exist for how to solve the conflict. Two of them are:
546
1. Decide whether you'd like hello.c.THIS, hello.c.THAT or hello.c.BASE.
547
Copy that one to hello.c.
549
1. edit hello.c and decide which part you wish to keep. Your solution
550
will be between the lines that say "<<<<<<< TREE" and "=======". His
551
solution will be between "=======" and "<<<<<<< MERGE-SOURCE"). Do not
552
forget to delete the markers too!
554
Bazaar also tracks which files conflicted during merge to prevent you from
555
accidentally committing the conflict markers to your branch. To tell
556
Bazaar-NG that you have fixed one of the conflicted files, run::
558
% bzr resolve hello.c
560
Using a program such as kdiff3, you can now comfortably merge them into one
561
file. To commit you have to rename it to the original basename and delete
562
the other two files. As long as there exist files with .BASE, .THIS or
563
.OTHER the commit command will complain.
467
If there is a conflict during a merge, 3 files with the same basename are
468
created. The filename of the common base is appended with .BASE, the
469
filename of the file containing your changes is appended .THIS and the
470
filename with the changes from the other tree is appended .OTHER.
471
Using a program such as kdiff3, you can now comfortably merge them into
472
one file. To commit you have to rename it to the original basename and
473
delete the other two files. As long as there exist files with .BASE, .THIS
474
or .OTHER the commit command will complain.
476
[**TODO**: explain conflict markers within files]
566
479
Publishing your branch
567
480
======================
569
You do not need a special server to publish a bzr branch. Generally
570
speaking, one can push a branch via sftp to a directory that is served via
571
apache. Bazaar-NG supports a variety of methods for reading and writing
574
Bazaar-NG can push branches via these methods::
575
1. sftp via ssh (the most common)
577
3. Any filesystem mounted via remote filesystem tools like NFS and Samba
578
4. The Canonical.com branch hosting service (via scoming soon)
579
5. Rsync (requires bzrtools plugin from http://bazaar-vcs.org/BzrTools)
581
Bazaar-NG can also read branches via a variety of methods::
583
1. Standard http, (E.g. Apache)
588
The most common approach is to push a branch via sftp to a place that is
589
served via SFTP. This usually looks something like::
591
* You have a branch in ~/somebranch
592
* You have a directory on /home/yourname/public_html on BigServer that
593
shows up as http://BigServer/~yourname
595
In cases such as this, you'll usually perform the following commands to
596
initially push your branch via rsync (which requires the bzrtools plugin)::
599
% bzr push yourname@BigServer:public_html/somebranch/
601
Other people can then access for your branch by doing the following::
604
% bzr merge http://BigServer/~yourname/somebranch
482
You don't need a special server to publish a bzr branch, just a normal web
483
server. Just mirror the files to your server, including the .bzr
484
directory. One can push a branch (or the changes for a branch) by one of
485
the following three methods:
487
* Rsync: rsync -avrz LOCALBRANCH servername.com/this/directory/here
489
(or any other tool for publishing a directory to a web site.)
491
* bzr push sftp://servername.com/this/directory/here
493
(The directory that must already exist)
495
* The push plugin that comes with BzrTools
added
removed
doc/tutorial.txt
