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