A Revision Control System is a suite of programs that allows developers to coordinate and chronicle their work. Each change or revision to any of the files being controlled by such a system can be tracked by date, developer or comment. The set of files being controlled can also be "rewound" or rolled back to a previous state. In addition, RCS's have mechanisms to prevent collisions and conflicts -- either by preventing more than one user from editing any file at any given time, or by indicating differences between two conflicting versions of the same file, and offering methods to merge files and resolve conflicts.
cd ~/.bazaar
nano bazaar.conf
# Last modified by Kevin Cole
<me@some.domain.tld> 2006.02.08
#
# Built following the directions found in the bzr tutorial
# at http://bazaar.canonical.com/IntroductionToBzr
#
[DEFAULT]
email=Kevin Cole
<me@some.domain.tld>
cd ~/
mkdir -p public_html/bazaar
Each bzr repository consists of the files in the project you're working on,and a hidden directory named .bzr . This directory is used to keep a history of all the differences between various revisions, and other info that bzr needs to keep track of your universe.
Therefore, separate projects need separate directories in which they can each keep their very own .bzr directory
If you're beginning your own project, you initialize the .bzr directory with the command:
mkdir ~/public_html/bazaar/project
cd ~/public_html/bazaar/project
bzr init
On the other hand, if you're not starting from scratch, you'll create a branch, of someone else's repository which creates the directory you need. You will need the URL of the repository you want to branch from.
cd ~/public_html/bazaar/
bzr branch
http://dc.ubuntu-us.org/~kjcole/bazaar/gin
ls
cd gin
At this point you should be able to begin work on the actual code.
| 1. | bzr init | # this command bzr init creates in the current directory the .bzr subdirectory. This is used to keep a history of all the differences between various revisions, and other info that bzr needs to keep track of your project. |
| 2. | bzr commit -m "comment" | # commits your changes and adds a comment. Leaving off the -m "comment" will crank up your favorite editor and allow you to leave a more detailed comment. |
| 3. | bzr status | # lists which files have been changed or added since the last time you committed your changes |
| 4. | bzr add | # adds any files of status "unknown" into the repository. |
| 5. | bzr mv oldfilename newfilename | # move file from one place to another within the repository IMPORTANT: Use this in place of a simple mv command, so that bzr knows a file has been renamed. Otherwise, bzr thinks an old file has been removed and a new one added. |
| 6. | bzr ignore filename | # logically enough, this tells bzr to ignore that file.
NOTE: This creates a file in the current directory named .bzrignore, which has one regular expression per line for what to ignore. |
OK, so now you've been existing in this vacuum where you've been happily modifying, adding and religiously committing your changes without a care as to what others are doing. Now, the package god wishes to see what you've been up to. He or she "pulls" your changes (as well as the changes of others editing in their own private universes), twiddles bits, sanctions everyone's work and commits what becomes the latest and greatest version... Now it's time for you to pull from that central, master version, which will incorporate any approved changes made by others into your version. In effect, both the lead developer and you are regularly downloading updates from each other.
NOTE: If you chose a default editor other than vi, bzr
leaves droppings after a commit (without the -m)
in the form of a temporary file named
bzr_log.pseudo-random-string~
which you should remember to get rid of manually ASAP.
Also, with regard to signing commits... If you wait until you've made several commits, and then sign, you will need to type in your passphrase a gazillion times -- once for each commit you've made. But wait, we have more to say about signed committs.
DISCLAIMER: I haven't worked with any other RCS and am also relatively new to bzr. So far, I haven't really done anything collaboratively with it.
Most of the burden for resolving conflicts, I hope, will fall to the lead developer. That person will be deciding which changes from multiple developers on a project to keep or reject. Drones, slaves and peons should refrain from making new commits while the project god is ruminating over all the branches. That said, it's a nice theory, but may not work in practice.
Should the unthinkable happen, and you end up pulling changes from somewhere that conflict with your own, bzr will offer some suggestions on what to do.
ls
TODO
...
bzr pull
Inventory OK.
bzr: ERROR: These branches have diverged. Try merge.
bzr merge
bzr: WARNING: Text conflict in TODO
1 conflicts encountered.
ls
TODO TODO.BASE TODO.OTHER TODO.THIS
...
At the beginning of the session, there was a file named TODO. bzr could not successfully pull the changes from elsewhere, because it would conflict with changes in the current branch you're working on, and it suggested you try a merge. The bzr merge also had problems. It altered the contents of TODO and produced three spin-off files. The results are the following four files:
At this point, what I do is examine all the conflicting files, edit whichever one involves making the fewest changes, and change the name of that file to whatever the merged file should have been named. When that's done, issue:
bzr resolve TODO
bzr commit
I'm not certain that the above is the proper way to do it, but it appears to work. The bzr resolve command gets rid of the .BASE, .THIS and .OTHER files for you.
There's a lot more that bzr can do, and many of the commands have optional arguments. The curious should look at the man pages as well as the documents referred to at:
In particular, the two documents from Canonical listed there are quite useful. Kevin Cole's TiddlyWiki, Logs and IRC conversations should also be considered.
One command area we did not include in this short presentation is:
bzr sign-my-commitsCryptographically Assured Repositories are now implemented in the Ubuntu universe as of Feisty Faun. Thus it will be necessary to digitally sign your code if you want to play well with others. For help with GPG and digital signatures, see:
The author wishes to express much thanks to: Kevin Cole of the DC Ubuntu Local Community Group (LOCO) and James Blackwell, the Ambassador of bazaar, for both their documentation and their patience with me. Also, Martin Pool's documentation was rather helpful in getting this started. For references to their work, see the Resources section above.