Introduction

The BitKeeper User's Guide explains both basic and more advanced usage of BitKeeper, including useful examples of commands, combining command options, and explanations of why things work the way they do. The following topics are covered:

• BitKeeper Concepts
• Getting Started
• Graphical Tools
• Advanced Operations
• Usage Models
• Advanced Topics
• Reporting and Data Mining
• Installation
• BitKeeper Maintenance

If you are viewing this on the website, the chapter headings appear at the left of the window. Section and sub-sections within each chapter are listed in the column under the chapter when the chapter is selected. You can click on any chapter or section heading from any point in the website. The Site Map is very useful because it gives the option of viewing the manual as one very long html page, or to view each section as one long html page.

Other available on-line documentation includes:

• bk helptool, an on-line reference manual with a built-in search facility
• the BitKeeper FAQ
• the BitKeeper mailing list.

Administration of BitKeeper, what little may be necessary, is documented in Appendix B.

BitKeeper Concepts

Assuming a basic knowledge of software configuration management (SCM), the first section of this manual describes what concepts are unique to BitKeeper and how they may effect your method of source management. The following topics are covered:

• BitKeeper
• Repository
• Changesets - grouping related changes, making BitKeeper a task-based system
• Revision Control - BitKeeper tracks more data than other systems
• Open Logging - tracking distributed open software projects

BitKeeper

BitKeeper is a source management system that enables developers to work concurrently on the same project. Unlike most other source management tools, BitKeeper was designed to be a scalable system that supports globally distributed development, disconnected operation, change sets, and excellent merging facilities.

Repository

A BitKeeper repository is a collection of revision files, sometimes called a "tree" or a "repo". Each repository is a self-consistent unit, meaning everything necessary to do work is contained in each copy of a repository. A developer can make a copy, called a clone, of a repository, or delete repositories as needed with no ill effect on the shared repository or other developer's repositories.

With BitKeeper each developer has his or her own repository. If the project is a one developer project, there is only one repository. For multiple developers, each developer will have his or her own local copy of the repository. BitKeeper moves changes between repositories using the local filesystem, rsh, ssh, SMTP, HTTP, or bkd - the BitKeeper network daemon.

There exists a relationship between a repository and a clone of that repository that is called a parent-child relationship. When you clone a repository, to creat a place where you may work, BitKeeper remembers the place from which you cloned as the "parent". A clone of a repository is the child. The repository cloned from is the parent. Generally, there is some sort of structured hierarchy of repositories (see Usage Models). Changes typically propagate between parent and child, but changes may just as easily move ``sideways'' from one child to another as long as there is a common ancestor.

ChangeSets

In the documentation there are references to changesets and the ChangeSet file. A changeset is a grouping of related changes, and the medium for the exchange of data between BitKeeper repositories. The ChangeSet file is BitKeeper's metadata and is a record of all changesets which are in this repository. BitKeeper is unique in that the BitKeeper metadata is itself a revision controlled file, i.e., the metadata is versioned just like your data is versioned.

A changeset is created by a developer to group related changes. In this way changes for a bugfix or feature addition can have some meaning by being grouped together. This method of grouping changes allows the notion of tasked-based entities rather than just file-based entities.

By recording things that do change and things that don't change, BitKeeper can roll back to any changeset. In other systems, the tree must be tagged (or labelled) to roll back to that point. Unfortunately, it is often in hindsight that people want to do a tag. In BitKeeper, this is not a problem since it can roll back to any revision of the source tree at any time.

What is Revision Controlled?

BitKeeper revision controls

• file contents
• file names
• file flags
• symbolic links
• file permissions

Any combination of changes to file type, file name, file permissions, file flags, and/or file contents can be merged because they are tracked in each revision.

OpenLogging

Open Logging is the sending of metadata information to a centralized, public web server, where it is sorted by project, date, and domain name.

If you are a commercial user, Open Logging does not apply to you.

Open Logging is an easy way for all developers to follow each other's progress. Because BitKeeper is a truly distributed system, without Open Logging there would be no centralized place to track the progress of a particular project. Open Logging is a requirement for non-paying customers that have multi-user repositories. It is optional for commercial customers.

What is sent?

• The ChangeSet file (comments and contents).
• The messages that annotate modifications of the data (also known as check in comments, ChangeLog entries, and/or log messages)
• All files contained in the top level BitKeeper directory in a BitKeeper repository, in particular the BitKeeper/html directory and the BitKeeper/etc/config and BitKeeper/etc/logging_ok files.

What is not sent?

• Source code or other data managed by BitKeeper.

People frequently think that Open Logging means their source code is published, but that isn't the case.

Getting Started

This chapter explains how to get started with BitKeeper and documents commonly used BitKeeper commands. This chapter will teach how to:

• set up a repository, including general set up and user preferences
• populate a repository, both importing large groups of files and adding individual files
• work with a repository, including making a copy, sharing changes, and backing out changes

This guide assumes the BitKeeper software has been installed for you. To verify it has been installed, try the bk version command. If version information doesn't come up, please follow the installation instructions in Appendix A.

Before You Begin...

First, if you are a developer and there already exists a Shared Repository that you will be working with, please skip to the Working With A BitKeeper Repository section.

If you are the project lead and have not set up a BitKeeper project there are some things that you will need to think about to tailor BitKeeper to your development processes.

Please review all the sections in Getting Started as well as the chapter on Usage Models and Access Control to help you start thinking about your development processes.

Setting Up a Repository

For every team using BitKeeper, there should be at least one person, maybe a project lead, who understands how to set up the first copy of a repository. This is done once per project and the only thing other team members do is clone the repository to make an individual workspace, or repository.

This section explains how to set up a new BitKeeper repository. This section assumes an environment where there are no permissions restrictions.

General Setup

When setting up a new project, the first instantiation of a repository for the project must be done. This is done once per project. A project key is generated for each new project's first repository. This project key is propagated to all clones of this repository. If project keys do not match when trying to do updates between repositories the updates will fail. Because of this, use bk clone whenever you want to make copies of this repository and use setup only for the original repository.

You can setup a repository using the command line or graphical setup tool. For the command line:

cd ~/projects bk setup dev-1.0

For the graphical tool:

cd ~/projects bk setuptool dev-1.0

Repository Configuration

BitKeeper repositories have a configuration file in BitKeeper/etc/config. This file contains information about the project, licensing methods, owner contact information, and user preferences.

When setting up a repository, a config file must be filled out. The required fields are:

• description
• logging and/or license
• email

The rest of the fields are optional.

Required Fields

The description field should contain a short description of the project this repository represents.

description:  project description goes here 

There also needs to be a contact person for the repository following the email field, add your email address for that field.

email: user@domain

To tell BitKeeper which mode to run in, the logging specifications must be outlined in the config file. If you are a commercial client set the following:

logging: none
license: your_license_key

logging: logging@openlogging.org

logging: none
single_user: your_login
single_host: your_machine_name

User Preferences

With BitKeeper, once files are checked in, by default the clear text version does not exist. It is possible to change that default to check out files in read-only mode (set ``checkout:'' to ``get'') or edit mode (set ``checkout:'' to ``edit''). If checkout: is left blank, the default behavior will occur.

checkout:

The checkout preference can be set per user, per host, or per repository via these filters:

