Test Drive

Thank you for trying BitKeeper! The following test drive will walk you through the installation and use of BitKeeper in the day-to-day life of an average Windows developer. This test drive does not cover the more advanced topics of distributed source control but is instead meant as an introduction to life in BitKeeper on Windows.

This test drive covers the following topics:

• Installing BitKeeper
• Setting Up a Work Environment
• Pulling Changes from a Parent
• Making Changes
• Viewing Changes
• Committing Changes
• Viewing Revision History
• Pulling and Resolving a Conflict
• Committing a Merge
• Pushing Changes to a Parent

The test drive makes it easy for you to follow along with what you should be doing by providing instructions in separate command boxes. These boxes will show you exactly what to do at each step of the test drive. The prompts you follow will be different depending on how you're running the test drive. They will look like this:

BitKeeper GUI prompt: When you see this, follow the instructions in the BitKeeper GUI

Windows GUI prompt: When you see this, follow the instructions in Windows Explorer.

Command Prompt: When you see this, follow the instructions at the open Command Prompt.

Note that any time you see a Windows command prompt throughout this test drive, the contents of that window may not look like what you see in your window. The output from BitKeeper changes from version to version, so what you see may not be exactly what is pictured in the test drive. As long as things don't look like an error, you should be ok.

If you're ready to get started, let's move on.

First Step: Installing BitKeeper on your system

Installation

So you're ready to try out BitKeeper? First things first, let's get it installed on your machine! If you have not downloaded BitKeeper already, you should request an evaluation key and download information now.

Once you've downloaded the software, continue through the installation steps.

Double click the installer to launch it, and a window will first pop up telling that it is unpacking. As soon as that's done, the installer should pop up and get us rolling.

Click through the welcome screen, and the first thing you're presented with is the license screen. This is where you'll enter your demo license. Don't worry though. You don't have to type the whole thing. You can copy-and-paste it into the fields, or you can load it from a file. Once you've entered your license key, the next screen asks you to accept the BitKeeper End User License before proceeding with the installation. Just click the Accept button once you've read the agreement and click Next to move on.

The next thing we're presented with is where to install BitKeeper. You can choose any location you want, but if you're not sure, it's best to just let it install to the standard Program Files directory.

Next we see a screen offering a few optional install pieces that we want. The two options on this screen are checked by default, and we want to leave them that way. If you don't run Visual Studio and don't plan to, you can uncheck the Enable Visual Studio integration button, but we definitely want to keep the Windows Explorer integration enabled. This enables the BK plugin for Windows Explorer, and it's what the entire rest of this test drive is based on.

Once you've selected your options, just click Next to move forward and start the installation.

Once the installation is complete, we should be ready to roll!

Next Step: Get a demo repo cloned to your machine

Setting Up the Demo Repo

Now that we have BitKeeper installed on your system, we're ready to try it out.

This section of the test drive will cover:

• Cloning a remote repo to your machine
• Cloning a local repo to make a working copy

Next Step: Cloning a remote repo to your machine

Cloning a Remote Repo

Now that you've completed the installation step of the test drive, we're ready to setup a repository for our demo.

First, we'll start by creating a simple directory to work in. For the purposes of our test drive, we're going to simply use C:\BK as our directory. This is the directory we will use to hold the repositories we clone and work in while we're working in BitKeeper. You can create whatever directory you like for your test drive.

Navigate to C: Right-click on the white background of the Explorer window. Click New -> Folder. Rename the newly-created folder BK.

Now that we have our directory setup, the first thing we'll do is clone a repository. Let's open Windows Explorer and navigate to our directory. Again, you can see in the screenshots that we're using C:\BK as our directory. Yours may be different.

Right-click on the white background of your Explorer window. Click BitKeeper -> Clone a Repository...

A small dialog will popup asking for some information about what you want to clone and where you want to put it. For the purposes of this test drive, we're just going to clone the demo repository.

Check the Get the demo repository box. Click the Clone button.

