Let’s start by making a copy of the demo repository by cloning it from the source URL to a local directory bk_demo. Later we’ll check-in a change to a source file and pull in another clone that has a conflicting change.

The clone, like many bk operations, shows a progress bar as the command runs with an OK at the end to indicate success.

Your clone should look something like this:

Now we’re ready to work! Our demo repo was cloned from bkbits.net, and we don’t have permission to write back to the parent repository Our next step is to make a second clone so that we can make some changes that we can push back to our first clone.

You should now have two directories with two repos: bk_demo and bk_demo_copy. When you clone, the cloned repository remembers its parent. So 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 by default. bk_demo knows that http://bkbits.net/u/bkdemo/bk_demo is its parent.

Let’s dig into that bk_demo_copy repo and see what we have. There is a C source file named ntp_io.c in the ntpd directory that we’ll work with.

We’re good to go — when we cloned the demo repo, BitKeeper automatically checked out this file with read-write permissions, because the default mode for this repo is checkout:edit. Sometimes very large repos use a checkout:get mode which speeds up commits considerably but which would require us to tell BitKeeper which files we intend to change. For all but the largest repos, checkout:edit works fine. To learn more, see the note on checkout modes for extra credit.

Now we’re ready to make a change. Let’s open up ntp_io.c in your favorite editor and add something to the printf at line 531.

Now 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.

Now that we’ve made a few changes to our repo, let’s take a look at those changes and see what we’ve done.

The following command shows us which files we’ve modified so far:

The bk command by itself is a swiss-army-knife kind of tool to list files under BK control.

The -Uc option lists changed files. That is, files that are different from the checked-in version.

So, where did foo.c go?! Well, BitKeeper doesn’t know anything about foo.c yet, so it’s not considered to be a modified file — it’s an extra.

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. Here’s the command to show the extra files:

Of course, you can combine the options:

Let’s look at our local diffs to verify that we changed the printf correctly:

The -U means to work over all user files in the repo and the -c restricts that to only the changed files.

Sometimes it’s easier to view the diffs graphically:

This brings up the BK difftool that shows us side-by-side differences in BitKeeper-controlled files. It starts on the first change in the first changed file and lets you navigate from there by typing "n" or "p" to move forward or backward through the diffs:

We’ve made some changes to our repo, and we’ve looked at those changes. Now we’re ready to commit our changes!

Let’s launch the BitKeeper checkin tool, known as citool, which makes it easy to see our file changes and commit them to the repository. It lists each file we changed (or added) and lets us write per-file comments, then it groups all those files together into what’s called a changeset (or cset for short). You can think of a cset as an indivisible unit of change you want to share with other people.

We can see in our file list that citool has found the changes we made to ntp_io.c as well as the extra foo.c file we created. Citool shows us the changes 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 our change to ntp_io.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. 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.

When we click on foo.c, citool sees that this is a new file and doesn’t know anything about it, so it just prints the file contents to the lower window. 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 file message in there.

We have two files ready to be committed, now all we need is a ChangeSet comment. Click on the ChangeSet file and you’ll see this:

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 a summary of the overall change, so it should be just a few lines describing what the change is about. Since this is just an example, you can comment it with anything you like.

Once you give the changeset a comment, you should see the green check next to the ChangeSet file, and you should now see the Checkin button has changed its text and is now labeled Commit. It should look something like this:

Click the Commit button twice to create a changeset. 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, citool will automatically close.

Let’s say you were remotely logged into your workstation via ssh and had no graphical display. No problem — it’s easy to create changesets completely from the command line. Here’s how we would have done it without running citool.

First, we tell BitKeeper to create deltas for each file we modified (and this includes telling BK about extra files we added). The -y option is how we specify comments.

Now we have two deltas pending — they haven’t yet been committed to the repo — so let’s create a changeset out of them by running the commit command:

That’s it! There now is a new changeset in our repo and its revision number is 1.3498.

A very common thing to do in bk is to view a summary of the history from the perspective of the changesets. Looking only at the csets and not the per-file comments gives a higher-level view of what’s going on. This is where your changeset comments come in handy for browsing back through the history.

Let’s take a look at revtool and understand what it’s showing us. Revtool is arranged with a revision graph on the top and then a description window on the bottom. When revtool is given no arguments, it runs over the entire repository, showing the last 50 csets along with their descriptions down in the bottom window. You should see your new commit to the far right of the graph. You can see down in the bottom window that our last commit is on top of the history.

You can very quickly get this summary, minus the graph, from the command line using the bk changes command:

Your bk changes command will print more than this, displaying a page a time, until you quit it. This command has lots of ways of displaying its output so that you can see just what you want; run bk help changes for a glimpse of what you can do.

Go back to revtool, or start it up like you did above if you need to, then click the last commit in the revision graph and you’ll see this:

When we select a revision in the graph, we see all of the comments for that changeset 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.

It’s easy to get this information from the command line, by specifying which cset revision you want details for and specifying -v to get some per-file details:

Here we can see the new foo.c file we added and its comment as well as the ntp_io.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? Now click the line below ntpd/ntp_io.c in the text window and you’ll 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. 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 ntp_io.c file that we are currently at revision 1.404, 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.

Now we are seeing the diffs of what was changed in our last commit. We added a field to a printf.

You can also click nodes in the graph to see diffs of a file.

You can select any two revisions with your mouse and see the differences between them. 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.

That’s it for revtool. You can press quit in the revtool windows.

Diffs are also easy to get from the command line. Just use two -v's to bk changes:

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 auto-merge 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 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 from another version of our demo repo that will cause a conflict and see how that is resolved.

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.

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 press Enter and BitKeeper will fire up fm3tool to do the merge.

Let’s take a look at fm3tool:

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 fm3tool has already moved us to the conflicting change in our merge, and the conflicting pieces are highlighted in yellow.

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 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 printf that we changed in our commit. We need to look at the two changes and figure out how to reconcile them. 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 0x highlighted in yellow.

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. So type u to undo that and move the conflict back to an UNMERGED state. Now click in the left window on the line with our changes to the printf highlighted in yellow.

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

We’re almost done! If there had been other conflicts, we would navigate to each of them resolve each one in the same way.

Now type s to save changes and exit the fm3tool.

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 to the resolver prompt. Now type C and press Enter to commit the merge.

This will commit our merged changes. Citool will pop up to show us our merged changes. We can see the changes we made to ntp_io.c, and it looks like the ChangeSet already has a comment. Let’s make a comment for ntp_io.c. You can use the comments to explain what you did with the merge, or you can just type "Merged".

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. So it’s customary to leave these defaults comments at the beginning. You add aditional comments at the end.

Click the Commit button twice and then we’re done resolving the conflict.

A quick word about checkout modes.

By default, BitKeeper operates in a "edit" checkout mode. This means the files are editable and ready to go. This is the default for most users and should probably remain unless you have larger repos and are experiencing some performance issues. In that case, you might consider "checkout: get".

Available Checkout Modes

A quick word on comments. Unlike some source control management systems, BitKeeper requires per-file and per-cset comments. That is, each file in a changeset needs a comment as well as an overall comment for the changeset itself. Generally speaking, your per-file comments are meant to describe the actual change to that file and maybe some detail about what was changed. The changeset comment is more a summary of the overall change being committed. You will see more of why this is a good thing when we start looking back at the revision history through revtool.