Test drive

Thank you for trying BitKeeper!

The following demo will walk you through:

• Installing BitKeeper
• Creating your own workspace (cloning a repository)
• Browsing the history of the repository using bk revtool
• Searching, reviewing, and debugging
• Updating a repository
• Viewing the updates
• Making your own changes
• Merging your work with another person's work

You will need to type some commands and run some graphical tools. You will see prompts like this:

Command-line prompt: When you see this, type it in the shell.

Graphical prompt: When you see this, do it in the BitKeeper GUI.

Graphical prompt for Windows: When you see this, do it in the Windows GUI.

The demo was designed to be done in under 30 minutes.

Installation

In this section you will install the BitKeeper product.

If you have not downloaded BitKeeper you should request an evaluation key and download information now.

Once you have downloaded the software, continue with the installation directions for your operating system.

Unix

The image you download is an executable file and your license keys are imbedded in it. In case your browser did not preserve the permissions, do:

chmod +x installer_binary

Then run the installer:

./installer_binary

The default is to run the graphical installer. To run the command-line installer, set the destination directory on the command line:

./installer_binary destination_dir

Windows

The image you download is an executable file and your license keys are embedded in it.

Double-click on the x86-win32 icon. You can safely use the defaults for all prompts.

Once BitKeeper is successfully installed, open a cmd window to run the demo:

Start -> run -> cmd

Mac OSX

The image you download is an executable file and your license keys are embedded in it. You will need to run the executable from a terminal window. In case your browser did not preserve the permissions, do:

chmod +x installer_binary

Then run the installer:

sudo su - cd download-dir ./installer_binary

When prompted, enter your own password. The default is to run the graphical installer. To run the command-line installer, set the destination directory on the command line:

./installer_binary destination_dir

Cloning a repository

Cloning is the term we use to describe the process of getting a personal workspace. Your workspace is your copy of both the source code and the revision history. You browse, modify, and check in changes to your workspace.

In the cloning section you will:

• Clone a demo repository from bkbits.net to your local machine; this repository will act as the "server" repository.
• Clone a workspace from the "server" repository you cloned from bkbits.net.

Go to a directory or folder of your choice.

mkdir BK cd BK bk clone http://bkdemo.bkbits.net/bk_demo my_parent

This creates a complete copy of the workspace in BK/my_parent.

If it doesn't work, you might need to tell BitKeeper about your HTTP proxy, which you can do by

# shell export http_proxy=http://your_proxy.your_company.com:80/ # cshell setenv http_proxy http://your_proxy.your_company.com:80/ # Windows cmd.exe set http_proxy=http://your_proxy.your_company.com:80/

For more information about methods of accessing repositories see the manual page

bk helptool url

Try this now and go to the next page after it is completed.

Cloning a child

Because the demo does not allow you to push changes back to bkbits.net, you need to clone again so that you have a local parent and child. This also demonstrates same file system clones.

bk clone my_parent bk_demo

You should now have a directory with two subdirectories: my_parent and bk_demo. There is a recorded relationship to the parent repositories. bk_demo knows that it gets updates from and sends updates to my_parent and my_parent knows it gets updates from and sends updates to http://bkdemo.bkbits.net/bk_demo.

Using bk revtool

There are ways to browse the repository both graphically and via the command line. The following example shows you how to browse a repository and file history using the graphical revision history browser, bk revtool.

Repository history is grouped by changesets. A changeset is a grouping of one or more changes to one or more files, and it is what is propagated between BitKeeper repositories. Changesets are stored in a revision controlled file named ChangeSet and can be browsed graphically. To do so:

cd bk_demo bk revtool

When in bk revtool, do:

Click on Select Range. Click on All Changes.

Things to notice:

• invoking bk revtool with no file argument displays the history of the entire repository, which is contained in the ChangeSet file.
• the top window displays boxes representing changesets containing the name of the person who made the changeset and the changeset revision. Tagged changesets are highlighted with a yellow box.
• the bottom window displays changeset information.

Repository history

Left-click on the box that says "tytso 1.111" .

The bottom window contains the comments for the changed files as well as the changeset comments.

Left-click on rev 1.111. Right-click on rev 1.114 (Cmd-click on Macintosh).