After clicking the Clone button, you will see a command prompt window pop up and some data start flying by. Don't worry. That's normal. While the Windows Explorer plugin makes it easy to navigate BitKeeper in the Windows world, it is still a command line tool for many of its functions. You will see a command window popup like this from time to time, but it's usually only there to show you what is going on as BitKeeper performs the requested action.

Once the clone is complete, the command window will be left open to show you what happened and/or to let you perform further command line actions. Your window should look something like this, but it may not be exact depending on your version of BitKeeper.

Close the command prompt window.

Now your directory should look something like this:

If the clone doesn't work for some reason, you might need to tell BitKeeper about your HTTP proxy if you are behind one. You can do this with:

Open a command prompt. set http_proxy=http://your_proxy.your_company.com:80/

For more information about methods of accessing repositories, see the url manual page in the helptool. You can launch helptool like this:

Right-click anywhere in Explorer. Click BitKeeper -> Help... Click More Help...

Next Step: Make a copy of this repo by cloning it

Cloning a Local Copy

You've just cloned a remote repo to your local system, and we're ready to work! Notice that BitKeeper has placed an overlay icon on the folder to show that this is a BitKeeper repository. When working within the Explorer plugin, BitKeeper uses several icon overlays to give you an idea of what you're looking at with a glance.

Now, this demo repo was cloned from bkbits.net, and we don't have permission write back to the parent repository, so the next thing we want to do is make another clone of our new repo to the same directory so that we can make some changes.

Right-click on the white background of your Explorer window. Click BitKeeper -> Clone this Repository...

You'll see the familiar clone dialog pop up. Notice that the dialog has already filled in the name of the repo we are cloning and a suggestion for the copy of the repo. We'll just keep the defaults for now and make a new bk_demo_copy directory to play in. You will see the command window fly by again as the repo is copied. Once it's done you can close the command window, and your directory should look like this:

You should now have a directory with two repos: bk_demo and bk_demo_copy. Each repo knows about where it came from and who its parent is. bk_demo_copy knows that bk_demo is its parent, and that's where it will pull its updates from and send its changes to. bk_demo knows that http://bkdemo.bkbits.net/bk_demo is its parent, and that is where it will pull updates from.

Next Step: Pulling changes from a parent

Pull Changes from a Parent

So we just finished setting up the demo repo, and now we're ready to start working in our new copy!

First things first. Let's try and pull changes from our parent to make sure we have the latest code. A clone will automatically pull the latest revision of the code, and we haven't made any changes to our parent, but we're going to do it anyway just to see what it looks like.

Right-click on the bk_demo_copy folder. Click BitKeeper -> Pull Changesets from Parent.

A dialog will popup asking where we want to pull from. It will populate with the value of our parent repo by default, and that's where we want to pull from, so we'll just leave that in there.

Click the OK button.

Another command window will pop open and try to pull any new changes from our parent. In this case it won't find anything because we haven't made any changes in the parent. Close the command window, and let's try and pull changes from another parent that does have some changes in it.

Right-click on the bk_demo_copy folder. Click BitKeeper -> Pull Changesets from Parent. For Target URL use: http://bkdemo.bkbits.net/bk_demo1 Click the OK button.

You should see another command window pop up as BitKeeper pulls any changes from that repository. This time we should see some changes come through. Specifically, we see that a change has been made to e2fsck/region.c. You will see some other stuff in the command window that gives you a little more information about what just happened. The window should look like this, but it may not match exactly what you see:

If we look at this a little closer, BitKeeper is telling us what just happened. We see that BK is pulling two files: ChangeSet and e2fsck/region.c. The ChangeSet file is a file you will see with every change. It is the main file that tracks change sets within BK, and it is updated each time a change is committed. The second file is our actual code change. We see BK run the resolver and apply our changes to the changed files and then run a consistency check to make sure that data integrity is correct.

Next Step: Make some changes of our own

Making Changes

Now that we've pulled in some changes, we're ready to talk about making changes of our own.

This section of the test drive will cover:

• Checking out files
• Modifying and creating files
• Viewing Changes in difftool
• Checking in your changes