• per user
  [jdoe:]checkout: get
• per host
  [@xyz.com:]checkout: none
• per user@host
  [jdoe@xyz.com:]checkout: get
• per repository
  [/path/to/repository:]checkout: edit
  [@xyz.com:/path/to/repository:]checkout: get
  [jdoe@xyz.com:/path/to/repository:]checkout: edit

Owner Information

To specify contact information, so that someone from BitMover can contact you if a problem with BitKeeper is discovered, add the appropriate information:

contact:
phone:

You may create a global config file and use that upon every setup:

bk setup -cconfig_file

Populating a BitKeeper Repository

Initially populating a repository will usually include an import of existing data.

There are a couple of ways to get those files under revision control:

• bk import
• bk sfiles with bk new

This section will teach:

• How to import existing non-BitKeeper files into a BitKeeper repository
• How to include or exclude files when importing
• How to add individual files to a BitKeeper repository

For new BitKeeper users it's important to note that after files are checked in, they no longer appear in your directory. The process of checking in files removes the files from the directory and places them in SCCS sub-directories. Once in the SCCS sub-directory, the file can be retrieved with the bk get or bk edit commands. Most versions of the Unix make command know about the SCCS sub-directory and will automatically check out files as they are needed.

Importing Files

If you have many existing files to move into a BitKeeper repository, you probably want to ``import'' them all at once. If you were starting a BitKeeper repository with a very small number of new files, the import step is probably unnecessary, and you could skip to the section on Adding Individual Files.

Files that are not yet checked into a BitKeeper repository are what is imported. This would include plain text, RCS, CVS, SCCS, and patch files.

To import:

bk import -ttype src_tree destination_repository

where type is any of the types of non-BitKeeper files:

plain   plain text file
patch   patch file (diffs)
RCS     RCS file
CVS     CVS file
SCCS    SCCS file

Including and Excluding Files

There may be times when it is necessary to import parts of a tree rather than the tree in its entirety. In these cases, there are options to import that may be used.

• If a list of files to import exists or can be generated, the -l option may be used.
• If the files wanted or not wanted for import can be described using regular expressions, the -i or -x options may be used.

For more information on importing files, please see

bk helptool import

Adding Individual Files

If you have just a small number of files with which to populate a new BitKeeper repository, then the bk import command might be overkill for your purposes. A more appropriate command is bk new, which will place new files under BitKeeper control. If given one file name, bk new will check in that file. When checking in multiple files in a directory, bk new can be combined with the bk sfiles command to checkin multiple files in a directory as follows, but be careful with this use of the command, because it will check in anything, including a.out, *.o, core, etc:

bk sfiles -x *.[ch] | bk new -

If you have a large number of files to add to an existing package, an alternative to import is to generate a list of the files, edit the list to make sure there are no unwanted files (such as object files), and then check in the files from the list. For example:

cd new_package mkdir new_files cd new_files cp -rp ~/files_to_import . bk sfiles -x . > /tmp/LIST vi /tmp/LIST # remove any you don't want bk new - < /tmp/LIST

Working with Repositories

After the initial project repository is setup, developers can start working. First an individual workspace or repository must be created for the developer. Once this is done, the developer can make changes, share changes, and, if necessary, back out changes.

This section describes how to do all of these operations.

Cloning A Repository

If the previous mentioned setup example happened to be a single-developer project, that might be the only repository necessary. The developer would simply work in the master repository. Most projects, however, are multi-developer projects and therefore the master repository would be cloned for each developer on the team. After the first repository is created, subsequent copies of that repository are created using bk clone. It's important that bk clone is used to make copies of the repository, and that bk setup is not run more than once, since bk setup generates a project key, but bk clone copies the existing key, and each project needs one unique instance of the key.

The bk clone command makes a local copy of the master repository, which is also known as the ``parent'' repository. The repositories then have a parent-child relationship, and subsequent BitKeeper operations use the knowledge of this relationship. It is possible to specify a new parent with bk parent to change the location of the effects of a BitKeeper command.

Making Changes

There are a number of things you may want to do with files in a BitKeeper repository, including:

• editing
• checking in
• changing file permissions
• renaming files
• removing files
• changing file permissions

This section explains how to do these common BitKeeper operations.

Checking Out And Editing Files

By default BitKeeper repositories do not automatically check-out files. Your directories may appear empty because of this default, to check out (not lock) the files in your current directory,

bk get

You may override this default with the ``checkout'' preference in the config file. See bk help config-etc or the repository cofiguration section.

To check out read only versions of files, use the bk get command.

To check out files for editing, you can either use bk get -e or use the bk edit command. With no arguments, the above commands will check out all the files in the directory. Use file names as arguments to checkout specific files, for example,

bk edit foo.c

It's also possible to use a shortcut to check out a locked version of a file and edit it by doing something like:
bk vi file or bk emacs file
(any editor can be used.)

It is also possible to set the environment such that editor file for example, vi file will check out the file for editing and open the file in vi. To do this:

set EDITOR=vi alias vi=`bk vi`

Again, this will work for any editor, vi is used as an example.

Miscellaneous File Operations

• Changing File Permissions
  BitKeeper stores revision history of file permissions just as it does the file contents. To change file permissions, use

  bk chmod file The command respects whatever syntax your native chmod command uses. It does this by running chmod on the file and then copying the resulting modes into the revision history.

• Renaming Files
  An advantage BitKeeper has over many other configuration management systems is that it keeps track of file names so renaming is easy. To rename a file, do

  bk mv file new_file

  Directories can be renamed in a similar manner with the command:

  bk mvdir dir new_dir

• Removing Files
  There are two ways to remove files from the source tree. The first, and safest, is

  bk rm file

  and the second, and irreversible, is

  bk gone file

  Using bk rm will move the file from your tree into the BitKeeper/deleted directory. All future operations will ignore the file unless you name it explicitly. In the event that you need to resurrect it, you may do that with

  bk unrm file

If you wish to obliterate all traces of a file use the bk gone command as follows:

bk gone `bk prs -hr+ -d:KEY: file` rm file SCCS/s.file

Checking In Changes

After you are done making changes, you will need to check in those changes and create a changeset.

Checking In Files

There are several ways to check in new and modified files. We suggest using the graphical checkin tool because it tends to generate better comments. There are also command line commands that you can use as well.

To run citool, do

bk citool

To use the command line to check in a new file use:

bk new file

or

bk delta -i file

To use the command line to check in modified files use:

bk delta file

or

bk ci file

At some point, either when a logical unit of work is done, or when a team member is ready to share work with the team, the work in the repository should be committed to a changeset. A changeset is a grouping of changes and the smallest thing that can be propagated between repositories. Changesets have their own comments and their own revision numbers, separate and independent of the revision numbers and comments of the file changes it is grouping together. For example:

ChangeSet@1.1036, 2001-02-06 11:25:53-05:00, doogie@work.bitmover.com Added rmgone command. Minor bug fix to lclone. man/man1/bk-rmgone.1 1.1 01/02/06 11:24:31 doogie@work.bitmover.com.com +41 -0 Added rmgone man page. src/bk.sh 1.256 01/02/06 10:52:09 doogie@work.bitmover.com +2 -0 Added a catch for bad options to lclone. src/bk.sh 1.255 01/02/06 10:49:54 doogie@work.bitmover.com +40 -0 Added rmgone command. src/port/unix_platform.sh 1.15 01/02/06 10:46:56 doogie@work.bitmover.com +4 -0 Support for using nawk on Solaris.

