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.