Extra Credit:

• A word on checkout modes in BitKeeper
• A few comments about comments

Next Step: Checking out files

Checking out files

Well, now that we've pulled in some changes, we're ready to make some changes of our own! Let's dig into that bk_demo_copy repo and see what all we have.

Double-click the bk_demo_copy folder.

Hmm. Some files with big green buttons on them and a subdirectory. Ok, so the files with the big green buttons on them are files that are under BitKeeper control. The green icon with a minus sign is showing us that these files are checked out in read-only mode. Let's go look in that e2fsck subdirectory and see what's in there.

Double-click the e2fsck folder.

You can see that the files in this directory are also marked with the green minus icon, telling us they are marked read-only, so the first thing we want to do is mark the files for editing so that we can start making some changes.

Right-click on the white background of your Explorer window. Click BK Edit Files...

If no files are selected, this action means to checkout all of the files in the current directory for editing. Now our directory should look like this:

Ok! The green check marks say that these files can be edited, so we're ready to make some code changes! If you want to learn more about why we need to checkout files for editing, see the note on checkout modes for extra credit.

Next Step: Modifying and creating files in a repo

Modifying and creating files

Now we're ready to make some changes. Let's open up recovery.c in your favorite editor and change all instances of jread to Jread.

Open recovery.c in your favorite text editor. Find and replace all instances of jread with Jread. Save recovery.c and exit the editor.

As soon as we save the file, the icon in the Explorer changes to a red minus icon.

This is the BK plugin telling us that this file has been modified and needs to be checked in. Which we'll get to in a minute. First let's make another change. This time, let's create a completely new file in our directory. Let's create a new file called foo.c and just put a little something in there. It doesn't matter what.

Create a new text file called foo.c.

Now we see that BK has marked our new file with a blue question mark, like this:

This is the BK plugin telling us that it doesn't know anything about this file. We don't need to tell BitKeeper about any new files we create unless and until we're ready to add them to our repository. You can happily work along in new files and add them to your repository when you're ready along with any other changes.

Next Step: Viewing our changes

Viewing Changes

So now that we've made a few changes to our repo, let's take a look at those changes and see what all we've done.

Right-click on the white background of your Explorer window. Click BK Diff Directory...

This will bring up the BK difftool that shows us side-by-side differences in BitKeeper-controlled files. It will load showing the first changed file and centered on the first change in that file. Like this:

So, where did foo.c go?! Well, BitKeeper doesn't know anything about foo.c so there's nothing to diff. Don't worry though. When it comes time to commit, BitKeeper will tell us there is an extra file there it doesn't know about and give us the option to include it then.

Next Step: Committing our changes

Committing Changes

We've made some changes to our repo, and we've looked at those changes in the difftool, now we're ready to commit our changes!

Right-click on the white background of your Explorer window. Click BK Checkin Tool...

This will launch the BitKeeper checkin tool that we will use to walk through, comment our file changes and then commit our changeset to the repository.

So, we can see in our file list that citool has found the changes we made to recovery.c as well as the extra foo.c file we created. Citool has already selected the first modified file under BK control (which is recovery.c) and is showing us the changes made to the file in the lower window. Citool doesn't need to show us the entire contents of the file or its changes, it's showing us just the differences between our current, working version and the last version committed in the repo.

We can see all of our changes to recovery.c right there, and the diffs look good, so let's give it a comment. For a little extra reading, you can read about our thoughts on commit comments. You can enter any comment you want for the changes, and notice that the icon on the file shifts to a green check to show us that this file is now set to be included in our commit.

Give recovery.c a comment. Select foo.c in the file list.

When we click on foo.c, citool sees that this is a new file and doesn't know anything about it, so it just dumps the file contents to the lower window.

Click the icon next to foo.c.

We see that citool has now marked this file to be included in our commit and has entered a default little comment about the file being new. You can change the comment if you like, or you can just leave the default new message in there.

We have two files ready to be committed, now all we need is a ChangeSet comment.

Click on the ChangeSet file

