Oftentimes you wonder what work has been done in a clone of a certain baseline. Maybe you forgot, maybe you just want to review what would be pushed. Figuring out what is local to this repository is easy:

The first command will show you the diffs between the baseline and the local repository. The second command will display the same diffs graphically.

See bk help diff and bk help difftool for more information.

One of the most common questions when looking at a particular ChangeSet is "Have we shipped this?". BitKeeper makes it easy to get an answer:

Let’s unpack that command. The bk set command allows set operations to be performed with BitKeeper’s ChangeSets. The -l option lists all ChangeSets that include the given revision (with the -r option). Finally, the -tt option lists only ChangeSets that have been tagged and furthermore, it lists the tags. Thus, we are effectively asking: Show me the tags for all ChangeSets in which this ChangeSet has been included.

See bk help set for many more uses of the bk set command.

BitKeeper makes it easy to see what was just pulled from a remote repository. Immediately after running bk pull, you can run one of:

The first one will run csettool showing both the list of ChangeSets pulled in and the diffs per ChangeSet. The second one will show difftool showing only the differences. The third one will print the diffs to the terminal, and the last one will show only a histogram of the changes.

See bk help csets for more options.

Tags can be tricky. When they have already been pushed and they have propagated, it isn’t possible to remove them (but you can override them). However it is often the case that we realize a tag we have just created and have not yet pushed needs to be removed. How do we do that?

The first command will print the key (-k) of the latest ChangeSet made (-1) which should be the tag. Since the default output for bk changes hides some non-data ChangeSets, the -a option is needed to tell bk changes to "show all". The second command uses the tagkey file which contains just the key of the tag to strip it from BitKeeper’s history.

See bk help changes and bk help undo for more information.

Occasionally we pull from the wrong place, or pull when we were not supposed to. Not a problem, we can easily undo a pull:

This handy command will revert the repository to the state before the pull.

See bk help unpull for more information.

Ever been looking at some diffs in bk difftool and wondered why the changes were made? There is a really easy way to have difftool display that information in a small window. Hit the 'w' key. For example:

will show you all the diffs in this repository with respect to the parent. Once you are looking at the diffs, hit 'w' for a small popup.

See bk help difftool for more options.

When working in a nested environment, bk clone will clone by default the set of components specified in the clone_default configuration variable. What if you need to take an exact copy of a repository with all of its components (which might be different from the default)?

Will clone the <src> repository to <dst> with all of the components that are there.

See bk help clone for more options.

Sometimes, when debugging, it’s necessary to look at the exact environment the developer had when a certain change was made. That is, we want to roll back to a certain ChangeSet, but want to reproduce the set of components that were populated when the ChangeSet was made.

This command will clone <src> into <dst> but will also populate the exact same set of components that were populated at the moment the ChangeSet specified by <rev> was created.

See bk help clone for more options.

When working with nested repositories, sometimes a pull will fail because some of the components that are not populated have changes both in the local and remote repositories. In this case, we can tell pull to automatically populate the needed components by running:

Which will use a smart algorithm for picking up the minimum set of aliases that cover the missing components. If you want to have pull always use the auto-populate option, you can put the following in your config file:

See bk help pull, bk help config-etc, and bk help alias for more information.

When you clone a repository, the copy created by clone will have the source of the clone as its parent. Sometimes however, it is desirable to clone a repository and have the parents of the source also be the parents of the copy. You can do this by running:

BitKeeper will remember the parents of <src> and set them as the parents of <dst> after doing the clone.

See bk help clone for more information.

When working on a repository, one of the most frequent questions is "What files have I added and or modified but not committed?". While it is possible to answer this question by running bk citool, it is sometimes enough to see the list. You can do that by running:

The -U optoin to bk tells it to operate on "user files". That is files that are not part of the BitKeeper metadata (like for instance the ChangeSet file). The modifiers cxp correspond to "changed", "Extras", and "pending" respectively. Since we did not specify any BitKeeper command to run, the default action is to print the files.

Note that BitKeeper will print the files are relative paths to the current directory. This is so you can pipe the output of bk to another command. For example:

Will "touch" all the modified files, which might be desirable for rebuilding with make.

In a nested collection, the configuration entry clone_default controls what aliases are cloned by default when the user doesn’t explicitly override the list. For example, if clone_default is not set, the alias will default to ALL.

Other useful options are:

See bk help config-etc and bk help alias for more information.