The bottom window now contains the comments for all changes from rev 1.111 and 1.114, inclusive.

Scroll back to find the 1.107 changeset.

Things to notice:

• The "branched" graph from node 1.107 represents parallel development.
• All work is recorded, including branch points as separate nodes. Each of these nodes is a reproducible snapshot of the repository.

Stay in bk revtool; on the next page you'll look at file history.

File history

Click on node 1.114.

You should be looking at a changeset which has modifications to pass2.c.

Left-click (single-click) in the comments below the e2fsck/pass2.c file.

Another bk revtool appears; this one displays the history of pass2.c. Revision 1.36 of pass2.c is the delta in the 1.114 changeset. bk revtool is displaying the differences between the revision of interest (1.36) and its parent (1.35). We can now explore this file further.

Click Select Range. Select All Changes.

To see the differences introduced by this delta:

Left-click on 1.35 and right-click on 1.36 (Cmd-click on Macintosh).

The differences are displayed in the text window. To see side by side differences with all the file context in a new window:

Click Difftool in the menu bar at the top of bk revtool. In bk difftool, press the spacebar to walk through the diffs. Press "p" to go to the previous diff. Click Quit when done. Click Quit in the bk revtool window that has ChangeSet in the title bar.

Stay in bk revtool with pass2.c in the title bar; on the next page you'll do some searching.

Searching

Suppose that you are looking for a particular change in pass2.c. Start by getting an annotated listing by

Double-click on a node in the graph; let's choose 1.35.

You should see lines like

tytso 1.1 /*
tytso 1.1  * pass2.c --- check directory structure
tytso 1.1  *

Suppose that you were trying to track down a bug in symlink handling. You know that the problem has something to do with a function with pass1_check in its name. To find this

Press "/" and notice that the focus is in the search window at the bottom. Type in "pass1_check" and press "Enter". That's not the right one; press "n". Press "n" exactly 3 more times.

That's the one you want. But you remember it being different so you would like to see what it was like before this.

Left-click on the line containing e2fsck_pass1_check_symlink.

Notice that the highlighted node in the graph is now the one corresponding to the line you just clicked. To see the changes for this revision,

Press "d".

Repeat the search process to find the call to e2fsck_pass1_check_symlink:

Press "/". Type in "pass1" and press Enter. Press "n". Left-click on the line with pass1 highlighted.

Stay in bk revtool; on the next page you'll look at the changeset that added that line.

Viewing a changeset

You should be on revision 1.34 in the history of pass2.c; if not go click on that.

Now that you have found the version of the line you want, you might want more information about what was happening when this change was made. This information can be helpful in tracking down the root cause of a bug.

Click on View Changeset at the top of bk revtool.

A new window, labeled Cset Tool, should appear. This window has 4 panes.

• The top left pane is the list of files in this changeset; you can click on a file to make it active.
• The bottom two windows show the before and after versions of the active file. You can move through the diffs by pressing the spacebar.
• The top right file has the changeset checkin comments followed by the checkin comments for the active file.

Browse around in the changeset viewer. Try clicking the files, moving through diffs, etc.

When you are done, click Quit in all BitKeeper windows.

At this point you should now be familiar with viewing repository and file revision history using bk revtool.

If you would like to use command-line tools to browse history, please read the help pages for bk changes and bk log:

bk help changes bk help log

Updating your repository

Next, you will update your repository using bk pull.

• The first pull will be from the parent and will have no updates
• The second pull will be from an alternate repository and will have updates

The bk pull command can be used with or without specifying a BitKeeper URL. Using bk pull without a URL argument pulls from the parent. With a URL, BitKeeper pulls from the repository specified by the URL. By default, the parent is the repository from which the current repository was cloned.

bk pull

It should have told you there was nothing to pull, which is correct; that repository has not changed. Let's go pull from a different repository which does have changes:

bk pull http://bkdemo.bkbits.net/bk_demo1

You now have learned how to get updates from the parent repository or an alternative repository.

Go on to the next page to make your own changes.

Making changes

In this section you will learn about and become familiar with

• file modes and checking out files for editting
• checking in both modified and new files
• creating changesets
• viewing the new changes

Checkouts

Before you actually make any changes, it is important to get acquainted with how to check out files in BitKeeper.

Cleaning a directory

cd e2fsck

Notice the directory is populated with files. Now do:

bk clean

Notice that the files are now gone. The SCCS directory is where the revision histories for the files in the directory reside. On Windows the SCCS directory is hidden by default.

Checking out
There are two modes for checked out files in BitKeeper: read-only mode and read/write mode.

To check out (or get) the files in read-only mode do:

bk co

Notice that the directory is now populated.

Now check out the files in read/write mode:

bk edit

Notice that the files are now read/write capable and thus can be modified.

To put the repository back in its original state, do:

bk clean bk co

Checkout Modes

By default, BitKeeper operates in a "clean" checkout mode such that all files must be explicitly checked out. It can also run in other checkout modes: get mode and edit mode.

The repositories you have cloned for this demo run in checkout:get mode and consequently all files in the repository are checked out in read-only mode. If you run in checkout:edit mode, all files in the repository are checked out and can be modified.

Modifying a file

Please do the following modification to recovery.c:

bk edit recovery.c Edit recovery.c in a text editor. Change all instances of "jread" to "Jread".

Creating a file

Create a new file:

echo "/* New File */" > foo.c