The above changeset (revision 1.1036) shows the description of changes to four files plus the comments.

The best way to commit changes to a changeset is to use the bk citool GUI command (for those who want a command line interface, read below about the bk commit command). bk citool combines the actions of checking in files and creating the ChangeSet file. Citool will guide you through entering comments for each of the new or changed files, including the ChangeSet file, displaying the changes you've made so it's very easy to remember what work was done and write appropriate comments. For more information on citool, please see the help page by running bk helptool citool.

For those who would prefer to use a command line interface, a combination of the bk ci and the bk commit commands will create a changeset.. Given without arguments, bk commit will search the repository for files which are in the ``pending'' state, that is, deltas which do not yet belong to a changeset, and groups those files into a new changeset. You will be prompted for comments to describe the changes that have been made. It's useful to have the output of bk pending in another window to see what changes were made to the file.

Sharing Changes

With BitKeeper, because everyone has their own local copy of a repository, it's not immediately obvious to other team members when you have made a change. You must take action to share your changes. When you are ready to do so, you create a changeset by running bk citool or bk commit as described in the previous section Making Changes. After you've created the changeset, you will take the following steps to share your changes:

• find out if anyone working in another repository has changed the same files you have
• if necessary, merge your work
• share your changes with another repository

The details of these steps are as follows:

Updating Your Work Area

After your work has been committed to a changeset as described in the last section, the next step is to pull the latest work from the rest of the team into your repository and resolve any differences. First use the bk pull command to pull work from the master tree. It's actually possible to pull from any tree you like, but if the environment is set up such that you have a staging area where people checkin their work, that's what you'll want to pull.

Merging Conflicts

Assuming there are no overlapping changes, the bk resolve command is automatically run by the pull command and will auto-merge the changes.

If there are conflicts that need to be resolved manually, BitKeeper will output a message about the conflict and save the pulled tree in the RESYNC directory. See Resolving Conflicts for more detailed information.

Sharing the Merged Work

After the the conflicts are resolved, or assuming there were no conflicts to resolve and you're ready to share your work, use the bk push command to share your ChangeSet with the team. This command applies your changes to the main repository and makes it available for others to pull with the bk pull command. Once again, you can push to any repository you like, but if you have a staging area with a master tree set up, that's most likely where you'll push.

Backing Out Changes

There are several ways to see and get back to an earlier version of a file or repository.

File Level

To see version history of a file:

bk revtool file

Sometimes you will want to remove a version of a file. If it is not a part of a changeset you may strip the delta(s) from the revision history by doing:

bk stripdel -rrev

Repository Level

Like the File Level, you may browse the revision history of the repository using

bk revtool

If you have just pulled updates into your repository browse the incoming changes by using:

bk csets

If you find that you do not want those updates, you can remove them from your repository by doing:

bk unpull

If you find a changeset that really should not be in the repository you may use undo to remove that changeset or set of changesets. However, use this with caution, you can not undo an undo. If you want to see the effects of removing a changeset without doing so, use bk cset -x.

bk undo -rrev

If you don't want to remove a changeset, but would like to safely exclude its effects on your tree (you can change your mind later) use:

bk cset -xvers

Advanced Operations

After getting started you can get into more advanced operations.

Resolving Conflicts

A conflict is when two or more people have changed information in different repositories and then try to update. Conflicts need to be resolved before the repositories can be synchronized. In some cases, conflicts that occur during a pull can be auto-merged. In other cases, manual merging must be done. This chapter outlines the manual merge process.

When is a Resolve is Needed?

Upon a pull if there are conflicts that must be auto-merged, the pull will not succeed. The incoming data will be saved in a directory called RESYNC.

Conflicts can occur because:

• file content changes overlap
• permissions changes overlap
• file name changes overlap
• file flags changes overlap
• tag changes overlap

When possible, these changes are auto-merged. If BitKeeper could not merge all conflicts, you will have to do a manual resolution.

Resolve

When a pull does not succeed due to conflicts, to resolve those conflicts, run:

bk resolve

You will be prompted for each type of conflict for each file. For each type of conflict there are available actions you can take, to see a list of available actions hit:

enter

For file content conflicts use the file merge tool by hitting:

F

Resolve all the conflicts in the file merge tool and save.

You will be back at the resolver prompt. If there are more files to merge, do those. If there aren't any more files to merge, commit the merges to a changeset by hitting:

C

While it is OK to quit out of resolve without finishing, the repository will be locked and remain locked until you return to resolve and finish up the merge process.

Merging Content Conflicts

In the file merge tool, the upper windows are the files to be merged. The lower left window is the merged file and the lower right window contains helpful hints. Whatever can be auto-merged will be auto-merged and displayed in the merge window. Unmerged conflicts will be indicated in the merge window and also will be indicated by a red bar above the hints window. You may scroll through unresolved conflicts with the "{" and "}" keys, previous unresolved conflict and next unresolved conflict, respectively. Scroll through all conflicts using "[" and "]", previous unresolved conflict and next unresolved conflict, respectively.

Specifying Older Revisions

One of the advantages of BitKeeper is the ability to ``go backward'' to any previous version of a file or release. There are many ways to do this and it's possible to specify a previous version of a file, a changeset, or a tagged release. This section explains how to specify older revisions at all of these levels.

File level

Sometimes it is necessary to resurrect an old version of a file. To do this it is necessary to

• know the version of the file you want to get - found browsing with revtool
• Get the file as of that revision

  bk revtool file_name bk get -p -rrev file_name > file_name.tmp

ChangeSet level

To revert a repository to a state as of a previous changeset, it is necessary to

• Know the ChangeSet revision - found browsing with revtool
• Clone the repository as of that ChangeSet

  bk revtool bk clone -rrev source_repo dest_repo

Tag level

Resurrecting the repository as of the state of a tag is similar to that for ChangeSets in that it is necessary to

• Know the tag name
• Clone the repository as of that tag

  bk tags # if needed, this will list all tagged changesets bk clone -rtag_name source_repo dest_repo

Note that if a repository is tagged by the same name more than once, the most recent instantiation of that tag name will be will be assumed to be the wanted tag.

Tags

A tag is a symbolic marker that provides a way to save the state of a repository as it was at time T and continue development in that repository while maintaining the ability to go back to how it was as of time T if the need arises. One of BitKeeper's strengths is ease of reproducibility, and tags, while not necessary for reproducibility, make it even easier. Tags are useful when saving stages of stability or when releasing beta versions when development is still occurring in the repositories. People tend to find it much easier to identify a release when it has a name that can be used to refer to it.

This chapter will cover why tags are useful, how to create and delete tags, and how to use tags to re-create a tree as of a certain moment in time.

Creating a Tag

A tag may be created at any time. NOTE: Make sure that the repository has no modified or pending files; use bk status to verify. In the following examples, ``Done'' is the name used when tagging the repository. Any name will do, though using a name that holds meaning is recommended, such as Alpha, Beta, 1.0-release, etc.

If the repository is ready to be tagged with the name ``Done'', type:

bk tag Done

If it is discovered that a changeset should have been tagged after more changesets have been added to the repository, the -r option may be used to select the proper changeset. If the rev to tag is unknown, run bk changes to list all ChangeSets with comments, look through this list to find the revision to tag. Once the revision to tag has been found, type:

bk tag -rrev Done

At Commit Time

A tag may be set when committing a changeset using bk commit:

bk commit -SDone

At this time citool does not permit tagging upon commit. This is a bug and will be fixed.

Updating a Tag

A frequent problem is that a changeset will be tagged with "Done" and then it is discovered that it isn't done. The tag may be updated to the later changeset by running the

bk tag Done

command again. If there are multiple tags with the same name, BitKeeper assumes the most recently applied tag is the "real" tag.

When browsing through a repository's history, you may notice two identical tags. To ensure proper reproducibility, tags are never removed, but rather are updated. To see all tagged changesets, type a ``t'' while in the bottom window of revtool. Use the text search window to find multiple instances of a tag.

Revert to a tree as of Tag

It is frequently helpful to look at a repository as of the state of a tag. To recover the repository as of a tag, use:

bk clone -rDone source_repo dest_repo

Branching

Branching is a means for continuing separate development of one body of code in two or more trees. In BitKeeper, this is accomplished by cloning a new repository. This chapter will explain when to create a clone, how to create the branch, or clone, and work flow between clones.

When to Create a Clone

Branching, should be done when development in a tree starts diverging. Suppose, for example, there is a main line repository called stable. When stable reaches a frozen state near release, only proven code that fixes bugs may be incorporated to that tree, but development must be allowed to continue for both the required bug fixes and for development of the next version of the software. The solution is to create three different repositories for work:

• stable-1.0: The main line repository for the 1.0 release, where only approved bug fixes are incorporated.
• bugfixes-1.0: The repository for developers to work on bug fixes that will, when approved, be incorporated to the stable-1.0 release.
• dev-1.1: The repository to continue development that will become a part of the 1.1 release.

Work Flow
It's fairly common for a software project to branch into stable and bug fixes branches, and the flow of work goes only one way -- work flows to new development branches, but does not travel back from new development branches to old trees. The flow of work for the example above is as follows:

• bugfixes-1.0: Work will be propagated to stable-1.0 and dev-1.1.
• stable-1.0: Work, if any, will be propagated to dev-1.1. Normally, once a release has gone into a frozen state, development would occur in bugfixes rather than stable, and then only scrutinized code would be propagated to stable.
• dev-1.1: Work will never back flow to stable-1.0 nor bugfixes-1.0.

How to Enforce Work Flow

Branching is accomplished in BitKeeper by cloning a repository to another repository and using ``levels''. Levels are arbitrary numbers assigned to the repository that are used to control the flow of changesets between repositories.

To enforce the flow of work, the bk level command is used to set the level of a repository. Setting the level of a repository tells BitKeeper whether or not to allow changes into that repository from another repository with a different level. A repository with no level setting defaults to level 1. The level is automatically set when a repository is cloned to the level of the parent repository.

If the level of repository A is lower than the level of repository B, work may flow from A into B, but not from B into A. If the level of repository A is equal to the level of repository B, work may flow in both directions from A to B and B to A.

In the example above, the level for stable-1.0 is N. The stable-1.0 repository was cloned to bugfixes-1.0 which takes on the level of its parent which is N. The level of dev-1.1, however, should be manually set to N+1 after it has been cloned from stable-1.0 to prevent new development work back flowing to stable-1.0 or bugfixes-1.0.

To check the level of a repository:

cd repository bk level

To set the level of a repository:

cd repository bk level num

Branching and Merging

Once the repository levels are set appropriately, to propagate changes, use the the bk pull command. For example, to incorporate work from stable-1.0 to dev-1.1:

cd dev-1.1 bk pull ../stable-1.0

NOTE: It will most likely be necessary to merge files when propagating changes between branches. See the section on Resolving Conflicts.

Revision Ranges

Many commands can take ranges of deltas as an argument. A range is a continuous sequence of deltas, such as 1.1, 1.2, 1.3, and 1.4. Deltas may be specified by their revision number (1.2), or a symbol (alpha1), or a date (99/07/25).

Specifying by Revisions

Some BitKeeper commands have options that allow the user to specify a revision or range of revisions by revision number (generally, the -r option).

To specify most recent revision:	-r+
To specify a single revision:		-r1.10
To specify a range of revisions:	-r1.2..1.5

Specifying by Dates

Some BitKeeper commands have options that allow the user to specify a date, rather than a revision, as the range. Typically, the -c option is that which allows the date to be specified. If there is only one date specified, without a revision, then a very useful form of the date is to specify a recent period of time.

In the last year:       -c-1Y (or -1y)
In the last month:      -c-1M
In the last week:       -c-1W (or -1w)
In the last day:        -c-1D (or -1d)
In the last hour:       -c-1h
In the last minute:     -c-1m
In the last second:     -c-1s

Revision and Date

If there are two dates, or there is a date and a revision, then the date format is [+\-]YYMMDDHHMMSS with missing fields either rounded up or rounded down. Rounding is explicit if there is a "+" (rounds up) or a "-" (rounds down) prefix on the date. If there is no prefix, then the rounding is context sensitive. If the date is the first date i.e., the starting point, then the date is rounded down. If it is the second date in the range, then it is rounded up. So 98..98 is the same as 980101000000 .. 981231235959.

Remote repositories

Since BitKeeper is designed as a distributed system, there are multiple ways to exchange data between remote repositories. There is a BitKeeper daemon, bkd, which can be used via rsh, ssh, or as a stand-alone daemon, all described below. It is also possible to send and receive BitKeeper repository information via email, which is useful for people with low bandwidth connections or working from a disconnected laptop.

bkd

The BitKeeper daemon, bkd, is used to get information about a repository from a remote machine. A new instance of the daemon is created each time a remote repository is accessed. It is created in one of several ways:

• via rsh/ssh, i.e., "rsh remote host bk bkd -e",
• via ssh as a login shell, and/or
• as a stand-alone daemon, i.e., "bk bkd -d".

BitMover recommends using ssh, since ssh provides a secure channel. The stand-alone daemon method has no security, other than the ability to run in read-only mode. If security is a requirement, use ssh to get to the daemon. The method used is determined by how the remote repository is referenced, as follows:

• host:pathname
  Uses ssh (by default) to access host, and starts a temporary bkd. If $BK_RSH is set, then bkd uses that to talk to the host (allows proxying). If no ssh is found then rsh is used.
• bk://host
  Connects to an existing bkd on the default bkd port. The bkd must be at the root of the repository.
• bk::/host/pathname
  Connects to an existing bkd on the default bkd port, changes to pathname, then runs command.
• bk://host:port
  Connects to an existing bkd on the specified port. The bkd must be at the root of the repository.
• bk://host:port/pathname
  Connects to an existing bkd on the specified port, changes to pathname, then runs the command.
• bk://user@host
  Connects to host using ssh, and assumes that bkd is the login shell. The home directory of user must be the root of the repository.
• bk://user@host/pathname
  Connects to host using ssh, and assumes that bkd is the login shell. Changes directories to the specified pathname, which may be relative to the home directory or an absolute pathname.