As repositories grow in size, scanning them to look for what changed can start taking too long. One way of improving the speed of citool (or any scanning for that matter) is to use the "SCANDIRS" feature of BitKeeper. Follow this steps to activate that feature:

Once you have everything properly configured, you can run bk citool --no-extras and citool will only look for changes in files that you have explicitly checked out using bk edit.

Sometimes you might want to create a new ChangeSet that is the combination of several other ChangeSets and put it on top of a new parent ChangeSet. This is desirable, for instance, when you’ve worked on a feature and have been tracking a master branch, and now you want to integrate your work as a single ChangeSet on top of the Tip of the master branch.

BitKeeper lets you do this while still using the powerful conflict resolution tools. Simply do:

The first command will make sure you are completely synchronized with the master repository. The second command will remove all local ChangeSets but preserve the modifications and comments to all the files, leaving them as locally edited files. The last command will run BitKeeper’s Check-In tool to let you modify the comments and commit the new ChangeSet. Once you are happy with the results, you can bk push the ChangeSet to the master repository.

One caveat is that you should not have propagated any of the local ChangeSets you are collapsing. If you have, you will be creating unnecessary conflicts down the road for people who have pulled the uncollapsed version of your work.

Adding large binary files to a distributed repository is the surest way to kill performance. Fortunately, BitKeeper provides a solution that combines the best of distributed and centralized version control. With the Binary Asset Management option (BAM), BitKeeper will keep the metadata of large binary files in the distributed repository, but use a centralized server for the file contents. This means that your clones will still be fast but the data will be version controlled in a distributed way.

To turn on the BAM feature, simply turn on the configuration variable BAM. You can also set it to the minimum binary file size that will trigger keeping the file in the BAM server. For example:

Will let BitKeeper set the default size. Currently it is 64K.

Will turn on the BAM option for binary files larger than 4M.

Note that only new files will be affected by the BAM variable. If you want existing binary files to be converted to the BAM format, use

See bk help bam and bk help config-etc for more information.

Don’t you hate it when right after committing a ChangeSet you think of better comments than the ones you just wrote? BitKeeper lets you quickly and easily modify the comments of a ChangeSet with the bk comments command. For example, to fix the comments of tip, just run:

and the editor specified in your environment variable EDITOR will be launched with the comments of the last ChangeSet filled in.

Note that comments will only propagate if the ChangeSet is actually pulled or pushed. If some other user already had the ChangeSet for which you fixed comments, they will have the old comments.

Finding strings in a BitKeeper repository is easy and demonstrates the power of BitKeeper’s modular design. If you are looking for a particular string, you can combine the grep command with the -U flag to bk, like so:

This command will search (grep) all user files (bk -U) for <string>. The matches printed will be preceded by the file name where the match was found. If you add the -n flag to grep, also the line number of the match will be reported.

See also bk help grep and bk help bk for more options.

Finding out the set of modified files between two revisions is easy, just use the rset command to generate "release sets". For example, running

will print out the list of files changed from ChangeSet A to ChangeSet B along with the revisions of the files as of each ChangeSet. Adding the -h option to rset will also show the history path names, which helps for seeing renames.

See bk help rset for more options.

When working with a nested collection, it is sometimes useful to work on an individual component. For example, if you are working on a single nested repository that encompasses an entire operating system, but you only work in the libc component (the C standard library), you might want to restrict some commands to operation only in the libc component. Most BitKeeper commands take a -S option for this. For example:

Will print the last ten ChangeSets done at the product level. However, if you use the -S option to bk changes:

Then the output will be the last ten ChangeSets done in the current component. Thus, if your current working directory is the libc component, and you run the previous command, you will see the last ten ChangeSets done in the libc component only.

Sometimes after finishing a merge, you might realize that one of the files was merged wrong. Maybe the compiler complaints? Or maybe the regressions don’t pass? The easiest way to remerge the file is to use the remerge command:

will pop-up fm3tool on the merge and give you the opportunity to remerge the file. Once you are done, the file will be left edited with the changes from the checked in version. So if you want to see how your remerge was different than the original merge, you can run:

The first command will pop up BitKeeper’s graphical diff tool while the second will just print the diffs to the terminal in unified diff format.

See bk help remerge, bk help difftool, and bk help diff for more information.

While you can redo a merge that was just completed using bk remerge, you can also redo any merge in the history of a file, or even see how BitKeeper auto-merged conflicts. The command to explore a merge is:

Which will give you a menu from which you can run different tools explore the merge.

See the file bk bin/bk.script for more details (aka read the source).