You should see the files we're ready to commit down in the lower window along with their per-file comments. This gives you an idea of what is about to be committed with this changeset. Remember, this comment is more a summary of the overall change, so just a few lines describing what the change is about should do. You can comment it with anything you like for a test drive here. Once you give the changeset a comment, you should see the green check next to the ChangeSet file, and you should now see the Commit button over on the right is ready to go. It should look something like this:

Click the Commit button twice

Now all the magic starts happening. The citool will walk through and check in each of the files and then commit the whole thing as a changeset to our repository. Once the commit has completed with no problems, the citool will automatically close. Now we can see in the Explorer that all of our files are green again. Notice that foo.c and recovery.c are now marked as read-only again. This is, again, because our repo is in checkout: get mode. When a commit is done, each file in the cset is checked in and committed and then checked back out in whatever the default mode is.

So, we've pulled in a change from a different parent, and now we've gone and done a little work and made our own change.

Next Step: Take a look at the history of our changes

Using Revtool

We've just committed some changes to our repo, so now let's take a look at the revision history of our repo through revtool. This section will cover:

• Launching revtool in a repo
• Looking at a changeset through revtool
• Looking a specific file in a changset in revtool

Next Step: Launching revtool in a repo

Launching Revtool

Right-click on the white background of your Explorer window. Click BitKeeper -> Revision Tool...

The revtool will pop up with the revision history of our repository. When revtool is called on a repo without a specific file, it will show the history of the entire repo, which is all of the changesets that have been committed. We're not looking at per-file commits here, we're looking at things from the perspective of the csets. This is where your changeset comments come in handy for browsing back through the history. Let's take a look at the revtool and what all of that stuff means.

The revtool is arranged with a revision graph on the top and then a description window on the bottom. When revtool is run on a repository, the default configuration is to show the last 50 csets along with their descriptions down in the bottom window. You should see the previous commits in the repo as well as the new commit that we just made to the far right on the graph. You can see down in the bottom window that our last commit is on top of the history.

Next Step: Take a look at a changeset in revtool

Looking at a Changeset

Click the last commit in the revision graph.

When we select a revision in the graph, we see all of the comments for that cset in the lower window. We can see the overall changeset comment we entered as well as the per-file comments for each file in the cset. Here we can see the new foo.c file we added and its comment as well as the recovery.c file we changed and what our comment on that was. The comments tell us what was changed at a glance, but what if we want to see what was actually changed in the code?

Next Step: Look at one file's changes in our cset

Looking at a file

Click the line below e2fsck/recovery.c in the text window.

You should see another revtool fire up with just that file and its history. Now we are looking at revtool from the perspective of a single file, not the repo as a whole.

It should look something like this:

When revtool is launched on a single file within a repo, the default is to show an annotated view of that file at its latest version. This shows us the full contents of the file with each line annotated by the revision it was first introduced as well as who made the change. We can see from our recovery.c file that we are currently at revision 1.7, which was our recent commit. This view shows us the entire file, but we really just wanted to see what was changed between our recent version and the previous version. For that we just hit d to bring up the diff view.

Type d

You can also click nodes in the graph to see diffs of a file. Select the first revision in the graph by clicking the left mouse button and then select any other revision by clicking the right mouse button. Revtool will show you the differences between those two versions. Typing d will automatically select the previous revision and diff the two, but the two revisions don't have to be adjacent. You can select any two revisions with your mouse and see the differences between them.

Revtool will automatically select the previous version and then diff that with the currently-selected version. It should look like this:

Ahh, there we are! Now we can see the diffs of what was changed in our last commit. Yup. Just as I thought. We changed jread to Jread.

Next Step: Pull some other changes that need a merge

Merging Changes

We've just finished up a quick overview of changeset history by using revtool, and we saw how easy it was to pull in changes from another repo that merged without a problem. But now let's see what it's like to pull in changes that don't merge so nicely. This section will cover:

• Pulling and Resolving a Conflict
• Merging a file
• Committing a merge

Next Step: Pulling and Resolving a Conflict

Pulling and Resolving a Conflict