Anonymous Access

The most common use of the stand-alone daemon is for anonymous access to a repository. To provide read-only, anonymous access, you can run:

bk bkd -d -xpush

This will allow anyone to read (but not write) all repositories on the system running the daemon.

If you want to export a single repository, pick a port number, and do this:

cd /u/linux bk bkd -d -p5555 -xcd -xpush

This says to run in daemon mode, bind to port 5555, and disallow the "cd" and "push" commands. By disallowing the "cd" command, the daemon at port 5555 is tied to the repository in the current working directory (bkd needs to be run at the root of the repository). By disallowing the "push" command, the repository is protected from updates.

Clients would then get to this repository by using the BitKeeper URL of:

bk://host.domain:5555

i.e.,

$ bk clone bk://host.domain:5555 my_tree

If you want to have a repository which allows the world to read it, but restricts write access to a select few, you would use bkd to give out read only access, and tell people the BitKeeper URL for the foo project is:

bk://someplace.com:5000

For both read and write access that you want to give to a few trusted people, you would give them ssh access to a machine with a clone into which you allow pushes. Suppose your bk://someplace.com:5000 is really someplace.com:/home/bk/foo. You would then give your trusted friends a login on someplace.com and tell them the bk URL they want to use is someplace.com:/home/bk/foo, that is, they would say:

bk clone someplace.com:/home/bk/foo foo

When they then push back to that location, they will be prompted for an ssh password that allows them to push.

Please see bk helptool bkd and bk helptool Howto-bkd for more information and bkd examples.

Sending Changes via Email

The bk send command is used in lieu of bk push when the only connection to a remote machine is through email. To send a complete repository, use:

$ bk send user@host.com

BitKeeper then generates a very large patch and mails it to user@host.com. To keep the size of the patch to a minimum, if you know a specific change you want to send (and you know that the other repository has the changes leading up to the change you want to send), you can do this:

$ bk send -rbeta.. user@host.com

or

$ bk send -r1.10.. user@host.com

Send remembers the changesets it has sent in BitKeeper/log/sendlog-address where address is like user@host.com. When you don't specify a list of changesets to send, bk send will look in the log file and send only the new changesets. The easiest thing to do is to always use the same email address and just say:

$ bk send user@host.com

If you lose the log file and you want to send it with the changes you know have been sent, the command to do that is:

$ cd package-root $ bk prs -h -rrevs -d:KEY: ChangeSet > BitKeeper/log/send-user@host.com

You can wrap patches so that they do not get corrupted by mailers. BitKeeper currently supports wrapping with uuencode. The following (contrived) command sends a wrapped patch and applies it in /tmp/foo (which must exist):

$ bk send -wuu -r..1.5 | bk receive /tmp/foo

Receiving Changes via Email

The bk receive command is used to apply a BitKeeper patch that was received via email. If you receive an email message that is a BitKeeper patch, save the message and feed it to the receive command as follows:

$ bk receive ~/mypackage < patch

Headers and footers are automatically stripped from the message. Note that if you don't yet have a repository created for this patch, you must use the -i option to bk receive in order to create a new repository.

Specifying the repository is optional; if it is unspecified, receive tries to use the current working directory.

Advanced Topics

This chapter provides information on how and why things work the way they do with BitKeeper, rather than how to accomplish specific tasks. The following topics are covered:

• Description of a BitKeeper repository's structure
• Supported file types
• Repository interactions
• Deleting repositories
• BitKeeper limitations on names, including illegal characters
• Specifying older revisions and revision ranges
• How to specify revision ranges to BitKeeper commands

Repository Structure

When a BitKeeper repository is setup, a number of directories are created for the storing of metadata associated with the revision history. All the directories live beneath the ``BitKeeper'' directory in the repository. The subdirectories are as follows:

• etc - contains configuration files
• log - contains mail and command logs, and the repository parent pointer.
• deleted - deleted files are archived here (similar to the CVS ``Attic'').
• tmp - scratch area.
• readers - Transient directory for reader locks.
• writer - Transient directory for writer lock.
• triggers - Executable trigger programs are stored here.

In addition to the directories that get created, there are a number of files associated with each file kept under revision control, as follows:

• foo.c - your source file (the gfile, or ``gotten'' file).
• SCCS/s.foo.c - the revision history of all versions of the gfile, known as the ``s.file''.
• SCCS/p.foo.c - the lock file, created when the file is edited, known as the ``p.file''.
• SCCS/z.foo.c - a lock file created when locking or checking in a new version, known as the ``z.file''.
• SCCS/x.foo.c - a temporary file containing the new version of the s.file under construction. When the checkin is finished, the s.file is removed and this ``x.file'' is moved in its place.
• SCCS/b.foo.c - a temporary backup of local s.file while resolve is applying new files. If all goes well, these files, the ``b.files'', are removed, but if the application fails, the b.files are moved back in place.
• SCCS/c.foo.c - a temporary copy of check-in comments, currently used only by bk citool.

Note that these files are for BitKeeper's use only and may be placed in a different location in the future.

File Types

BitKeeper can be used to track history on source code, documentation files, web pages, etc.

The BitKeeper file types are

• text (ordinary files such as source code)
• binary (images, word docs, etc.)
• symbolic links (Unix only)

It is not possible to switch the type of a file from binary to text or vice versa at this time.

Some of the tools, such as bk difftool, aren't appropriate for binary files.

A common recommended practice is to not include any kind of generated output files under any kind of revision control. If you have the input files and the process itself stored in a source management system such as BitKeeper, then you have what you need to reproduce the generated output.

Repository Interactions

Repositories have a notion of ``parent/child'' relationships, established at the time of the clone. When the clone command is run, the default parent, or parent pointer, is set to the originating repository. Note that it's possible for a repository to be both a parent and a child, if someone clones from a cloned repository.

Moving data between BitKeeper repositories is generally done using bk pull and bk push. These commands, by default, communicate with the parent, but data can be shared with a repository other than the parent in a couple of ways:

• The bk pull and bk push commands can be given an alternate_repository argument to specify a one-time change in communication.
• For multiple operations, it is possible to reset a repository's parent by using the bk parent command with an argument of the new parent. The bk parent command with no argument displays the name of the parent pointer.

It's important to note that because BitKeeper has a star topology and its possible to share data with any repository, it's not necessarily recommended. The parent pointer shorthand was designed to guide the user to a defined structure for repository interactions. BitKeeper allows data to flow any direction, but in practice you don't necessarily want it that way. It's good practice to think about how the data should flow. BitMover provides consulting on this for commerical customers who have purchased 25 or more seats.

Deleting a Repository

Before deleting a repository, make sure you do not want it anymore.
Please be aware this action is not reversible.

• Verify whether or not the repository is a master repository
• Make sure there are no pending changes that should be pushed
• Delete the repository

A repository is a master repository if it has no parent. To check:

cd repository bk parent

If this is a master repository, the message

This package has no parent

will be displayed. If you do not know whether a repository is a master repository or not, please consult the person in charge.

To find pending changes or modified files:

bk status

Review the output. If there are any:

• files not under revision control
• files modified
• files with uncommitted deltas

you should verify you will never need that work. If there's any chance the work may be needed, make sure it's in a safe repository somewhere before deleting this copy of the repository.

