Point your browser to: http://www.bitkeeper.com/Products.Downloads.html
And follow the instructions.

"Do I have fill out the forms and wait for email every time I update BitKeeper?"

No, once you have the username and password for the download site, you may use that to access the download area any time you want to update BitKeeper.

bk clone bk://linux@linux.bkbits.net/linux-2.4 mylinux-2.4 bk clone bk://linux@linux.bkbits.net/linux-2.6 mylinux-2.6

You now have a copy of the Linux 2.4.x source tree in the directory ``mylinux-2.4'' and a copy of the Linux 2.6.x in the directory ``mylinux-2.6''.

"I cloned the tree, but all I see are directories. Where are all the files?"

BitKeeper does not automatically check-out files unless configured to do so. To get all your files, change directory into the top-level directory of your repository and run:

bk -r co

This will recursively descend each directory in the repository and check out every file read-only. Although it is not recommended, if you prefer to have all your files checked out read/write, run:

bk -r edit

This will increase the total number of administrative files in your repository which wastes disk space and can make other operations run slower, unnecessarily.

You may configure your repository to do auto-checkouts. For more information, see

bk help config-etc

"I want to make some changes, what do I do?"

For each file you want to edit, run:

bk edit filename

Do not change the write permissions of a checked out file directly. If you just change the file permissions of the checked out file to make it writable, bk will be put in an inconsistent state and will not let you check in your changes.

For a convenient shortcut, read through the editor help page, and follow the directions for making bk checkout files read/write before editing them:

bk help editor

"What is a changeset?"

A changeset is a grouping of one or more changes to one or more files. Each changeset has comments and revision numbers associated with it apart from the comments and revision numbers associated with the individual files.

"What's the difference between check in and commit?"

Changes to individual files are checked in. A commit groups checked in changes together in a changeset.

"How do I check in and commit my changes?"

You may use the command line or the graphical check-in tool to check in and commit changes. The graphical check-in tool is the preferred method because people make better comments when they can browse the changes.

Graphical
To use the graphical tool, run:

bk citool

The top window shows modified files and files not under revision control. The middle window is the comments window and the bottom window shows the diffs for a modified file and the contents of a new file.

Clicking on a file name will select it for making comments. When comments are made to a file, it is ready for inclusion into a changeset. If not creating a changeset, after all comments are made, click on the Quit button and save comments.

If you are ready to commit your changes to a changeset, select the ChangeSet file in the citool file list and add comments. By default, all files with comments and all extra files that have been chosen for inclusion will go into the changeset. You may toggle between including/excluding a file from a changeset by left-clicking on the icon to the left of the file name. Click on commit twice to commit the changes to a changeset.

Command Line
If you prefer a non-graphical check in tool, you can check in individual files with:

bk ci

And to group all currently checked in changes into a changeset, run:

bk commit

"When I check in, will my changes appear in the main repository?"

No! When you check in or commit your changes, only your local copy of the repository is altered. To update another repository, run:

bk push [remote_repository]

"I just checked in some changes and now the changed files are gone!"

By default, bk will not check out a file after checking it in. To check it back out, run:

bk co filename

If you would like bk to auto-checkout your files, you must configure the repository to be in checkout-get mode. To configure the repository to run in checkout-get mode, do the following:

bk edit BitKeeper/etc/config echo -e ``\\n[]checkout:get'' >> BitKeeper/etc/config bk citool # check in the config change

Note that the BitKeeper administrative files are also revision controlled, so this change will show up in your revision history.

For more information about repository configuration, please see

bk helptool config-etc

"I just checked in some changes, and now I'm getting weird compile errors!"

The pre-kbuild 2.5 Linux build system has some interesting quirks. One of these quirks is that if a required header file doesn't exist (because you just checked it in and it wasn't checked back out), it creates an empty file with the correct name. Naturally, this causes compile errors.

To fix this problem, remove all zero length header files in include/:

find include/ -size 0 -name '*.h' -exec rm {} \\;

Check out the files read-only:

bk -rinclude co

Most kernel developers set up their repositories to automatically recheck out checked in files read-only, by adding ``[]checkout:get'' to the end of their BitKeeper/etc/config file. See the previous question for details on how to do that.

"I'm trying to edit a file, but bk tells me that a writable copy already exists."

See the answer to the next question.

"I edited some files, but when I try to check them in, citool isn't finding them."

For some reason, the file you changed was not marked as ``edited'' but was changed to writable. To mark all writable files as edited without overwriting your changes, run:

bk -r check -f

To list all files that are writable but not edited, run:

bk -r check -w

"I made some changes, but they don't appear when I run ``bk revtool''."

Running ``bk revtool'' without arguments tells it to show you a graph of the changesets in the repository. If you haven't created a changeset, you won't see your changes in the changeset graph.

To view history of a particular file, run:

bk revtool filename

"How do I view all my un-checked in changes?"

Run:

bk sfiles -gc | bk difftool -

Or, if you prefer non-graphical tools:

bk -r diffs