So, here we are. We've changed some code in our repo and made a small commit with our changes. We can see from the history what our changes look like, and now we're ready to move on and keep working. But now we find out that we need to pull some code from another repo. Someone else has done some work, and we need to merge their changes into our work before we keep going.

Most often when changes are pulled into your repo, BitKeeper will handle auto-merging the changes without a hassle. But sometimes you pull changes from another repo that touch the same files in the same areas as ones you have already changed. This creates a conflict that BitKeeper doesn't know how to solve, so it relies on you to merge the conflict by hand. Let's pull in a change that will cause a conflict and see how that is resolved.

Right-click on the white background of your Explorer window. Click BitKeeper -> Pull Changesets from Parent...

You'll see the familiar little pull dialog, but this time we're going to pull from http://bkdemo.bkbits.net/bk_demo2. Put http://bkdemo.bkbits.net/bk_demo2 into the Target URL box and click OK. The command window fires up again to do the pull, only now we see something like this:

BK has run into a conflict while merging the new changes, and it doesn't know how to resolve it, so it has dropped us into the resolver. It's waiting on us to decide what to do. If we press Enter at this prompt, we're given a list of available commands.

Next Step: Merge it all together

Merging a file

We've pulled in a cset with a conflict, and now we need to merge the changes. In our case, we want to step into the 3-way merge tool and do our merge graphically from there.

Type f and hit Enter.

BK will fire up the fm3tool for us to do the merge. Let's take a look at this thing:

Whew! That's a lot of stuff for one window! Let's start at the top and work down. The top row shows the two changeset comments side by side so that you can see what you are working with. The row below that has two text windows showing a side-by-side diff of the changes. We can see that the fm3tool has already moved us to the first conflicting change in our merge, and the conflicting pieces are highlighted in orange.

Down in the lower window you can see the result of our merge, and it currently has a big chunk marked UNMERGED. This is showing us the first conflict and where in the file it needs to be merged. We'll merge our changes by selecting the pieces we want from each cset. This is also where we can jump into the file and edit the changes by hand if we want, but we won't be doing that today.

So, someone has changed the same jread lines that we changed in our commit. We need to look at the two changes and figure out which one is the one we want. Our changes are on the left, and the changes we're pulling in and trying to merge are on the right. It looks like our changes are the ones we want, so we want to execute the merge such that our changes are taken over the new changes we're pulling in.

Let's pick a change on the right first to see what happens.

Click the right window on the line with jREAD highlighted in orange.

You'll see that line appear in the lower window where the UNMERGED block used to be. We've now resolved the first conflict, but we didn't actually want that line, we wanted the other line.

Type u.

This will undo our previous change and move the conflict back to an UNMERGED state.

Click in the left window and click the line with Jread highlighted in orange.

That puts our change down in the lower window in place of the UNMERGED block.

That looks good. We can also see in the lower right window that our first conflict has now been resolved. Only two more to go!

Click the right arrow button or type ].

The fm3tool will jump to the next unresolved conflict in the file. Again it looks like we want our changes, not the incoming ones.

Click the left window and click the line with Jread highlighted in orange. Click the right arrow button or type ] to move to the last conflict. Click the left window and click the line with Jread highlighted in orange.

That should be our last conflict. We're done!

Click File -> Save or type s to save our changes and exit.

Next Step: Commit our merged changes

Committing a Merge

We've just pulled and merged a conflict from another parent repo, and now we're ready to commit our merge. BitKeeper has dropped us out of the fm3tool and back into the resolver which looks something like this:

Type C and hit Enter.

This will commit our merged changes. The citool that we've now seen before will pop up to show us our merged changes. We can see the changes we made to recovery.c, and it looks like the ChangeSet already has a comment. Let's make a comment for recovery.c. You can use the comments to explain what you did with the merge, or you can just use something like "Merged."

Select the ChangeSet file.

BitKeeper has already filed in a simple comment stating what happened. We pulled bk_demo2 into our bk_demo_copy and merged the two. You can take the time to write in your own merge comments here, but the standard merge comments are useful for noting the difference between a merge and a regular commit when looking through the change history.