Deleting a repository in bk is just like removing any other directory:

rm -rf path_to_repository

If the repository that is being deleted has children, be sure to reset those repositories' parents:

cd child_repo bk parent /new_parent/path

Name and String Limitations

BitKeeper has the following limitations for file names and contents:

• File Names
  There are several characters to be aware of when naming files:
  * The "|" character
  * The "/" character on Unix
  * The space character
  BitKeeper does not allow the pipe, "|", character in file names, Unix users should quote file names that contain a slash, "/".
  If a repository is going to be used by developers on both Unix and windows, it is important to remember that windows does not distinguish between upper and lower case letters, but Unix does distinguish between the cases so choose file names accordingly.

• File Content
  BitKeeper does not support null characters in an ascii file's contents. If it discovers a null character in a file, BitKeeper treats the file as if it is binary and will uuencode the file.

• Path/Name lengths
  Full path names to a file is limited to 1023 characters in length.

Reporting and Data Mining

BitKeeper is essentially a database of everything that has ever happened with your source base. Your source base becomes an invaluable resource of information about what was done when and by whom. There are many ways to go about mining for this data. This chapter explains how to get at that information, whether it be by a quick one-time command or a regularly-run generated report that shows a particular group's activities for a period of time.

File Level

File State Information

File State Information is general information about how many files are in a particular state. This includes information such as how many files are checked out; how many files are not under BitKeeper control; and how many files have checked-in deltas, but have not been committed to a changeset.

To find out the number of files in a repository that are under revision control, not under revision control, modified (not checked in), checked in (not committed) use:

bk status

To find which files are modified, but not yet checked in:

bk -r sfiles -gc

To find which files are pending (checked in, but not yet committed):

bk pending

To find all files the are not under revision control:

bk -r sfiles -gx

There are many options to bk sfiles that will give specific file information in the output. To see a more detailed list please look at the help page

bk helptool sfiles

File revision history

File revision history is all the information collected about a file as it changes over time.

GUI-tools

File revision history is probably best viewed graphically by bk revtool.

Upon startup, the bottom window displays the last month's revision history for the file or project.

To view the comments for just one revision, left click once on that revision in the graph.

To see the differences between two revisions, left click the older revision and right click on the newer revision. The differences will be displayed in the lower text window. Right click on another revision to diff with another revision. The default diff format is -u (unified diffs).

To see the contents of a file, double click the left mouse button on the revision node in the graph. The text shown for the file is annotated with the user name and the latest revision that modified the line.

Once the annotated file listing is shown, you can then click on the text to view the checkin comments associated with the chosen line. Double clicking on an annotated line brings up csettool and shows all of the other files that were modified in the same changeset as the selected line.

To get a side-by-side view of the differences, select the two revisions and click on the "Diff tool" button.

Command Line Interface

BitKeeper has commands that will do the equivalent of bk revtool described above. The information must be extracted by various bk commands, as follows:

To get a list of revisions of a file with revision comments:

bk sccslog file

The above could also be done with:

bk prs file

prs is a superset of sccslog, and used with options, is a powerful reporting tool for scripting. For more information on prs and scripting reports, see Reporting with Scripting.

To display a line-by-line listing of a file showing who modified each line and in what version number of the file it was modified, use:

bk annotate file

There are useful options to bk annotate to give more detailed information in the annotations including prefixing each line with the date it was modified, line number, and filename. Please see Command Summary for details.

To restrict the set of lines displayed to those lines added in a specified revision or date range use:

bk sccscat -rrev

or

bk sccscat -cdate

In this case, the whole file is not displayed, instead, only the lines which were added in that range of changes are displayed.

To display all lines in all versions of a file use:

bk sccscat file

This is useful for determining when a particular feature was added.

File Contents

Contents of a single revision

To view contents of a single revision of a file you may use bk get to get any revision of a file. If the revision wanted is not known, bk prs may be used to get a listing of each file revision with revision comments.

bk prs file bk get -rrev file

File content comparisons (one file)

There are two methods to do file content comparisons: via the GUI tools or via the command line.

To do file content comparisons via the GUI tools, use bk difftool. Differences between any two revisions of a file can be viewed, including the latest modified but not yet checked in version. It's also possible to compare files in different repositories with difftool. To see the differences between the latest modified version of a file and the latest checked in version of the file, use:

bk difftool file

To see the differences between the modified version of a file and another revision:

bk difftool -rrev file

To see the differences between any two specific revisions of a file:

bk difftool -rrev1 -rrev2

To see the differences between a file in one repository and a file in a different repository:

bk difftool /somepath/file1 /someotherpath/file2

To do file content comparisons via the command line, use bk diffs. Differences between the modified version of a file with the last checked in revision of that file, between any two revisions of a file in a repository, or between a specific revision and its preceding revision can be displayed. There is also the ability to do side-by-side diffs as well as author, date, and/or revision annotations if desired. To view the differences between a modified file and the last checked in version of that file, use:

bk diffs file

To view the differences between a modified file and any previous version of that file:

bk diffs -rrev file

To view the differences between any two revisions of a file:

bk diffs -rrev1..rev2 file

To view the differences between a specific revision and its preceding revision:

bk diffs -Rrev file

There is also the ability to do side-by-side diffs as well as author, date, and/or revision annotations if desired. To do that use the options shown below individually or in combination to produce the desired output.

To do side-by-side diffs:

bk diffs -s

To prefix lines with author annotations:

bk diffs -U

To prefix lines with the revision date annotations:

bk diffs -D

To prefix files with revision numbers:

bk diffs -M

As an example, suppose a side-by-side view of differences of revision 1.5 and 1.14 of file foo.c with author and date annotations is desired. To accomplish this the following command could be issued:

bk diffs -sDU -r1.5..1.14 foo.c

File content comparisons (all files in a directory or repository)

Sometimes it is desired to see all the file changes made in a directory or repository since the last time the files were checked out.

To view all differences of all modified files in one directory with the corresponding last checked in files (sometimes this output is very long so piping to more or less may be useful), use:

bk diffs | more

To view all differences of all modified files in a repository with the corresponding last checked in files (sometimes this output is very long so piping to more or less may be useful):

bk -r diffs | more

Project Level

At the project, or repository, level there are many items which are tracked and can be used to get an overall view of the evolution of the project. You can:

• view the history of the project over time
• get a detailed view of particular changesets
• get a listing of all tagged changesets

All of which can help get the high level picture of what is going on in a project.

Viewing Project History

To see an overall picture of what's been happening in a repository, you would view the history of the ChangeSets in that repository as follows:

bk revtool

When launched the tool shows all ChangeSets for the repository. To view a specific ChangeSet, click on that ChangeSet box in the graph that's displayed in the upper window.

To find which files are associated with a ChangeSet, double click on the ChangeSet box.

To view changes made over a range of ChangeSets, left click on the ChangeSet with the lower revision number then right click on the ChangeSet with the higher revision number, and the cumulative list will be displayed in the lower window.

Viewing ChangeSet Contents

To get a detailed view of the last applied ChangeSet's contents, use

bk csettool

Csettool will show:

• associated changeset comments
• a list of changed files
• revision comments for files associated with the changeset
• the differences between each file and the revision from the previous changeset

