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.