Click the Commit button twice.

The resolver finishes up the pull, does an integrity check, and then it's done. You can close the command window once you've read what happened.

Last Step: Push our changes back to our parent

Pushing Changes Back to the Parent

We committed a merge to our repo, and now we're finally ready to push our changes back upstream to our parent repo. But before we do that, let's make sure our parent doesn't have any changes we need to pull first. BitKeeper will not let you push your changes to a repo that has any changesets you don't already have, so we need to check for any changes before we push. Note that BitKeeper will stop you from doing the push if there are changesets you need to pull, so you don't absolutely have to check for them, but it's good practice here.

Right-click on the white background of your Explorer window. Click BitKeeper -> View Remote Changesets...

A command window will pop up to list any remote changes in the parent that we don't already have in our repo. Of course, we already know that our parent doesn't have any changes, so we didn't need this step, but now we can see, for sure, that there are no changes in the parent:

BitKeeper shows us the changes command being executed and the parent repo we're checking against followed by the list of changesets on the remote side if there are any. We can see here that there are no changes in the parent that we need to pull. Close the command window, and let's check and see what changes we're about to push to our parent.

Right-click on the white background of your Explorer window. Click BitKeeper -> View Local Changesets...

Another command window will open up listing the changesets we have that our parent does not have yet. It should look something like this, but it may not be exact depending on your version of BitKeeper:

Ok. We have several changesets that we've made that need to be pushed back to our parent. Let's take a look at them. The first two changes were pulled in when we pulled from . The third changeset is the one change we made locally where we modified recovery.c and added the new foo.c file. The final change is the merge we did. Notice that BitKeeper has marked this changeset as a MERGE changeset.

Those changes look good. We're ready to push them back to our parent.

Right-click on the white background of your Explorer window. Click BitKeeper -> Push ChangeSets to Parent.

The familiar dialog pops up asking us where we want to push our changes, and our original clone parent is the default.

Click OK.

The command window pops up and starts doing its thing. We see from the output that BK has pushed our changed files back to our parent, and then it ran a consistency check on the remote repo to make sure everything is ok. Everything looks good.

Well, it looks like that's it for our Windows Test Drive!

Now that you have an idea of how BitKeeper works and how to interact with BitKeeper on Windows, you should poke around at some of the rest of the options in the Explorer plugin and see what all you can do. Open up the helptool and read through some of the docs if you want to learn more about some of the commands you do.

Right-click anywhere in Explorer. Click BitKeeper -> Help... Click More Help...

If you run into any problems, drop us a line at support@bitmover.com and let us know. We're happy to help!

Extra Credit Work

This section is not part of the basic testdrive but is meant to expand on a few of the topics mentioned throughout it.

• A word on checkout modes in BitKeeper
• A few comments about comments

Checkout Modes

A quick word about checkout modes.

By default, BitKeeper operates in a "clean" checkout mode. This means that all files must be explicitly checked out in either read-only or read-write mode. You can specify that a particular repository should be in "checkout: get" or "checkout: edit" mode as well as specify in your own configuration what the default mode should be.

Available Checkout Modes

checkout: get
In get mode, BK will automatically checkout each file in read-only mode (using bk co ) after doing a checkin.

checkout: edit
In edit mode, BK will automatically checkout each file in read-write mode (using bk edit ) after doing a checkin.

checkout: last
In last mode, BK will preserve the state of the file before checkin.

checkout: none
In none mode, BK will clear the file after doing a checkin. This is the default.

The repositories we are using for this test drive have been marked "checkout: get" which means that all files within the repo will be checked out in read-only mode by default. That's why we have to first checkout the files for editing before we can make any changes to them. In most cases you will usually just checkout the files you plan to modify for editing and leave the rest as read-only as it makes it really easy to see what you're changing from the Explorer. If you were to run in "checkout: edit" mode, all of the files would already be in the directory and writable after a clone, and you could skip the step of having to check them out.

File and ChangeSet Comments