Csettool can also be launched from revtool by selecting a ChangeSet or range of ChangeSets and clicking on the View ChangeSets button in the top of the window.

Viewing Tagged ChangeSets

To get a list of all changesets which have been tagged use

bk changes -t

If finding this information is done as part of a script, using prs may be more useful:

bk -R prs -hr1.0.. -nd'$if(:TAG:){:DEFAULT:}' ChangeSet

Command History

Each BitKeeper repository keeps logs of the commands run in that repository. To get a history of the repository level commands, which are clone, commit, export, pull, and push use:

bk cmdlog

To get a history of all commands run in a repository use:

bk cmdlog -a

Debugging with BitKeeper

BitKeeper makes debugging a faster process than can be found in other systems due to the differing levels of information gathered by the tool at the file level, changeset level, and repository level.

There are a couple of different types of bugs that will be explained and then a process for debugging each kind of bug will be demonstrated.

Build Bugs

Build bugs are failures that occur during the build of a product. These can be anything from a missing semi-colon at the end of a line of c-code to a missing include file. Most often, the information needed is what file broke the build and who made the change in the file that broke the build.

If the offending file is known, use bk revtool to find all the changes made to the file between the last build and the present build. Revtool shows the differences between any two versions of the file by left clicking on the last known good version of the file and right clicking on the buggy version of the file. Scanning the differences may make clear the line that broke the build. The differences are annotated with the user who last changed the line so if the line that introduced the bug is found, so is the author.

Functionality Bugs

Functionality bugs are unwanted and unexpected behavioral problems with the software as its running. Most often the process of tracking down a bug is: first find what file and what revision the problem is in, second is finding the changeset containing that revision of the file, and then have the engineer who caused the bug fix it.

If a particular string is known, an error message for example, bk grep can help find the file and revision of the file that contains the particular string (and hopefully, the bug). The default output is annotated with file name and revision number. If you have a general idea in which directory to check, use:

bk grep string

if not, it is possible to do the search on all files in a repository by doing:

bk -r grep string

If the file has already been found (this can sometimes be accomplished by an assertion or core file) run revtool on the file.

bk revtool file

Using revtool on the file, information about what was introduced in various revisions of the file can be found. When the revision that caused the bug is found, click on the View Changesets button, to see all the files associated with the one that caused the bug. This will give a picture of what happened at a particular point in time to help illuminate the problem.

When All Else Fails - Binary Search

BitKeeper employs the concept of binary search when trying to track down elusive bugs. A range of time of when the bug was introduced is needed. This can be sometime between the first changeset and the last changeset, or it can be sometime between the last known good version and the first known bad version. The range can be anything as long as the lower bound does not have the bug and the upper bound does have the bug. The lower bound is the earlier cset (without the bug) and the upper bound is the later cset (with the bug).

Choose the changeset that occurs in the middle of the upper and lower bound. Clone the repository as of that changeset to a new repository and build the product.

bk clone -rmiddle_cset repository /tmp/repository make product

Check if the resulting product has the bug. If so, the middle changeset is now the new upper bound. If not, the middle changeset is now the lower bound. Repeat.

Code Reviews

Code reviews are the checking of a developer's code by one or more reviewers to determine whether or not that code is suitable for integration with the main source base.

Code reviews can be done using the Request To Integrate (RTI) process. This is done by "queuing" changes against a "gate".

Queue

A gate is the integration tree, it has what is believed to be good changesets. Things normally don't go into the gate unless they have passed peer review and regression tests on all platforms.

Have a gate for each active release. For example, for BitKeeper we have 3.2.x and 3.3.x plus other shorter lived gates coming and going as needed. For each gate there is a gate queue. You can do this all on a file server like so

	/home/bk
	    bk-3.2.x - 3.2.x gate
	    bk-3.2.x-queue - changes which are ready, done, rejected
	    bk-3.3.x - 3.3.x gate
	    bk-3.3.x-queue - changes which are ready, done, rejected
	    etc.

	ready/
	done/
	rejected/

	ready/feature - symlink to the repository containing the change
	ready/feature.RTI - text file containing the reason why this is needed
	ready/feature.REVIEWED - text file containing review comments

Process

The process to go through is:

• Engineer creates a repository which is a clone of the gate and then develops the new feature. Use hardlinked clones, if possible, as it takes up less space.
• Engineer feels the feature is ready and creates a symlink to the repository in the ready directory of the appropriate queue.
• Engineer sends email to the reviewers that feature is queued.
• Reviewers review and add comments to feature.REVIEWED.
• If the feature is accepted the "gatekeeper" can pull the change into the gate and move all feature related repositories and files to the done directory.
• If the review comments are negative then the engineer does a

  bk fix -c

  on the repository, fixes the problem, and starts the review process again.

Reporting with Scripting

Information about files or sets of files can be found using bk prs, a command used to extract revision history and or metadata from a file or set of files. There are many options to prs, making it a powerful query language for the BitKeeper database which is your source base. The default behavior is to print a summary of each revision to each of the specified files. There are options to restrict the set if revisions to print, a very commonly used one is -r+ which restricts the set to the most recent revision.

With no options specified, prs output defaults to giving information on all revisions of all files under BitKeeper control in the present directory. The filename and range of revisions is listed first, offset by === characters. Below that line, for each revision prs lists: revision number, revision date and time, user who made that revision, what the relative path from root of repository is to that file, the comments that go with that revision, and any renames that have occurred, if appropriate. Revision information is repeated from most recent to oldest, separated by a a line of ---\characters. Once the oldest revision information is listed, then the sequence will repeat with the next file in the directory.

Output Format
The bk prs command has a default output format which can be overridden. There are many different pieces of information in a BitKeeper file and bk prs can extract most of them. To extract specific information, a dspec (data specification) string must be provided and should contain keywords, surrounded by colons. bk prs will expand each of these keywords in the output it produces.

To specify a TAB character in the output, use \t; to specify a NEWLINE in the output, use \n; An example dspec which prints the file name (s.file) and the revision number is

bk prs -d':SFILE: :REV:\n' file

In almost all cases, a trailing newline is not provided by any of the variables and one should be provided as needed. The list of variables which currently provide one are: COMMENTS, PATH, DEFAULT, SYMBOLS.

If a multi-line variable is printed as one line, i.e., without $each() (see below) providing a prefix and/or a suffix, then the lines are separated by spaces. The list of variables with this behavior is: C, GB, FD.

Conditional Output
The dspec can produce output conditionally. The following will print the default output format for each revision made by lm:

bk prs -d'$if(:P:=lm){:DEFAULT:}' file

Conditional Statements

BK/Web

BK/Web is an interface for browsing repositories using the web. A project's ChangeSets, user statistics, the source tree and the tags in a tree can all be browsed using the BK/Web interface.

Appendix A: Installation

This appendix explains how to install BitKeeper, including:

• Installing the Software
• Getting a License After Completing these steps you will be able to run BitKeeper.

Installing The Software

This section describes how to install BitKeeper. There are four steps to installing and verifying the BitKeeper installation:

• Figuring out which software to download
• Downloading the software
• Installing it on the machine
• Running regression tests

Once the four steps are accomplished, BitKeeper will be ready for use.

Supported Platforms

The download area contains a a number of images for different platforms. If you are wondering which one is the right image for your platform, the table below may help. The release number portion of the image name may be different as we release new releases but the architecture portion should always be the same.

Platform name	Download image name
AIX 4.1.5 and later	bk-3.2.4-powerpc-aix.bin
FreeBSD 2.x	bk-3.2.4-x86-freebsd2.bin
FreeBSD 3.x	bk-3.2.4-x86-freebsd3.bin
FreeBSD 4.x	bk-3.2.4-x86-freebsd4.bin
FreeBSD 5.x	bk-3.2.4-x86-freebsd5.bin
HPUX 10.20	bk-3.2.4-hppa-hpux10.bin
HPUX 11.x	bk-3.2.4-hppa-hpux11.bin
IRIX 6.5 and later	bk-3.2.4-mips-irix.bin
Linux/Alpha	bk-3.2.4-alpha-glibc22-linux.bin
Linux/Itanium	bk-3.2.4-ia64-glibc23-linux.bin
Linux/MIPS	bk-3.2.4-mips-glibc22-linux.bin
Linux/PARISC	bk-3.2.4-hppa-glibc23-linux.bin
Linux/PPC	bk-3.2.4-powerpc-glibc23-linux.bin
Linux/SPARC	bk-3.2.4-sparc-glibc23-linux.bin
Linux/StrongARM	bk-3.2.4-arm-glibc21-linux.bin
Linux/x86 (Glibc 2.0)	bk-3.2.4-x86-glibc20-linux.bin
Linux/x86 (Glibc 2.1)	bk-3.2.4-x86-glibc21-linux.bin
Linux/x86 (Glibc 2.2)	bk-3.2.4-x86-glibc22-linux.bin
Linux/x86 (Glibc 2.3)	bk-3.2.4-x86-glibc23-linux.bin
MacOS X	bk-3.2.4a-powerpc-macosx.bin
NetBSD/x86	bk-3.2.4-x86-netbsd.bin
OpenBSD/x86	bk-3.2.4-x86-openbsd.bin
Solaris/SPARC	bk-3.2.4-sparc-solaris.bin
Solaris/x86	bk-3.2.4-x86-solaris.bin
Windows (all releases)	bk-3.2.4-x86-win32.exe

Downloading Software

Go to www.bitkeeper.com, click on downloads in the left column, and then click on "Go here to download BitKeeper".

You will be asked for your name and email address. Once you submit your request for downloading instructions an email will be sent to the address you entered. Follow the download instructions sent, noting the login and password.

Read the license.

At the end of the license there are directories of BitKeeper releases. Click on the directory of the latest version of BitKeeper. There will be a list of BitKeeper binaries. The binary names are in the form

cpu_type-OperatingSystem.file_type

Click on the one that corresponds to the system upon which BitKeeper will be installed. Specify the destination directory and file name and click the "okay" button.

Installing on Unix

Once downloaded, change the permissions and execute the binary. For example, if the x86-glibc21-linux.bin binary was downloaded,

chmod +x x86-glibc21-linux.bin ./x86-glibc21-linux.bin

Enter the directory to install, /usr/libexec is recommended, and hit return.

At this point BitKeeper should be installed and the BitKeeper regression tests should be run to verify the installation. Please see the Trouble Shooting section or contact support@bitmover.com if there are problems regarding the installation.

Installing on Windows

Once downloaded, double-click on the executable file to launch the BitKeeper installer. The installer will take a series of steps. The default installation is recommended for new users and can be accomplished by simply clicking on the Next, Okay, or yes buttons as they appear. The following is a more detailed look at the windows installation.

Once the installer is running, you may click Cancel at any time to abort the installation. In the first installation window, if you are in agreement with the license and copyright and are ready to proceed, click the Next button. The default destination folder is C:\Program Files\BitKeeper. If you would like to change the destination folder you may do that via the Browse... button. Once the destination folder is chosen, click on the Next button. In the next window, choose the Program Manager group, the default is BitKeeper. Once you choose the Program Manager group click the Next button. In the next window, you may choose Back to change a setting, Cancel to abort the installation, or Next to install the BitKeeper software.

BitKeeper requires cygwin and will attempt to install version 1.1.5 if it is not detected on the computer. Click Yes to install 1.1.5 or No to abort the installation. Read the message box with "Important Instruction" and click OK button when finished. To begin installation click Next. Choose Install From Local Directory and click Next. In the local package directory window click Next. Select the install root directory via Browse... button if the default is not correct. Make sure the "DOS text file type" and the correct "Install for" option are chosen and click Next.

At this point BitKeeper and cygwin should be installed and the BitKeeper regression tests should be run to verify the installation. Please contact support@bitmover.com if there are problems regarding the installation.

Verifying the installation

BitKeeper should now be installed. To verify, run the bk regression tests on the system as follows:

bk regression

At this point you should have downloaded BitKeeper, installed it, and run the regression tests on your system. If the regression tests did not pass please send mail to support@bitmover.com.

Getting a License

BitKeeper has three licensing models that are implemented depending on the user's preferences:

• Single User License
• Multi-User License with Open Logging
• Commercial License

The use of BitKeeper with the Single User License is free. Please read the BitKeeper License for terms. If this model is appropriate for you, add lines to the BitKeeper/etc/config file as follows:

single_user:username single_host:hostname

The use of BitKeeper for multiple users with Open Logging is also free. Please read the BitKeeper License for terms. If this model is appropriate for you, add lines to the BitKeeper/etc/config file as follows:

single_user:username single_host:hostname

The use of BitKeeper for multiple users without Open Logging enabled requires a commercial license key. You can get a temporary license by sending an email request to bk_license@bitmover.com. The system is automated so responses should be almost immediate.

Once you have the license key add a line to BitKeeper/etc/config file:

license:license_key

Please see Repository Configuration for further explanation of configuring BitKeeper.

Appendix B: Administration

BitKeeper is designed to work ``out of the box'' but it was also designed with flexibility in mind. It is possible to change the default configuration of the look and feel, to set up a list of files to be ignored by BitKeeper, and to enforce a software development policy you have in mind. This section describes how to do those things, plus gives you instructions on what to do if something ``goes wrong''.

Backups

One way to back up a repository is to have a trigger to push to a mirror repository every time an incoming push to the master repository occurs. So, if a developer pushes into Master, master pushes to the mirror. And the mirror only accepts pushes from Master, no one else. For more information see

bk helptool triggers

Another way to do this is with traditional backup tools. BitKeeper repositories with no pending files can be safely backed up with any backup tool, such as tar or dump, etc. To see if there are any pending files, run

bk pending

No output indicates no pending files.

WARNING
If the repository has pending files (files which are checked in but not yet committed to a changeset), then saving and restoring the repository should be done carefully. Problems can arise if the repository is restored multiple times and the same pending deltas are committed to different changesets. In other words, the following will cause problems:

cd REPO bk edit foo.c echo "I am a pending delta not yet committed" >> foo.c bk delta -yPENDING foo.c cd .. cp -r REPO COPY cd REPO bk commit cd ../COPY bk commit

Why is it a problem? Because the two commits both created a changeset, and the changesets are different. This means that the same delta to foo.c now belongs to two different changesets. It is not fatal when this happens, but it may make it difficult to roll backwards to this point.