Ubuntu Wiki

Ubuntu Open Week - Version Control with Bazaar - Emma Jane Hogbin - Mon, Nov 3rd, 2008

(03:00:39 PM) emmajane: Hi everyone!
(03:00:56 PM) emmajane: In this next session I'm going to walk you through the very basics of setting up the world's best revision control system: Bazaar!
(03:01:14 PM) emmajane: Who's up for a little bit of version control?! :)
(03:02:08 PM) emmajane: This session has six parts: (1) A little bit about Bazaar, (2) Installing Bazaar, (3) Initializing a repository (aka Creating a time machine), (4) Going back in time, (5) Downloading files from Launchpad and (6) Resources.
(03:02:20 PM) emmajane: In the next session you will learn how to use Bazaar to maintain a package in Launchpad.
(03:02:29 PM) emmajane: I have the notes typed out if you are interested in reading ahead, please keep your questions to the topic at hand though, thanks!! http://pastebin.ubuntu.com/66913/
(03:02:42 PM) emmajane: Ok! Let's get started!
(03:02:56 PM) emmajane: Topic 1/6: A little bit about Bazaar
(03:03:06 PM) emmajane: Bazaar is a distributed version control system that Just Works. Bazaar adapts to the workflows you want to use, and it takes only a few minutes to try it out.
(03:03:19 PM) emmajane: Bazaar is used by all kinds of project teams to maintain all the changes that are made to the underlying code by each developer. In fact the code for the data base MySQL is stored in Bazaar! And Ubuntu is working towards putting 15,000 packages into Bazaar! These are HUGE projects!
(03:03:39 PM) emmajane: It can be used by real people too though. I like to think of myself as more of a "real person" than a "hardcore ninja developer." I use Bazaar because it's really good, but also because the support community is AMAZING. People have answered questions at all hours of the day in the IRC channel #bzr.
(03:03:55 PM) emmajane: Whether you're a hardcore ninja developer, or a real person, you can take advantage of version control for your work.
(03:04:01 PM) emmajane: (Apparently ninjas are real people too though.) ;)
(03:04:14 PM) emmajane: It can be useful to put all kinds of files under version control. For example: your configuration files, your resume, or any other kind of file that you might want to see a "historical" snapshot of.
(03:04:27 PM) emmajane: For example: I'm a freelance Web developer. I'm doing work on a client site and all of a sudden I get brand new files from the graphic designer that change everything. I could start a new folder, but that leaves a lot of junk lying around on my computer. Instead I use all the new files in my project (overwriting the old ones), but with Bazaar there is a secret "history" folder that allows me to go back and look at the old versions of the fil
(03:04:27 PM) emmajane: e whenever I want.
(03:04:55 PM) emmajane: I like to think of Bazaar as the biggest, baddest UNDO button my computer has ever known.
(03:05:01 PM) ***emmajane pauses for people to catch up. :)
(03:06:40 PM) emmajane: Topic 2/6: Installing Bazaar
(03:06:46 PM) emmajane: I'm going to assume that everyone is already using Ubuntu?
(03:07:17 PM) emmajane: We will be working from the command line for most of this session. I am very comfortable at the command line so if I go too quickly, please jump up and down and tell me! I have used the convention of $ to mean start typing a command. If you look at your command line you will see that it ends with a $. Mine looks like this:
(03:07:23 PM) emmajane: emmajane@gollum:~$
(03:07:30 PM) emmajane: If you are using GNOME you can open a new terminal window by navigating to:
(03:07:35 PM) emmajane: Applications (top left of your screen) -> Accessories -> Terminal.
(03:07:41 PM) emmajane: If you are using KDE you can open a new terminal window by navigating to:
(03:07:46 PM) emmajane: System -> Terminal Program (Konsole)
(03:07:54 PM) emmajane: If you are using a different desktop environment you are probably already a super 1337 haX0r that knows how to find a terminal window, but please let me know if you need more help!
(03:08:11 PM) emmajane: Let me know if you can't find a terminal window....
(03:09:01 PM) emmajane: Sounds like we're all good?
(03:09:18 PM) ***emmajane welcomes LarstiQ from #bzr :) (I told you they were helpful!! :) )
(03:09:48 PM) emmajane: Now that you are at the terminal window you will see something similar to my command line that I displayed above. We are now going to install Bazaar. I chose to do this from the command because that's where we'll be running the commands. You could also use the Synaptic Package Manager to do this installation.
(03:10:03 PM) emmajane: To install Bazaar we are going to use a package manager called apt-get. It install a package it uses the structure: apt-get install PACKAGENAME. You must be the super user of your system to run this program we will use the "sudo" command instead because it's faster and because this comic is funnier if you know about sudo:  http://xkcd.com/149/
(03:10:12 PM) emmajane: $ sudo apt-get install bzr
(03:10:36 PM) emmajane: You will be prompted for your password. If there are multiple accounts on your computer you may not be in the sudo group. You can switch to the root user if 'sudo' doesn't work for you.
(03:11:27 PM) emmajane: Let me know when you've successfully run that command.... or if you're having problems getting Bazaar installed...
(03:14:26 PM) emmajane: I've got a little bit more installation information, if you're not done yet, that's ok. You're not missing anything. :)
(03:14:26 PM) alucardni: ok, done
(03:14:27 PM) emmajane: Assuming that worked you should now have Bazaar installed on your system. You can test this with the following command:
(03:14:35 PM) emmajane: $ bzr
(03:14:41 PM) emmajane: You should get a list of Bazaar commands. Note: Bazaar is the name of the application and bzr is the actual command that you run.
(03:14:54 PM) emmajane: If you want to have a pointy-clicky browser to make these changes you can also install "Olive." This program has the package name: bzr-gtk. You can install it with the following command:
(03:15:00 PM) emmajane: $ sudo apt-get install bzr-gtk
(03:15:25 PM) emmajane: How's everyone doing so far? Ready to start taking snapshots of your files?

(03:16:09 PM) emmajane: Topic 3/6: Initializing a Repository (aka Creating a Time Machine)
(03:16:18 PM) emmajane: For the next part I want you to choose a directory that has files you *know* you should be keeping in better order. This might be an application that you've been hacking away on, or your resume folder, or whatever!
(03:16:26 PM) emmajane: We could also invent some files if you wanted to, but I think it's nice to work with files you know.
(03:16:35 PM) emmajane: Change directory to the folder that has the files you want to put under revision control. I am going to work in the folder that contains the files for the Web site riversideyarns.com. I use the following command to move to that directory:
(03:16:41 PM) emmajane: $ cd websites/riversideyarns.com
(03:16:54 PM) emmajane: Remember that you can use the tab button to finish typing each of the words. Type the first letter of the file name and then press the tab key. It will type the rest of the word for you. Of course if there are more than one files that start with the same letter you will need to type a few more letters before hitting tab again.
(03:17:31 PM) emmajane: Once you have changed to your working directory you can create a new "repository" of your files. A repository is a place where data are stored and maintained. This folder will no longer be a simple set of files. It will be an uber awesome time machine that lets you travel back in time to see old versions of your files.
(03:17:56 PM) emmajane: To start the time machine, I mean initialize the repository, use the following command:
(03:18:02 PM) emmajane: $ bzr init
(03:18:19 PM) emmajane: It's sort of like a magic trick because you won't see anything happen. This command creates a hidden time machine in your current directory.
(03:18:23 PM) emmajane: You can confirm it is there with the following command:
(03:18:30 PM) emmajane: $ ls -al
(03:18:36 PM) emmajane: Do you see the .bzr folder? That's your time machine!
(03:19:26 PM) kippy: does bzr init require sudo?
(03:19:32 PM) emmajane: kippy: nope.
(03:19:44 PM) emmajane: kippy: you get to be a regular person for this part. :)
(03:20:37 PM) emmajane: Has everyone got their time machine?
(03:20:42 PM) emmajane: I mean .bzr folder?
(03:21:04 PM) emmajane: For the next step you need to add all your files into the time machine. Use the following command:
(03:21:10 PM) emmajane: $ bzr add
(03:21:25 PM) emmajane: Bazaar will tell you that it has added the files to the time machine. Next you will need to lock and load the time machine. This allows you to jump back to this point in history. In Bazaar-speak this is referred to as "committing your changes."
(03:21:44 PM) emmajane: You must add a little message each time you commit your files. This lets you know what happened at this point in history (and makes it easier to jump back in time to exactly the right point). Be descriptive in your commit message. Use the following command:
(03:21:52 PM) emmajane: $ bzr commit -m "Adding files to the time machine for the very first time."
(03:23:49 PM) emmajane: You can now edit your files and continue "committing" changes. Remember Bazaar is like an undo button. You want to be able to "undo" small changes, and not lose a bunch of work because you undid too much.
(03:23:58 PM) emmajane: Try editing one of your files and committing the changes. Once you've edited a file you can commit the change into the revision history with:
(03:24:01 PM) kippy: difference b/w add and commit?
(03:24:30 PM) emmajane: kippy: "add" tells bzr about the files. You only use it once to add each new file.
(03:24:57 PM) emmajane: (or you can add files in bulk, like we just did)
(03:25:43 PM) emmajane: commit, on the other hand, is how you mark each set of changes so that you can jump back to that point in history.
(03:25:56 PM) emmajane: kippy: does that make sense?
(03:26:31 PM) emmajane: Try editing one of your files and committing the changes. Once you've edited a file you can commit the change into the revision history with:
(03:26:32 PM) emmajane: $ bzr commit -m "A descriptive message with a summary of the changes you made."
(03:27:01 PM) emmajane: I would like everyone to try editing one or two files in the directory they're in and "committing" the changes.
(03:27:21 PM) alucardni: emmajane: done
(03:27:27 PM) emmajane: The next step is to learn how to go back in time, but you need to have edited the files to believe that you really are going back.
(03:27:47 PM) emmajane: If you do a few edits and a few commits you will have more to look at in your logs (which is the next step).
(03:28:06 PM) emmajane: I'll give everyone three minutes to do this.
(03:28:19 PM) emmajane: This would be a good time to ask questions if you have some at this point as well.
(03:29:56 PM) ciprian_topala: does bazaar commit too newly created files that didn't exist at the initial commit?
(03:30:46 PM) emmajane: ciprian_topala: you have to explicitly add any new files. Otherwise Bazaar will ignore them.
(03:31:12 PM) emmajane: Ok. That's the three minutes.
(03:31:18 PM) emmajane: Hopefully everyone's done some editing by now?
(03:31:43 PM) emmajane: Topic 4/6: Going back in time
(03:31:51 PM) emmajane: Mistakes happen. What if you need to UNDO some changes you've made? You can go back in time and restore your files to a previously saved version.
(03:31:59 PM) emmajane: To undo mistakes there are two commands you need to know: revert, and uncommit. But before we start undoing things, let's read the history books to see where we want to travel back in time to....
(03:32:05 PM) emmajane: $ bzr log
(03:32:30 PM) emmajane: This command lets you see the revision history for the commits you've made to your repository. if you are working with text files you can also look to see what the EXACT changes were between two versions of a file with the "diff" command. To compare from a previous version to the current one, use the following command
(03:32:38 PM) emmajane: $ bzr diff -r# FILENAME
(03:32:43 PM) emmajane: Replace the # with the "revno" from your log.
(03:32:53 PM) emmajane: In the text that is spit out look for the lines that have - and + at the beginning of the lines. The - means the line was removed; the + means the line was added.
(03:33:18 PM) emmajane: (This won't work as expected for binary files such as images and OpenOffice.org documents.)
(03:33:50 PM) ***emmajane pauses to give people a chance to read their history books... I mean logs.
(03:34:23 PM) emmajane: I'm going to answer some questions while you're working on that.
(03:34:31 PM) emmajane: rgreening       QUESTION: Is there a qt/KDE equivalent to the bzr-gtk?
(03:35:04 PM) emmajane: Hm. Not that I'm aware of. Does anyone else know?
(03:35:25 PM) cyphermox: that was brought up in the -chat channel. it seems there is qbzr
(03:35:43 PM) emmajane: excellent!
(03:35:48 PM) emmajane: Kolyan_ufalug_  QUESTION: What current status of bazaar speed? When my familiar developers looked at last time bazaar they have said it was not very fast in comparsion to other systems. I know that this is not critical in small projects but big projects also interest.
(03:36:32 PM) emmajane: Kolyan_ufalug_: it's fast enough for MySQL.... specific benchmarking questions could be directed to the mailing list though. I believe it depends on the complexity of the project.
(03:37:00 PM) emmajane: presi   QUESTION: I feel confortable with GNU Arch, but seems a bit unmantained so I'm thinking about moving to bazaar, can I work with bazaar in the same way as with arch, that is with working trees separate from repositories?
(03:37:26 PM) LarstiQ: Yes, you can with lightweight checkouts.
(03:37:33 PM) emmajane: presi: I think you mean branches? Yup, you can do branches in Bazaar. You'll learn that in the next session.
(03:37:46 PM) emmajane: moreati QUESTION: bzr add and bzr commit resulted in the same messages (added foo.bar) is the commit necessary or does bzr add do an implicit commit?
(03:38:02 PM) emmajane: moreati: Yup, the commit is necessary. This locks your changes into Bazaar.
(03:38:16 PM) kippy: why so many version control systems like SVN, GIT and BAZAAR ? which one is more advantageous in what kind of situations?
(03:38:37 PM) emmajane: kippy: Why so many Linux distros?
(03:39:00 PM) kippy: why?
(03:39:04 PM) emmajane: kippy: each has advantages for different projects. Personally I go with the system that has the best and most active community.
(03:39:11 PM) LarstiQ: To explore different approaches, mainly.
(03:39:15 PM) emmajane: Ok. Back to the classs. :)
(03:39:36 PM) emmajane: This command lets you see the revision history for the commits you've made to your repository. if you are working with text files you can also look to see what the EXACT changes were between two versions of a file with the "diff" command. To compare from a previous version to the current one, use the following command
(03:39:41 PM) emmajane: $ bzr diff -r# FILENAME
(03:39:47 PM) emmajane: Replace the # with the "revno" from your log.
(03:39:53 PM) emmajane: (I think this might be review?)
(03:40:00 PM) emmajane: In the text that is spit out look for the lines that have - and + at the beginning of the lines. The - means the line was removed; the + means the line was added.
(03:40:09 PM) emmajane: (And this should be new...)
(03:40:10 PM) emmajane: To compare two versions in history use the following command:
(03:40:15 PM) emmajane: $ bzr diff -v -r#..# FILENAME
(03:40:20 PM) emmajane: Note the two dots between the revision numbers. These are important.
(03:40:30 PM) emmajane: To move back in time to the last commit (i.e. UNDO only the current changes) use the command "revert." This will take you back to the previously committed changes. This will change all files that have been updated since the last commit.
(03:40:35 PM) emmajane: $ bzr revert
(03:41:09 PM) emmajane: To go one step further back and undo the last commit of your files, use the "uncommit" command like so:
(03:41:15 PM) emmajane: $ bzr uncommit
(03:41:24 PM) emmajane: If you want to go back to a very specific version number, you can use the revert command as well as the revision number:
(03:41:29 PM) emmajane: $ bzr revert -r #
(03:41:50 PM) emmajane: Remember to COMMIT your changes when you go back in time. You must "save" your new location in time by committing the new snapshot into your revision history. Once you've restored your files to the right version, use the commit command like this:
(03:41:56 PM) emmajane: $ bzr commit -m "Undoing bug fixes from previous revision. Reverts files back to feature set YXZ."
(03:42:55 PM) emmajane: <mbt> emmajane: QUESTION: Is there a uncommit like thing that preserves version history, say, for branches that are always-public?
(03:43:31 PM) emmajane: I'm pretty sure that the history isn't deleted, it's the file that's returned to that state...
(03:43:36 PM) LarstiQ: well
(03:43:38 PM) emmajane: someone else might be able to correct me on that though.
(03:43:51 PM) LarstiQ: Once you use uncommit (or rebase) the old revision is destroyed and you can then make a new one.
(03:43:58 PM) emmajane: <alucardni> QUESTION: We have to revert and uncommit to make changes to a previous version of a file?
(03:44:08 PM) emmajane: alucardni: Nope. Choose right tool for the job.
(03:44:12 PM) emmajane: Do one OR the other.
(03:44:15 PM) LarstiQ: mbt: so doing that will impact other people's ability to interact with your branch
(03:44:38 PM) emmajane: There is more information in the Bazaar User Manual at: http://doc.bazaar-vcs.org/latest/en/user-guide/index.html#undoing-mistakes
(03:44:45 PM) LarstiQ: (and in #bzr :)
(03:45:07 PM) emmajane: (That's just more information for "UNDO" althoug the full user manual is there)
(03:46:02 PM) emmajane: <weboide> emmajane: uncommit seems to delete history
(03:46:16 PM) emmajane: weboide: correct. uncommit completely UNDOES the last commit.
(03:46:21 PM) emmajane: As if it NEVER HAPPENED!
(03:46:29 PM) emmajane: (How cool would it be to have THAT in real life?!)
(03:46:45 PM) emmajane: revert is a little more polite. :)
(03:47:01 PM) emmajane: There is more information on the differences in that link I gave you above.
(03:47:24 PM) emmajane: What you've had so far are the basics for working with your own files.
(03:47:45 PM) emmajane: Hopefully people have had a chance to edit their own work and see the log files and revert changes and basically muck around a bit.
(03:48:28 PM) LarstiQ: To stress that, using uncommit on a branch you have published is not recommended.
(03:48:34 PM) emmajane: The next part will set you up for Part Two of Bazaar in the next session.
(03:48:41 PM) LarstiQ: But you _can_ do it if you have to.
(03:48:48 PM) emmajane: Topic 5/6: Working with Launchpad
(03:48:56 PM) emmajane: There is one last thing I want to show you today. And that's how to get a repository from Launchpad. In the next session you will learn all kinds of fantastic things that you can do with real code, but first I want to show you how to get that code into your computer.
(03:49:03 PM) emmajane: The first thing I want you to do is change directories into a play area. This might be in your home directory, or on your desktop. To change to your home directory use the following:
(03:49:09 PM) emmajane: $ cd
(03:49:15 PM) emmajane: To change directories to your Desktop use the following command:
(03:49:21 PM) emmajane: $ cd ~/Desktop
(03:49:50 PM) emmajane: Here are two different ways to grab a repository from Launchpad. You can either use the URL for the project, **or** use the Launchpad project name. You don't need to do both. Let's take a look at the two commands:
(03:49:55 PM) emmajane: $ bzr checkout https://launchpad.net/terminator
(03:50:01 PM) emmajane: $ bzr checkout lp:terminator
(03:50:07 PM) emmajane: Both of these commands will do the same thing. The "lp" version will (obviously) only work for projects that are available in Launchpad. But the first version will work for any URL on the internet that has a .bzr folder in the same directory. (You can probably see the advantages and disadvantages of this!)
(03:50:45 PM) emmajane: Choose one method now and download the "terminator" project.
(03:51:12 PM) emmajane: In other words perform a "checkout" using either the URL for the project *or* the lp project name.
(03:51:14 PM) emmajane: It may take a little while for the terminator project to download. You will be using these files for the "advanced" Bazaar session coming up next.
(03:52:27 PM) emmajane: <gQuigs> QUESTION: is there a shortcut (like lp) for gnome projects?
(03:52:44 PM) emmajane: gQuigs: As far as I know there is not. But, again, I've been wrong before. ;)
(03:53:01 PM) james_w: gQuigs: there is a plugin to provide it floating around
(03:53:01 PM) jcastro: most of the time bzr checkout lp:nameofgnomeproject will work
(03:53:48 PM) james_w: the main problem is that GNOME only uses bzr for a few things at the moment, but as jcastro said launchpad has bzr mirrors of most of the projects
(03:54:07 PM) emmajane: While you're downloading the project (you saw how easy it was compared to CVS?!) I'm going to plunk in some resources to wrap up this session, but please start asking me questions as well!!
(03:54:17 PM) emmajane: Topic 6/6: Resources
(03:54:23 PM) emmajane: There are lots of resources to learn more about Bazaar. I personally use the following a lot:
(03:54:30 PM) emmajane: The Bazaar Web site. http://bazaar-vcs.org/ Here you will find good documentation as well as useful plugins. I use the "upload" plugin for my Web work as well as bzr_push_and_update.
(03:54:37 PM) emmajane: The built-in documentation is really good too. You can check the "man" pages with $ man bzr  OR get a list of all the commands in bzr with: $ bzr --help commands
(03:55:19 PM) emmajane: And that's all I've got.
(03:55:25 PM) emmajane: Not bad timing, eh? :)
(03:55:47 PM) james_w: "bzr help topics" is good too
(03:56:06 PM) james_w: and #bzr and bazaar@lists.canonical.com of course
(03:56:13 PM) presi: very basic but usefull class