When you clone a BitKeeper repository, BitKeeper will first transfer all the metadata (history) of the files, and then it will check out the files in different ways depending on your checkout mode.

There are four different checkout modes:

There are various ways to set the checkout mode. The simplest one is to put it in your .bk/config file. Like this:

Where '<option>' is one of 'get', 'edit', 'last', or 'none'. Another option is to pass the checkout mode to the clone command:

will clone '<src>' to '<dst>' and will not check out any of the files.

When debugging, it is sometimes useful to figure out why a specific section of code was written. BitKeeper provides a powerful annotation system designed to be used either from the command line, or in a GUI. The easiest way is to use the GUI. If you know the line number you are interested in, you can run:

and bk revtool will appear with the line '<lno>' selected in the file '<file>'. From there you can start exploring the revision history. Sometimes it is convenient to tie this with your editor and have a shortcut that makes the whole process automatic.

If you want to use the command line, you will have to get an annotated copy of the file using the bk annotate command:

See bk help annotate and bk help revtool for more options.

BitKeeper by default runs error checks on any changed files in many operations, like pull, push, and clone. It can also be configured to run a full-repository check in all of these operations by turning the configuration variable partial_check off.

Even with partial_check turned on, BitKeeper will run a full check at least once a week. However, this interval can be adjusted using the config variable check_frequency. For example,

Will run the full check every two days. Also remember that you can always run a full check manually using the repocheck command:

See bk help config-etc, bk help repocheck, and bk help check for more options.

Sometimes it is useful to see what commands have been run in a repository. For instance, we might have forgotten if we pulled from a particular URL or if we ran an undo operation in this repository. This can be easily accomplished by running:

Which will print a list of the command run in this repository since it was cloned (or created).

See bk help cmdlog for more options.

Sometimes it’s necessary to go back to a particular ChangeSet, like for instance a tagged release, and do some work there. The easiest way to do this in BitKeeper is with the bk undo operation. For instance, ot go back to the release tagged 'REL_2.0', we would run:

The '-a' option means 'at' so this command will take this repository back to the REL_2.0 ChangeSet. Note that bk undo is a destructive operation and will remove information from your repository. It should be run on a clone that has no unique work.

See bk help undo and bk help clone, for more information.

Some operations in BitKeeper run by default in 'paginated' mode. One example is bk changes, which will print its output one screenful at a time. BitKeeper chooses which pager to use based on the value of the BK_PAGER environment variable. You can set this to any pager you like or, to avoid using a pager, to the cat program:

Options can also be passed, this works nicely:

When you are working on many different features, you might end up with many different clones of the same repository, all with a few unique ChangeSets. One way to save disk space is to use hard links for all the files that are common to all of them. This is done with the 'relink' command:

This will use the repository '<to>' as a baseline for creating hard links for all the repositories listed in the '<from >' arguments. For example, if all of your repositories have the prefix 'bk-', you can run:

And all files that have not changed between each of the 'bk-*' repositories will be relinked with the 'bk-baseline' repository.

For more information see bk help relink.

If you need to get a copy of your repository that doesn’t include BitKeeper’s metadata (i.e. the revision history of all your files), you can use the 'export' command:

This command will export a plain text copy of your entire repository as of revision '<rev>' to the '<to>' directory. Note that keyworkds will be expanded by default, but you can prevent the expansion by using the '-k' option to 'export'.

See bk help export for more options.

Occassionally you might find yourself with a repository in which most of the files are checked out and some are not, and you want to check out all the files. If you just run 'bk -U co', it will re-check out all of the files that were already checked out. A faster way of doing the check out is to use the '-S' option to 'co'.

This command will quietly ('-q') check out all the files in the repository, but it will skip any files that were already checked out ('-S'). Note the use of 'bk -U' to iterate over all files in the repository.

Sometimes many people collaborated in creating the work but you end up committing it. For instance, you might have built up many changesets by many different users and now you are collapsing the collection into a single changeset. Or maybe someone from the QA department emailed you the tests and you are now committing them, but would like to preserve authorship. No problem! BitKeeper lets you change the author of a ChangeSet using the BK_USER environment variable.

Will run bk citool as normal, but will check in the changes as user 'buddy'. Note that you don’t have to commit a ChangeSet in citool. You can just check in the files that Buddy wrote, quit out of citool, and then commit the ChangeSet as yoursef.

See also bk citool.

Sometimes it is convenient to run a command on a repository other than the one you’re at. In those cases, all you need to do is pass the '-@' flag to the 'bk' command. For example:

Will run the pwd command in the parent repository. You can also pass a url to the '-@' flag, like so:

to run the command in the remote repository. The bkd needs to have been run with remote commands enabled for this to work.

See bk help bkd, and bk help bk for more options.

Sometimes, when looking at a particular file, you are surprised to find that sections you remembered where there, are in fact not there anymore. The most probably explanation is that someone deleted that region of code (or you are misremembering ;). BitKeeper has a very fast way to show you deleted sections of code. Simply run annotations with the '-R -w' options:

This will display the entire contents of the file, including deleted lines. Each line that has been deleted will have annotations like this:

The first field is the user ('awc'), the second is the revision in which this line was added (1.26.3.7) and the last one is the revision that deleted this line (1.26.1.17).

See bk help annotate for more options.

In the BitKeeper documentation you will sometimes see references to revision numbers (numbers like 1.234.4.2) and cautions saying they are not stable. What is meant by this is that they only make sense in a single repository.

As an example, imagine you have a repository in which the top changeset is 1.234. You clone it to create a copy of it. If you create two new changesets, one in each repository (the original and the copy) both of those changesets will get the next number, that is 1.235.

If you pull on repository into the other, one of those two changesets will get renumbered (to something like 1.234.1.1) so refering to changeset 1.235 will only make sense in the context of a specific repository.

If you want a global identifier for a changeset, one that won’t change as the changeset flows between repositories, you need to use either changeset keys or md5 keys.

See also bk help changes.

Changeset keys are stable identfiers that don’t change as the changesets move between repositories. They come in two flavors: regular keys, and md5 keys. The former look like this:

and the latter looks like this:

Both of those are useful for refering to particular changesets in bug trackers and other databases since they won’t change when pulling/pushing to other repositories.

See also bk help changes.

When updating a local copy by using the 'bk pull' command, it is sometimes desirable to see what files were updated by the pull. One easy way of doing this is by telling pull to show diffstat output after the pull:

if you want to have this option permanently enabled, you can set it in you '.bk/config' file:

See bk help config, bk help pull, and man diffstat.

Sometimes, when you are tracking another repository with your local one, it’s convenient to throw away all the local work and just resynchronize with the parent repository.

In those cases the following sequence of commands can get the job done:

The first one will use 'bk repogca' to compute the greatest common ancestor of both repositories (greatest lower bound), then the 'bk undo' command is called to remove all the changesets follwing the computed repogca. Finally bk pull will bring in all the changesets in the parent.

See bk help undo, bk help repogca, and bk help pull for more options.

When BitKeeper updates a repository it creates a temporary work directory at the root of the repository called the 'RESYNC' directory. The RESYNC directory is used for handling merges, renames, and whatever other tasks need to be done to merge the work done in the remote repository with the work done in the local repository.

Sometimes, the RESYNC directory will be left behind due to problems finishing the pull, triggers that abort the pull, or aborting the pull.

If you want to get rid of the RESYNC directory, there are two safe ways of doing it. You can run 'bk abort' to go back to the state of the repository before the pull. Or you can run 'bk resolve -a' to try finishing the pull.

It’s important to never delete the RESYNC directory as the 'bk abort' command can do other cleanups besides just removing the RESYNC directory, especially if you are using nested.

See also bk help pull, bk help abort, and bk help resolve.

When BitKeeper needs to read or write the files in a repository it will take a 'lock'. Normally these locks are managed automatically and you don’t have to worry about them. However, sometimes aborted operations or problems with triggers can leave a repository locked. To see what operations are locking a repository, you can run the 'bk lock -l' command:

The output will tell you who is locking the repository, whether it’s a read or write lock, what BitKeeper command is responsible for the locking, and how old the lock is.

See bk help lock.

BitKeeper normally manages locks automatically, so you should very rarely need to manually unlock a repository. However, failed operations or aborted commands can sometimes leave a repository locked. BitKeeper provides an 'unlock' command that can be called manually to deal with this situations:

The '-rw' flags tell 'bk unlock' to remove both read and write locks.

See bk help lock, bk help unlock.

BitKeeper provides several ways to create a new repository. By far the simplest is to just call the 'setup' command on an empty directory:

Another way is to call 'bk setuptool', which is a wizard based GUI tool for creating repositories:

See bk setup, and bk setuptool for more information.

Have you ever noticed that the last line in the output of 'bk version' tells you about the latest version of BitKeeper? If you are out of date, upgrading BitKeeper couldn’t be easier. Simply run:

and BitKeeper will download the latest version from the web and upgrade your installation.

See bk help upgrade.

If you want to try the latest version of BitKeeper but you don’t want to upgrade your existing installation, you can precede any command with the 'latest' command:

will run 'bk changes' using the latest version of BitKeeper. How does this work? The first time you call 'bk latest', the latest version of BitKeeper is downloaded and temporarily installed in the '.bk' in your home directory. Any further invocations of 'bk latest' use this version instead of the installed one.

See bk help latest.

Yes! BitKeeper ships with an Emacs mode by default. You can find it in the BitKeeper installation directory. In order to load it to your emacs installation, simply add the following lines to your .emacs file:

The Emacs plugin is distributed as source, so you can modify it to suit your own needs.

See also bk help bin.

When you want to modify the structure of a nested repository, for example when you are adding new components, you need to do the operations in a portal.

A portal is simply a fully-populated BitKeeper repository (a side effect of turning a repository into a portal is that all components are populated).

In order to turn any repository into a portal, you just need to run the 'bk portal' command like so:

See bk help portal.

A gate is an integration repository that is backed up and generally considered safe. This means that changesets that have made their way to a gate are considered good to build on top of.

BitKeeper will use gates to prevent users from losing work when working with unpopulated components. For example, if a developer is doing a sideways push to another developer, and one of the components has unique work and is populated in the source but unpopulated in the destination, BitKeeper will check the configured gates to see if the changesets in that component have made their way to it. If not, the push will fail unless the destination populates the component in order to receive the changesets.

You can turn any repository into a gate by using the 'bk gate' command like so:

But be careful that you only turn stable and backed up repositories into gates.

See bk help gate.

Components can only be added to a product in portals. Portals are fully populated repositories in which component manipulation is considered safe.

To add a new component to a product you run the 'bk attach' command. It takes the URL of a repository and attaches it to the current product.

This will attach the repository at '/path/to/repo' to the 'dest' directory in the current working directory. A changeset is automatically created in the product to record the new component. The 'attach' commmand has a flag to prevent the automatic changeset in case you want to attach multiple components but record just one changeset in the product.

See bk help attach.

Aliases are a very powerful way to organize your components. They are basically named sets of components that can also include other aliases as elements.

Aliases are managed using the 'bk alias' command. For example, to create a new alias call NEW that includes the components 'comp1', and 'comp2', you can run the following command:

If you later want to add comp3 to the alias, you can run:

See bk help alias for more details.

BitKeeper has a few reserved aliases that have a specific meaning. One of these is the 'HERE' alias, which always expands to the set of components currently populated in the product.

This alias is so useful, it even has a shortcut, the 'bk here' command.

See bk help alias, and bk help here.

The easies way to see the list of components populated in the current product is to use the 'bk here' command.

Note that the 'bk here' command will print the aliases populated, you add the '-v' flag to see the expansion of each of the aliases.

If you just want the list of components populated, you can run:

which will print the component paths and not the aliases.

See bk help here, and bk help comps.

Components are repositories bundled together into a single product. You can create a new product using the 'bk setup' command and passing the '-P' flag.

Once you have a new product, you can attach any repositories you want to it using the 'bk attach' command. For example, if you want to attach the components 'kernel', and 'libc' to your new product, you can run:

Another way of creating components is to take an existing large BitKeeper repository and partition it into a product and a bunch of components. This is done with the 'bk partition' command.

See bk help setup, bk help attach, and bk help partition.

A product is a BitKeeper repository that provides a single timeline for a collection of other BitKeeper repositories called components. You can see what type of repository you have by running the 'bk repotype' command:

It will print one of 'product', 'component', or 'traditional'.

See bk help repotype.

If you end up with a large BitKeeper repository that you would like to partition into a product and a bunch of components, BitKeeper has an easy way of doing that. The command is called 'bk partition' and all it takes is a list of directories in your repository that will be turned into new components.

For example, say you have a repository with subdirectories 'src', 'doc', and 'lib', and each of those subdirectories should be turned into a component. You would create a file with the list of directories and pass it to the partition command:

This command will take the traditional repository at '/repos/traditional' and use the 'complist' file as a guide to partition it to '/repos/product', which will have 3 components, one for each of the subdirectories.

See bk help partition for more options.

BitKeeper has a few useful options for working with components. One of them is the '-e' flag to the 'bk' command which functions as a component iterator. For example, to run the 'repotype' command in all the components present, you can run:

If you want to precede the output of the command with the pathname of the component in which it is being run, you can add the '--headers' flag:

See bk help bk for more options.