Notice that you did not tell BitKeeper that this file needs to be revision controlled; you'll do that later.

Viewing the changes

Often it is useful to see what changes have been made that haven't been checked in yet. You can use bk difftool or bk diffs to view differences.

Try the command line first; you should see the jread changes:

bk diffs

And to see which files are not yet under BitKeeper control:

bk extras

Then try the graphical tool:

bk difftool

As with most BitKeeper graphical tools, you can use the "n" key to get to the next diff and the "p" key to get to the previous diff.

bk difftool displays the differences between the last rev and the modified versions of the file if run without options and the file argument is a modified file. With no arguments, it shows diffs for all modified files in the current directory.

Click Quit in bk difftool.

Checking in changes

Checking in files and creating a changeset can be done via the command line or with bk citool, the graphical check-in tool. We recommend using bk citool because it shows the changes made to each file which improves the quality of the comments. Steps for the graphical tool are shown first followed by steps for another file edit and the command-line check-in.

Using bk citool:

bk citool

Add comments about the changes in the middle window. Click on the icon next to foo.c to add this file to the repository. Click on ChangeSet. Add comments about the ChangeSet in the middle window. Click on the Commit box at the right. Click on the Commit box again to confirm you are done.

You have now checked in your changes, added the new file foo.c, and grouped these changes into a changeset. Next you will check in changes using the command line:

echo foo > bar.c bk new bar.c bk edit foo.c echo "This is file foo.c" >> foo.c bk ci -y"These are the checkin comments" foo.c bk commit -y"These are the changeset comments"

To see the changes you've just made:

bk revtool

Double-click on the box containing "your_login 1.125". In the bottom window, click on the line under "e2fsck/recovery.c".

The history of the recovery.c file is shown in another bk revtool window. You can use bk revtool on files in the same way you can use it on a repository.

Click Quit in all BitKeeper windows.

Merging changes

The next part of the demo will illustrate how to merge conflicts. BK/ProMerge can complete many complicated merges automatically, but there will be times when there are merge conflicts that need to be resolved by a human being.

The BitKeeper update process does not apply changes to your repository until they have been merged. Instead, the changes are pulled into a sparse repository called the RESYNC repository. When there are conflicts to merged, the bk pull command tells you that as the last part of the output.

In the following section you will learn

• what bk pull outputs when it can not automerge
• how to run the resolver to resolve a conflict
• what the file merge tool looks like and how to use it
• how to check-in once you have performed a manual merge

Let's go see how that works.

Pulling and resolving a conflict

When you pull in a conflict that must be merged manually, BitKeeper will automatically run the resolver and will prompt you to resolve the conflicts. Let's pull in a merge conflict:

cd .. bk pull http://bkdemo.bkbits.net/bk_demo2

You should see:

---------------------- Receiving the following csets -------------------------- 1.124 ---------------------------------------------------------------------------- ChangeSet: 1 deltas e2fsck/recovery.c: 1 deltas --------------------------------------------------------------------------- takepatch: saved entire patch in PENDING/2006-07-07.01 --------------------------------------------------------------------------- Applying 1 revisions to ChangeSet, renumbering, checking checksums Applying 1 revisions to e2fsck/recovery.c takepatch: 2 new revisions, 2 conflicts in 2 files 569 bytes uncompressed to 1363, 2.40X expansion Running resolve to apply new work ... Conflicts during automerge of e2fsck/recovery.c resolve: 1 unresolved conflicts, starting manual resolve process for: e2fsck/recovery.c (content conflict) e2fsck/recovery.c>>

Because bk pull encountered merge conflicts, it runs the resolver, which prompts you to resolve the conflicts. (You can run the resolver manually with the bk resolve command.) The resolver can handle a number of different conflict types, such as content or rename conflicts. Each conflict type has its own resolver "plugin" with a type specific set of commands. In this example, you will be handling a content conflict.

Press "Enter" to see the command options. Press "f" and "Enter" to run the 3 way file merge.

File merge

You should see a multi-pane graphical tool. It has 6 panes:

• The first "row" contains two small side by side windows. These contain the checkin comments for the active diff.
• The next row contains two larger side by side windows. Each of these is a "stacked diff" window, showing the changes from the common ancestor to the local (left window) or remote (right window) versions of the file. The active diff is the one with lines highlighted the width of the window. The darker highlighting with the leading "-" represents the lines in the ancestor and the lighter highlighting with the leading "+" represents the lines added by the local or remote version of the file.
• The merged file is shown at the bottom left.
• The smaller lower right window contains instructions for the active difference or conflict. There is also a status bar which contains information about which conflict you are on out of how many.

Each conflict that must be resolved by hand highlights the status bar in red. To select a line or block simply click in the upper left or upper right boxes on the line or block that should be in the merged file. So, in the example, you're going to keep the changes you made and complete the merge.

Click in the upper right window on the line with "jREAD" highlighted in orange. Press "u" to undo since you want the "Jread" changes. Click in the upper left window on the line with "Jread" highlighted in orange. Press the "]" key to go to the next conflict. Click in the upper left window on the line with "Jread" highlighted in orange. Press the "]" key. Repeat until all conflicts have been resolved. Type "s" to save.

Checkin

The file merge tool should have dropped you back into the resolver interface. If you are sure that you want to keep the merged changes you are ready to commit the merge:

Type "C".

If there were more files with conflicts, the resolver would prompt you with the next conflict. Since this is the only conflict, the resolver then brings up citool to allow you a chance to comment the merge changes.

Type in comments for all files. Click Commit twice.

Update the parent

What you have done so far is to make local changes and merge in changes from a different repository. You have not yet updated the parent with your changes; they are only in your repository.

In this section you will learn

• how to use bk changes to see if there are local only or remote only changes
• how to use bk push to update another repository with your changes

You can see if there are changes in the parent (or remote) repository that aren't in your repository by running

bk changes -R

You shouldn't have seen any changes.

You can see if there are changes in your local repository that aren't in the parent by running

bk changes -L

To update the parent repository, you need to do what is known as pushing, i.e., you push your changes to the parent repository. To see where changes will go, run the bk parent command and then push:

bk parent bk push

After you push, the parent and your local repository are exactly the same. If you pull or push, nothing should be transferred. Let's see what happens when you try a bk pull:

bk pull

You should not have received any updates.

You have now updated a repository with the changes that you made.

Finis

Congratulations! You have successfully run through some of the basic and some of the more complex BitKeeper operations. You've seen how to get views of the repository and its files via the command line and via the graphical tools. You have made modifications to a file, added new files, checked in those files, and created a changeset. And finally, you've run through a merge with conflicts that needed to be resolved by hand.

You might want to delete the BK directory you made along with all the demo repositories.

For more information about BitKeeper commands, try one of the following:

bk helptool bk help topic bk help -k keyword

If you need further assistance, you can find it at support@bitmover.com.

A next step in learning about BitKeeper is to try it on your own data. If you would like to talk to a representative about doing a conversion of your current tool's data, please send mail to sales@bitmover.com.