"How do I create a patch?"

It depends on what you want to create a patch from. If you want to create a patch containing all the changes in one changeset, run:

bk export -tpatch -rrev > ../patchfile

If you want to create a patch containing all the changes in a range of changesets, run:

bk export -tpatch -rrev1,rev2 > ../patchfile

If you want to create a patch containing only the un-checked in changes in your tree:

bk -r diffs -u > ../patchfile

If you want to create a patch containing the un-checked in changes in your tree plus the checked in but not yet committed changes:

bk diffs -u -Clast_changeset_rev > ../patchfile

"How do I apply a patch?"

You can do this two separate ways, the first is with the normal patch command:

patch -p1 < ../patchfile

The patch command will automatically attempt to check out each affected file in read/write mode, since patch knows about SCCS, and BitKeeper is SCCS compatible. The second way is with the BitKeeper import command:

bk import -tpatch ../patchfile .

"How do I send changes to other developers?"

It depends. We'll talk only about the technical aspects of sending changes around using BitKeeper, not the politics or etiquette of sending changes.

If your changes are in a publicly accessible BitKeeper repository, tell other developers to run:

bk clone bk_url

Or if the other developer already has a clone of the same repository:

bk pull bk_url

Be aware that the other developer will get all your committed changes.

Otherwise, create a GNU patch using the directions from the ``How do I create a patch?'' question and send that.

"How do I update my tree?"

Run:

bk pull

If the parent tree (the one you cloned this tree from) has moved since you cloned it, run this first:

bk parent bk_url

"Can I undo my last set of changes?"

Yes, but it depends on what set of changes you want to undo.

To undo the last changeset:

bk undo -rrev

To undo all the changesets after a certain revision:

bk undo -arev

To undo a changeset which is in the middle of a series of changesets:

bk cset -xrev

To undo changes to an un-checked in file:

bk unedit filename

To undo the checked in but not committed changes to one file:

bk revtool filename # Find rev number bk stripdel -rrev file

To undo all changes from the last pull:

bk unpull

"I canceled a pull and now my tree is locked, how do I unlock it?"

Abort the pull with:

bk abort

"bk pull failed, what do I do now?"

If one of the last output lines was something like:

resolve: 1 unresolved conflicts, nothing is applied.

Then the auto-merge algorithm couldn't resolve a conflict and you need to resolve it by hand. Run:

bk resolve

And follow the menu prompts to finish the resolve. Choose 'f' to run the 3-way graphical merge tool.

"bk push failed, something about being 7 changesets ahead of my repository?"

You need to pull all the changesets in the parent repository and merge them before you can push your local changes to the parent.

bk pull bk push

Merges only happen on pulls, for several reasons. The most important reason is that if you push to a parent repository used by several other people and you need to hand-merge some changes, the repository will be locked for several minutes and no one else will be able to push to it during that time.

"Pushes and pulls hang when using bk over ssh."

This is a bug in OpenSSH, which is fixed in version 2.9.9. Upgrade your version of OpenSSH.

"How do I set up an ssh accessible tree for multiple read/write users?"

The easiest way is to have one user on the hosting machine that owns the files in the repository. Then put ssh public keys for all read/write developers into that user's .ssh/authorized_keys file.

"Why do the revision numbers associated with changesets sometimes change when I pull from another tree?"

When you create a new changeset, BitKeeper assigns it the next logical revision number. Since each repository operates independently from other repositories until you do a push or a pull, your local repository has no way of knowing what numbers are being assigned to changesets in other repositories. When you do a pull, BitKeeper sometimes finds two changesets with the same revision number and renumbers one of the changesets. All the information is the same, but the revision number assigned to that particular changeset is now different.

If you want to be able to refer to a particular changeset without using a version number, then tag it with this command:

bk tag -r

"I don't understand bk URLs. Something like http://bkbits.net/linux-2.5 is easy to understand, but what about the others?"

We'll use the ``bk clone'' command to show the different types of bk URLs.

If the bk daemon is running on the default HTTP port:

bk clone http://some.website.com my_repo

Or:

bk clone bk://some.website.com my_repo

If the bk daemon is running on port 5555:

bk clone http://some.website.com:5555 my_repo

Or:

bk clone bk://some.website.com:5555 my_repo

If the tree is accessible only through ssh and the login shell for the remote user is normal, e.g., /bin/bash:

bk clone username@hostname:/path/to/repository my_repo

If the tree is accessible only through ssh and the login shell for the remote user is the bk daemon:

bk clone bk://username@hostname/path/to/repository my_repo

If the tree is on the local filesystem:

bk clone /path/to/repository my_repo

"How do I move a repository?"

Repositories can be moved around on the local filesystem with a mere:

mv old_directory_name new_directory_name

If you are moving a repository to another host, just:

bk clone bk_url new_repo

And remove the old repository when you are done, if you desire.

"How do I export a plain text version of the repository?"

Run:

bk export -tplain ../plain_text

You can also specify a revision to export the tree as of:

bk export -r -tplain ../plain_text