Bazaar from the Ground Up
Whether you're working alone or as part of a team, you should use version control to safeguard your work. This tutorial shows you how easy it is to create a new Bazaar branch and start tracking versions of files.
Bazaar is a version control system that developers use it to manage source code. It serves two important purposes:
You could try to do this manually by constantly making copies of your project:
Not only does this take up a lot of disk space, but it is error prone and it won't help you collaborate with others. Using a version control tool like Bazaar is a better way to solve this problem.
While graphical front ends are available, the most basic way of working with Bazaar is via the command line. The name of the Bazaar command is bzr:
Bazaar -- a free distributed version-control tool http://bazaar.canonical.com/ Basic commands: bzr init makes this directory a versioned branch bzr branch make a copy of another branch bzr add make files or directories versioned bzr ignore ignore a file or pattern bzr mv move or rename a versioned file bzr status summarize changes in working copy bzr diff show detailed diffs bzr merge pull in changes from another branch bzr commit save some or all changes bzr send send changes via email bzr log show history of changes bzr check validate storage bzr help init more help on e.g. init command bzr help commands list all commands bzr help topics list all help topics
The bzr command alone doesn't do anything beyond showing you all the common subcommands you might want to invoke. You can see the same menu by calling bzr help, and you can get help about a specific subcommand using bzr help <subcommand>.
Before we go any further, let's introduce ourselves to Bazaar:
Now that Bazaar knows who we are, it will tag all of our changes with this user name. Of course we can't make any changes until we have a branch to work in. What exactly is a branch? Let's pause for a moment and learn a few core concepts in Bazaar.
The smallest building block in Bazaar is a revision. A revision, conceptually, is a snapshot of your files at a point in time. For example, if you added a paragraph to a text file in one version and removed it a later version of that file, Bazaar would record these versions of the same file as separate revisions.
A repository is a structure that stores revisions. It's sort of like a revision library. If we want to retrieve an old version of file, Bazaar would search the repository for the revision that contains the old version and use it to restore the file.
Revisions in a repository are related to other revisions. Namely revisions have parents— one revision follows another. As you alter your files, you'll record snapshots as successive revisions in your repository. This stream of revisions is called a branch. A repository contains every revision of a project, and a branch is a specific thread of revisions through the repository. There can be many branches that fork off and join back together, representing the individual histories developers create as they work independently then integrate their work. Put simply, a branch is your history.
All work in Bazaar happens in the context of a branch.
Okay, there's just one more thing to wrap your mind around, and that's the working tree. This one is easy— the working tree is just your files! All the files and directories in your project that are versioned constitute the working tree.
A picture is worth 1024 words. Let's put all these concepts together:
This picture sort of looks like a New York City subway map. The repository is what holds all the revisions. Each revision is a snapshot of the file system. A branch is sort of like a train line— it's an ordered history of revisions. Finally, the working tree is a versioned directory that is associated with a revision, usually the latest one.
Now that we understand the core concepts in Bazaar, let's create a new branch to work in. Assume we have an existing project in a directory named "MyProject". That's a great name for a project! I'm already excited. Let's enter that directory in a terminal and put it under version control:
Created a standalone tree
It doesn't look like much, but we've just created a new branch and a repository to hold that branch. Don't believe me? The init operation created a new repository stored in a subdirectory called .bzr:
. .. .bzr Gemfile Gemfile.lock README.rdoc Rakefile app bin config config.ru db lib log public test tmp vendor
The .bzr directory is our repository. It will track all our revisions and our branch. Treat this directory like a museum— feel free to look, but don't touch anything.
Right now, our branch is empty— there are no recorded revisions. Heck, right now Bazaar doesn't even know which files we want to keep track of! Let's tell Bazaar we'd like to keep track of everything:
adding Gemfile adding Gemfile.lock adding README.rdoc adding Rakefile adding app adding bin adding config adding config.ru adding db adding lib adding log adding public adding test adding tmp adding vendor adding app/assets adding app/controllers adding app/helpers adding app/mailers ... adding vendor/assets/javascripts adding vendor/assets/stylesheets
By default, bzr add is going to recursively add all files and directories in our project. Unlike some other version control systems, Bazaar versions directories in addition to files, so it adds them too, even if they're empty. We're not done yet, though. The bzr add command marks all of these files and directories to be tracked, but we have to commit this change to the branch before these files will be tracked. The act of adding all these files is the first change we want to record as a revision.
When we issue the bzr commit command, Bazaar will open our favorite editor and show us a list of what we're committing to the repository. It will also let us enter a message so we can remember what we were thinking when we added the changes.
Create initial version of MyProject.
-------------- This line and the following will be ignored --------------
added:
Gemfile
Gemfile.lock
README.rdoc
Rakefile
app/
app/assets/
app/assets/images/
app/assets/javascripts/
app/assets/javascripts/application.js
app/assets/stylesheets/
app/assets/stylesheets/application.css
app/controllers/
app/controllers/application_controller.rb
app/controllers/concerns/
app/helpers/
app/helpers/application_helper.rb
app/mailers/
...
vendor/assets/javascripts/
vendor/assets/stylesheets/
Everything above the dashed line is the message we've typed into the editor to describe this change. Everything below is a record of what we're committing. When we save this document, the commit command finishes:
Committing to: /home/fmccann/MyProject/ added Gemfile added Gemfile.lock added README.rdoc added Rakefile added app added bin added config added config.ru added db added lib added log added public added test added tmp added vendor added app/assets added app/controllers added app/helpers added app/mailers ... added vendor/assets/javascripts added vendor/assets/stylesheets Committed revision 1.
Revision 1! We've just added our first revision. Just to be sure, let's take a look at Bazaar's log:
------------------------------------------------------------ revno: 1 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:44:24 -0500 message: Create initial version of MyProject.
Hey, that's a lot of information. The revno is the number of the revision— 1. Bazaar knows who the committer is because we introduced ourselves with bzr whoami. The branch nick is the name of our branch. Bazaar named the branch after our project directory. Finally, we see the timestamp of the revision and the message we wrote when we committed the change.
Now that our files are under version control, let's try changing one of the files:
This is my project readme file.
This is my awesome project readme file.
Our change isn't recorded as a new revision until we commit the change to the branch. If we execute bzr commit, Bazaar will take a snapshot of the working tree and notice that README.rdoc has changed:
Just as before, Bazaar opens an editor so we can review the changes to the working tree and enter a commit message:
Updated readme file to reflect the awesomeness of the project. -------------- This line and the following will be ignored -------------- modified: README.rdoc
As we expected, Bazaar noticed that README.rdoc has been modified. We enter the commit message above the line to describe the change, and when we save the message, the commit command finishes:
Committing to: /home/fmccann/MyProject/ modified README.rdoc Committed revision 2.
Revision 2! Our branch is filling up with work. Let's take a look at the log again:
------------------------------------------------------------ revno: 2 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:46:44 -0500 message: Updated readme file to reflect the awesomeness of the project. ------------------------------------------------------------ revno: 1 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:44:24 -0500 message: Create initial version of MyProject.
By default, bzr log shows the most recent revision first.
The reason we'd use a version control tool like Bazaar is to make our lives easier. So far, all we're doing is giving Bazaar constant updates as to what we've been working on. It might feel like working for a micro-manager who asks you to keep a log of every task you did today and how many minutes each one took. Unlike the manager who loves creating busywork, there's a reason we keep telling Bazaar about our changes. Let's say we do something stupid:
This is my awesome project readme file.
You know what would make this application better? More XML.
Let's not stop with just changing the readme file. Let's do some real damage:
This is really bad. We've lost some important source code and we've deleted all of the configuration. I have to think we need that for our application to work. I sure hope you use one of those newfangled cloud backup services and backs up every half second, because those files are gone.
Remember when I said that one of the jobs of a version control system is to remember every version of a file? Bazaar remembers every snapshot we've committed. That means we can restore the state of the working tree, or any single file in the tree, to a previous state:
M README.rdoc N app/controllers/application_controller.rb N config/ N config/application.rb N config/boot.rb N config/database.yml N config/environment.rb N config/environments/ N config/environments/development.rb N config/environments/production.rb N config/environments/test.rb N config/initializers/ N config/initializers/backtrace_silencers.rb N config/initializers/filter_parameter_logging.rb N config/initializers/inflections.rb N config/initializers/mime_types.rb N config/initializers/secret_token.rb N config/initializers/session_store.rb N config/initializers/wrap_parameters.rb N config/locales/ N config/locales/en.yml N config/routes.rbMyProject fmccann$ ls README*
README.rdoc README.rdoc.~1~MyProject fmccann$ cat README.rdoc
This is my awesome project readme file.MyProject fmccann$ cat README.rdoc.~1~
You know what would make this application better? More XML.
Now we're not complaining that committing is busywork anymore. Committing is awesome. We can rollback the changed files in the working tree to their last recored state (or any recorded state) with a single command. By default, bzr revert rolls back all the changed files in the working tree, but you can use it to selectively rollback individual files as well. The bzr revert command makes a backup of all modified files by default, just to be safe.
Notice above that the files listed by bzr revert command are prefixed by letters. The letters show the action taken to restore the working tree. The actions you might see are new (N), modified (M), renamed (R), and deleted (D).
If you find yourself going down a rabbit hole while working on a particular piece of code or an entire module, it's easy to get back to where you started. The general pattern is:
Even a simple project can have lots of files, and as you can see, the state of the working tree will change as you work. It's tough to remember all the changes you've made while you're feverishly trying to wedge in a new feature before the end of the week because Phil in sales promised a potential client that the application could import legacy Lotus 1-2-3 files. It gets hard to remember what changed or if you made new files that should be added to the branch.
Bazaar has the answer for us— the bzr status command. This command will show you the state of your working tree since the last revision in your branch. To make things interesting, let's create a file and delete a file:
While we're at it, let's make some more changes to the README.rdoc file:
This is my awesome project readme file.
This is my awesome project readme file.
Ray, when someone asks you if you're a god, you say "YES"!
Now that we have some changes in our working tree, let's see what bzr status tells us:
removed: public/favicon.ico modified: README.rdoc unknown: newfile.txt
Bazaar lets us know that we've removed favicon.ico and that we've made modifications to README.rdoc. It has no information about newfile.txt. This is because we've never placed it under version control with the bzr add command, so this is a new or "unknown" file as far as Bazaar is concerned. Bazaar can detect a number of changes:
Let's take a look at README.rdoc. Bazaar tells us that we've altered this file since the last time we committed changes to our branch, but what exactly changed? Bazaar has a command to help us out- bzr diff:
=== modified file 'README.rdoc' --- README.rdoc 2015-12-10 22:46:44 +0000 +++ README.rdoc 2015-12-10 22:49:22 +0000 @@ -1,1 +1,2 @@ -This is my awesome project readme file. +This is my awesome project readme file. +Ray, when someone asks you if you're a god, you say "YES"!
This output will look very familiar if you're used to the diff command on Unix-like systems, but if you're not, the key thing to know is that lines that start with a minus shows removed text and lines starting with a plus show added text.
We removed the favicon.ico file. If this was a mistake, we can always recover the file using bzr revert. However, if we really want it gone, we can just commit the changes and it will be removed— Bazaar will honor an external tool removing the file.
There is also a command in Bazaar to explicitly remove a file. This is useful if we add a file with bzr add then change our mind:
adding newfile.txtMyProject fmccann$ bzr remove newfile.txt
removed newfile.txt (but kept a copy: newfile.txt.~1~)
Notice that bzr remove is a bit safer than just deleting the file. The bzr remove command removes the file from the branch. It also removes the file from the working tree. If the file could be recovered with a bzr revert command, Bazaar will simply remove the file. However, if the file has not yet been recorded, like newfile.txt, Bazaar will remove the file, but it will also make a backup copy by default to make sure we could possibly recover the contents of the file.
Okay we made some changes. We added a file, newfile.txt, then removed it. What's the state of the working tree?
removed: public/favicon.ico modified: README.rdoc
That makes sense— favicon.ico is still scheduled to be removed and README.rdoc is still modified. The newfile.txt file was added, then removed. Since it was never committed to any revision, it's like it never existed (though our backup newfile.txt.~1~ will hang out until we trash it). Let's commit these changes into a new revision:
Committing to: /home/fmccann/MyProject/ modified README.rdoc deleted public/favicon.ico Committed revision 3.MyProject fmccann$ bzr log
------------------------------------------------------------ revno: 3 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:53:23 -0500 message: Remove the favion.ico and offer some good advice for dealing with other dimensional beings in the readme file. ------------------------------------------------------------ revno: 2 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:46:44 -0500 message: Updated readme file to reflect the awesomeness of the project. ------------------------------------------------------------ revno: 1 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:44:24 -0500 message: Create initial version of MyProject
All of our changes, including removing favicon.ico from the branch, have been committed as a new revision. Notice that this time we entered the commit message directly with the -m option rather than using an external editor. Either way is acceptable; you can use an editor or just enter the message as part of the command. You can always use bzr help to see all the options that can be used with any command.
Sometimes as we develop code, we change the metaphors that we work with. Let's add a new class to our project:
class ThreadItem < ActiveRecord::Base
validates :title, length: { maximum: 128 }
end
We're happy with it, so let's add it to our branch.
unknown: app/models/thread_item.rbMyProject fmccann$ bzr add
adding app/models/thread_item.rbMyProject fmccann$ bzr commit -m"added a class to model Thread Items"
Committing to: /home/fmccann/MyProject/ added app/models/thread_item.rb Committed revision 4.
Now that we're thinking about it, "Thread Item" is sort of a bad name for this class. Maybe a better metaphor is simply "Message". At this point, Bazaar knows there's a file in the project called thread_item.rb, but we can tell it that we'd like to change it's name. So, let's modify the source code, then tell Bazaar what we're up to:
class ThreadItem < ActiveRecord::Base
validates :title, length: { maximum: 128 }
end
class Message < ActiveRecord::Base
validates :title, length: { maximum: 128 }
end
app/models/thread_item.rb => app/models/message.rbMyProject fmccann$ bzr commit -m"refactored ThreadItem to Message"
Committing to: /home/fmccann/MyProject/ renamed app/models/thread_item.rb => app/models/message.rb Committed revision 5.
Bazaar has a command that looks like the basic Unix mv command, but what makes this version special is that the history of the file is preserved:
------------------------------------------------------------ revno: 5 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:55:38 -0500 message: refactored ThreadItem to Message ------------------------------------------------------------ revno: 4 committer: Fred McCann <fred@bzrinit.com> branch nick: MyProject timestamp: Tue 2015-12-10 17:54:56 -0500 message: added a class to model Thread Itemsmodels fmccann$ bzr revert message.rb -r4
R app/models/message.rb => app/models/thread_item.rbmodels fmccann$ ls -l
concerns thread_item.rbmodels fmccann$ bzr revert thread_item.rb
R app/models/thread_item.rb => app/models/message.rbmodels fmccann$ ls -l
concerns message.rb
As you can see, when we get the history of message.rb, Bazaar knows the file used to be called thread_item.rb, and we see the original revision. If we revert to revision 4, Bazaar changes the name of the file to thread_item.rb. When we revert to the current version, it changes it back to message.rb. This means we don't have to worry about how we'll refactor code in the future— Bazaar will keep up with us, preserve the history accurately, and be able to reproduce any old versions correctly.
Bazaar is really good at keeping track of all our files, even through renames and reorganizations. However, sometimes we'd like Bazaar to not track specific files. Let's say that we're testing our application and it's written a log:
development.logMyProject fmccann$ bzr status
unknown: log/development.log
We really don't want logs under version control. Logs aren't source code or assets— they're just generated files, and tracking them will add noise to all our revisions. Luckily, we can tell Bazaar not to care about them:
added: .bzrignore
We used bzr ignore to tell Bazaar to ignore any files in the log directory that end with the extension ".log". Notice when we checked the status of the working tree, the log file is no longer listed. However, we do have a new file called .bzrignore.
log/\*.log
If we take a look at the contents of this file, we'll find that the it contains the pattern we added. Any files or patterns listed in this file will be ignored by Bazaar. You can append new patterns with the bzr ignore command, or if you prefer, you can edit this file directly to add and remove patterns. Once created, Bazaar tracks this file like any other, so all your ignore settings are versioned by Bazaar! Let's commit the change:
Committing to: /home/fmccann/MyProject/ added .bzrignore Committed revision 6.
We're up to six revisions now! That's a whole lot of history. At this point, we might forget what the contents of files used to look like in the past. If we wanted to view the contents of the old versions of the README.rdoc file, we could use bzr revert, but that would overwrite the contents of the file in the working tree. We could also use bzr diff, but that would show us differences between revisions of the file, not just the contents. Bazaar has a command that will just show us the contents of a file:
This is my awesome project readme file. Ray, when someone asks you if you're a god, you say "YES"!MyProject fmccann$ bzr cat README.rdoc -r2
This is my awesome project readme file.MyProject fmccann$ bzr cat README.rdoc -r1
This is my project readme file.
The bzr cat command works a lot like the regular Unix cat command. What's different is that you can specify a revision (with the -r option) and see what the contents were in that snapshot. If you'd like to just see the contents of a file, use bzr cat. Of course if you want to see what's changed, let's say between revisions 1 and 2, you can always use bzr diff:
=== modified file 'README.rdoc' --- README.rdoc 2015-12-10 22:44:24 +0000 +++ README.rdoc 2015-12-10 22:46:44 +0000 @@ -1,1 +1,1 @@ -This is my project readme file. +This is my awesome project readme file.
With bzr cat to view files, bzr diff to compare files, and bzr revert to rollback to previous versions, you have a host of tools to work with your history.
Whew! We've come a long way. At this point you've seen the basic Bazaar operations. However, there is one more thing we're going to cover. We saw there are a bunch of ways of accessing the historical contents of your files. You could bzr cat to view an old version of a file. You can also use bzr diff to see what has changed. You can use bzr revert to overwrite the contents of a file with an older version. There is one more command that interacts with history— bzr update.
The commands bzr cat, bzr diff, and bzr revert let use work with historical versions of files, but they don't change the revision of the working tree. The last revision we committed was revision 6, and that's the latest revision of the working tree. While we generally keep the working tree associated with the latest revision, it's possible to rewind the working tree to an older revision:
-D .bzrignore R app/models/message.rb => app/models/thread_item.rb All changes applied successfully. Updated to revision 4 of branch /home/fmccann/MyProject
We've now been whisked back in time by Doc Brown and his bzr update command, which oddly enough he built out of a DeLorean. The working tree has been rolled back in time to revision 4:
Note that update always affects every file because it operates on the entire working tree. At this point, all of the files in our working tree look exactly the way that they did when we were on revision 4. We can get up-to-date with the most recent revision by running bzr update again.
+N .bzrignore R app/models/thread_item.rb => app/models/message.rb All changes applied successfully. Updated to revision 6 of branch /home/fmccann/MyProject
Now we've zoomed forward in time, and Biff Tannen isn't married to our Mom anymore. Mission accomplished— the working tree is now pointing at the latest revision again.
This may appear to work the same way as bzr revert, but you can think of our branch history as a train track with a bunch of stations we can stop at. When we run bzr update, we're moving the train to a different station. The working tree has been moved to a specific revision.
Generally, we want to stay at the latest revision because that's where we want to append new revisions. When we execute bzr revert, our metaphorical train doesn't go anywhere— we're still at the last station. We're just took the old contents of the files and dumped them into the current working tree.
You've learned the basics of version control with Bazaar from the ground up. There's still more to learn, but you now know how to: