Documentation

This section contains links to different kinds of documentation for BitKeeper. It's a constant work in progress as we evolve the documentation.

The reference material is included with BitKeeper; it may be read, searched, and/or browsed by using bk helptool [topic]. The material included with BitKeeper is more likely to be up to date than this web site.

The documentation is divided into reference material, a printable quick reference guide, some FAQs, some Howtos, and a user guide. The user guide is in a different location, clicking on the user guide link on the left will take you there.

Quick reference guide

A small summary of the commonly used BitKeeper commands, suitable for printing, is available as Postscript or PDF

Reference manual

All BitKeeper commands are documented with included online documentation. The reference pages are available at the command line

bk help topic

bk helptool

Command Comparisons

The following command comparisons documentation is a translation system of sorts between other product's commands and BitKeeper commands.

Thus far we have documentation for CVS only.

CVS to BK This section is a hyper link to here.

Bug Database

BitMover's BugManager can be found at

http://db.bitkeeper.com

There are four defined states at this time:

• Open - any bug that is open and not assigned; this is a bug's initial state
• Assigned - any open bug that has been assigned an owner
• Fixed - any bug that has been fixed and closed
• Closed - any bug that will not be fixed and has been closed

Submitting Bugs

If you have found a bug in BitKeeper, you can submit it via the command line or on the web.

To submit BitKeper bugs via the command line, do

bk sendbug

To submit a bug using the web, go to the bug database page:

http://db.bitkeeper.com

To submit,

• click on the "Submit bug" tab
• fill out the form and click "Submit"

Querying Bugs

To query bugs go to

http://db.bitkeeper.com

Specific Queries
To list bugs that match specific criteria:

• click on the ¨Simple Query¨ or ¨Advanced Query¨ tab.
• fill in the query form with as much specific information as you can
• click "Send Query"

Sorting Lists
When you are looking at a list of bugs, you may sort that list by clicking on the top heading of the column for the field on which you would like the data sorted.

Viewing Bugs

From A List
If you have a list of bugs and would like to view a particular one, click on the hyperlinked BugID number.

If you have an ID number
If you know the number of the bug you wish to view,

• go to http://db.bitkeeper.com
• Click on the Simple Query tab
• Cut and paste the ID number into the ID field
• Click Run Query

Updating Bugs

To update or change a bug's state, first view the bug using one of the methods in the Viewing Bugs section.

Any field that allows updates can be modified. Once fields are modified, click on Record changes.

You will be prompted to verify your updates. Once verified, the bug will be updated with your changes.

User guide This section is a hyper link to here.

FAQS

General usage

• What are the SCCS directories in my repository all about?
  That's where all the metadata for the revision control is stored. Do not remove any piece of the SCCS directories. People have been known to remove part or all of the contents of the SCCS directories which has serious consequences for BitKeeper. If you do remove some or all of the SCCS files these repositories can probably be restored. Please contact support@bitmover.com for help.

• Does BitKeeper have support for versioning directories?
  Bitkeeper does not version directories directly, it version controls files. Another way to say it is that BitKeeper version controls file "objects". The objects have several attributes including contents, permissions, and pathnames. When instantiating any version of the repository, all directories needed in order to place an object (file) where it wants to be are created automatically. The only limitation is that BitKeeper currently has no way to version control an empty directory.

• I'd like to be able to create, move and delete files and have that versioned along with the rest of the files. Does that capability exist?
  BitKeeper tracks all attributes associated with a file; path names are one of those attributes. All attributes are tracked in every delta, not just a tagged changeset. This means when you rollback or undo a change set, renamed files will be automatically move back to their previous locations.
  See also bk helptool mv.

• How can I turn off keyword expansion, that is: [ Documentation expansion ] ?
  

  bk admin -FSCCS foo.c	# OR
  bk -r admin -FSCCS	# Does it on every file

  
  If you want to understand more about this, bk helptool keywords will explain which keywords get expanded when, and bk helptool admin tells you how to shut off SCCS keyword expansion.

• Is there any way (other than putting something in the triggers) to tell a particular repository that it should always try to do the equivalent of 'newgrp bk' every time? (I have the repository owned by group bk)
  If you like to set the sgid bit on directories, you need to specify the symbolic mode. This is a safety enhancement of chmod.

  find . -type d | xargs chmod u=rwx,g=rwx+s,o=rx

  should do the trick.

• I am in the EST timezone with daylight savings time and dates are showing up wrong in the revtool. The changesets reflect the time accurately but the tool is displaying the dates as if they were UTC. What's up with the timezones?
  Yes, the times in revtool are in UTC. The reason for this is that when projects have members in different timezones, the dates at the bottom start becoming out of sequence when members to the east do commits before you do. For example, if we display dates in local time and someone in a timezone where it is the next day does a commit before you, then you will see the something like:

  1/16 1/15 1/17 2001 2001 2001

  One of our customers found the out-of-sequence dates irritating and asked that we display the dates in UTC.

Making changes

• How do I retrieve and put packages back into BitKeeper?
  bk clone retrieves a copy of a package, bk citool checks the files into the package and creates a changeset, and bk push puts your changes back into the parent package repository.

• How do I export a clear-text version of the repository as of some version?

  bk export -tplain [-r<rev>] /tmp/snapshot

• After doing a ``bk citool'' the result is only a pending change. I then have to do a ``bk commit'' Why require two steps?
  You must add a comment to the ChangeSet file entry in citool, which at some point in the future, you will probably find very useful -- you should describe the reason for the changeset. Without a comment for ChangeSet, citool will not do a "commit" for you, the file you checkin will be left in pending state.

• Let's say I have a repository in /home/bkdev. If I simply move that directory to /home/project/bkdev, will that muck up anything that bk uses to keep track of project info, e.g. for use with the open logging system? If it does muck with things, what is the 'safe' way to move or rename a bk repository?
  Moving a repository is a safe operation. Just make sure that any child repositories' parent pointers are reset:

  bk parent <new-parent>

Viewing changes

• How can I find out what files have been modified and what the changes are?
  You can either use bk citool or a combination of bk sfiles and bk diffs.

• How do I view differences between file revisions?
  The main file browser is revtool. If you want to see changes between two checked in versions, run:

  bk revtool filename

  and a graphical viewer will appear. You can double click (left mouse) on any version and an annotated version will appear in the bottom window. To see differences between any two versions, left click on the earlier version and right click on the later.

  Another frequent request is to see the differences between the checked in version and a working version that has been modified. To do this, run:

  bk difftool filename

  and a side-by-side viewer will appear. You can even use difftool on files that are not checked in at all by specifying those file names.

• How can I view overall history/status? That is, how can I piece together what has happened in a repository -- when it was cloned, what happened since the clone, etc.

  bk revtool

  will browse the entire package. If you select one or more revisions, you can click "View changesets" to get detailed information about the files changed in that changeset. See bk help revtool for more information.

• How do I view revisions of a package and individual file revisions in that labeled package?
  Revisions of a file are best viewed with bk revtool. This is a GUI that shows context differences. In the top window is a graph of the file's history. Left click and right click on two versions of the file to see the context diffs. To see side-by-side full file diffs, click on the "diff tool" button and a new window will display that. If no filename argument is given to revtool, it displays the entire package's history.
  Revisions of a package can also be viewed using bk csettool. You'll need a revision number as an argument to csettool; bk changes or bk revtool will give you a revision number. Csettool is used to view the detailed information about the specified changeset[s]. The tool displays the list of changes in each changeset, the ChangeSet history, and (optionally) the differences found in each file contained in each changeset.
  To see the changes for a particular file, click on the file name the top left window and you will see:
  * the number of diffs in the light blue, middle status window
  * the old version of the file in the lower left window
  * the new version of the file in the lower right window
  * the ChangeSet's comments followed by the delta's comments in the upper right window
  Use the space bar to move between diffs and files. Each time you hit the space bar, the next diff is brought into view. If you are on the last diff, the tool moves to the next file. The Next (>>) buttons and Previous (<<) buttons in the upper left corner will also allow you to browse the files and diffs.

• Is there any way to diff two committed and tagged versions of the repository
  Yes, there is a way. Use:
  

  bk export -tpatch -rtag1,tag2 | more

File operations

• What is the best method for adding new files to a BitKeeper package?
  If you are adding a small number of files, the easiest thing to do is

  bk new file

  If you are creating a new package, and you have an existing set of files, run:

  bk setup new_package bk import -tplain files new_package

  which will import all files into the new package. This method can only be used once, when the package is created.

  If you have a large number of files to add to an existing package, the easiest way is to copy the files into the package, generate a list of the files, edit the list to make sure there are no unwanted files (such as object files from an earlier build), and then create 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

  
  
• What is the best method for deleting files from a BitKeeper package?
  The command bk rm file(s) will remove a file(s) from the BitKeeper package. Because BitKeeper remembers everything, this actually renames the file to .del-file. All future BitKeeper operations ignore the file unless you name it explicitly, but it still exists in the package and will still be propagated by resync/pull/push.
  If there is a file that you really want to not be in the tree, you have to do this:

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

  The gone command records the fact that the file is really gone and tells BitKeeper to not complain when it can't find it.

  Can I simply do a 'bk ignore deleted/' so that subsequent clones won't get the deleted directory?
  The short answer is no. The most important points to note are:
  * bk gone takes a root key as argument, not a file name or directory name.
  * bk gone does not actually remove a file, it just informs BitKeeper that the file (which is associated with the specified root key) is physically deleted. The lack of a bk command to physically remove a file is deliberate, we do not want to encourage this action, since it results in a lack of reproducibility.

• What does BitKeeper do with file permissions and how can I change them?
  BitKeeper preserves all file permissions as they were originally set in the first established tree, unless you specifically change them with the bk chmod command.

Multiple file operations

• How do I check in lots of files from the command line?

  bk sfiles -U -c | bk ci -yyour_comments -

• How do I modify every file in the tree in one shot for testing?

  bk sfiles -g -U| while read x; do echo $x; echo "foobar" >> $x; done

• How would I ``bk get'' all *.pm files in all subdirectories?
  Try this:

  bk -R sfiles -g | grep '\.pm$' | bk get -

• How do I find all bad writable files?

  bk -r check -w

  Typical usage:

  bk -r check -w | bk -R edit -g - bk -r check -w | bk -R xargs whatever

Merges

• Is there a way to make the diffs during merge (i.e., dr[m], dl[m]) output a unified context diff instead of the old style diff?
  Yes, you may call an external tool to merge changes. When in the resolver, you can say:

  file.c>> !<command>

  then <command> will be run with the following environment variables set:

  BK_LOCAL - pathname of a temp file containing the local version
  BK_GCA - file containing the common ancestor
  BK_REMOTE - pathname of a temp file containing the remote version
  BK_MERGE - pathname where the merged content should be placed
  So you could make a little shell script:

  #!/bin/sh if [ "X$PAGER" = X ]; then PAGER=more; fi exec bk diff -u $BK_REMOTE $BK_LOCAL | $PAGER

  call that ``udiff'' and then do:

  file.c>> !udiff

  and you're all set.

• I would like to be able to do an manual merge ('e') without the preceding automerge. Is this possible?
  Yes. The same technique as above would do it. That is, the command run would be the editor you want run.

Import

• I am tracking some vendor sources which I have put into a BK repository using bk import. I tagged it after the import so I could get it back out, etc. if I need to. I have got a new release and need to put it into the repository and will tag it with the new release, but how do I do this? It seems that bk import only works once (the first time) on a new bk repository.
  Assuming you know how to generate patches, and have a patch, you can:

  bk clone -rvendor_rel_1 tree import_tree bk import -tpatch import_tree

Undoing work

• How do I undo or back out changes?
  There are several ways to get back to an earlier version:
  a) When debugging a problem, you may want to base a bug fix on an earlier release. First you'll want to find the correct version of the package (you can say bk revtool without a file name argument to browse the package, or say bk changes to see the changes from the command line).
  Once you have the version, say:

  bk clone -r<version> master bugfix

  Then make the changes in bugfix. Whether you merge them back into master or not is a policy decision; most companies create a bug fix tree (or series of them) and engineers clone from "Project-1.0" and push back into that.

  b) If a change came into your tree and more changes are also there on top of the earlier change, you cannot use undo to get rid of the change. You can "exclude" that change by running

  bk cset -x<version>

  which will create a change that removes the effects of the change specified by <vers> (and yes, you can later bk cset -x the change that excluded the first change and the first change will come back). This choice is by far the safest thing to do - no information is lost and you can change your mind later.

  c) If you pulled a change into your tree, and you are not ready that change yet, then you may be able to undo it. It has to be the most recent change or series of changes. To undo it, find the versions that you want to get rid of, make sure they are at the top of the graph, and run:

  bk undo -r<vers>,<vers>,<vers>

• How do I manually do an anti-delta on a single file?
  Very easily. All the bk cset -x does is recursively do a bk get -e -x on each of the deltas in each of the files which were part of the specified changeset.
  If all you wanted to do was undo the effect of the bk cset -x (or -i) on a single file, and that file was last modified by the cset, then you can just X out the -x like so:

  bk edit -x+ file

  if you want to have some weird fun, you can keep repeating that. All you are doing is manipulating the set deltas which make up the file contents.

• How do I remove changes from the last pull? Basically, I am looking for a 'bk undolast' kind of command'.

  bk unpull

Tags

• How do I label revisions of a package? And how do I then retrieve a certain package revision by label in case one labeled version works and the other does not?
  Labels are called "tags" in BitKeeper. To add a tag to the package, make sure you've checked in everything and created a changeset. You can use bk status to see what needs to be checked in and/or committed to a changeset. Tag the tree by typing:

  bk tag TagName

  The most recent changeset is now labeled, or tagged, with "TagName". If you didn't want to tag the most recent changeset, you can say

  bk tag -r<vers> TagName

  to add the name to any revision. You can now use this tag as an argument to clone, for example:

  bk clone -rbeta master beta

  which creates a repository called "beta" that has everything up to and including the "beta" changeset.

  A frequent problem is that you tag a changeset with "Done" and then discover you weren't really done. You can update the tag to the later changeset by running the bk tag Done command again.

• How do I view comments that have been written for specific files or a labeled package?
  For individual files, use bk prs filename. For a tagged changeset, use bk changes.

• Is there an easy way to find out what tags are in a tree and when they were created with what changesets, etc.?
  

  bk changes -t

  or

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

Failure recovery

• What does BitKeeper do in the event of some failure? Will we have half-done work in BitKeeper?
  It depends on the failure. All of the common failures have been handled, but new users find new and wonderful ways to make BitKeeper fail. The most important thing to do if something goes wrong is to create a "tarball" of the repository before you try to figure out what went wrong. Suppose you had a cloned copy in your home directory named "my_work". If something goes wrong do this:

  cd tar czf BUG.tgz my_work

  That way, if you can't fix it, you have something that you can ask BitMover to unscramble. We've successfully unscrambled problems that were quite complicated and each time we do that, we put code into the system to make sure the problem doesn't come back. So please tell us about any problems you find.

  If the machine has a failure, do a bk -r check -a which will check the repository to make sure it's in a consistent state. If check reports errors, contact BitMover.

• How do I complete a failed pull? I did a pull and had files checked out and the pull didn't complete. I noticed that a PENDING directory was created. Is there a way for me to complete the resolve without making another network connection?
  The contents in the PENDING directory need to be rerun. The pending directory will have one or more patch files that have names made up of the data plus a sequence number. Find the latest PENDING file and then run takepatch and resolve on it. For example:

  bk takepatch -vvf PENDING/2000-09-19.01 bk resolve -a

• What's the best way to recover from the following type of error?

  docs/img/services/acct/top_back_bar.gif: 2 deltas docs/img/services/acp/titles/scheduled.gif: 2 deltas --------------------------------------------------------------------------- takepatch: saved entire patch in PENDING/2001-03-26.02 --------------------------------------------------------------------------- =================================== ERROR ==================================== takepatch: SCCS/s.ChangeSet is locked w/o writable gfile? takepatch: patch left in PENDING/2001-03-26.02 ============================================================================== 496746 bytes uncompressed to 1127864, 2.27X expansion

  If you are doing a push, go to the parent tree; if you are doing a pull, go to the client tree, and from that directory type:

  cd RESYNC; bk unlock -p ChangeSet

• Given the following situation, how do I continue the resolve?
  box ``A'' holds a clone of a repository
  box ``B'' is where I'm working
  I had a resolve going on box ``A'', in an rxvt on box going until box ``B'' crashed. Now when I try to run resolve I get:

  $ bk resolve Using boxB:0.0 as graphical display Verifying consistency of the RESYNC tree... ======================================================================= check: arch/ppc/kernel/pmac_pci.c is locked but not checked out, which usually means that a file was locked (via a "bk edit") and then removed without being unlocked. ======================================================================= {bk} {-r} {check} {-cR} failed. Resolve not even started. resolve: RESYNC directory left intact. =======================================================================

  Try this:

  cd to the RESYNC tree bk unlock -p arch/ppc/kernel/pmac_pci.c

  Alternatively, if you have not invested a lot of work in the resolve process, you can always do a bk abort and re-do the bk pull.

• I'm trying to do a fairly large clone remotely and because the connection appears quiet, the line is dropped and the clone then fails. What can I do to work around this?
  To keep the line alive, and thus the clone, open a second window and ping the repository every ten seconds or so.

• I accidentally deleted a SCCS/s.* file in my cloned repository. To continue working, I scp'ed it from the parent repository. Is this the correct fix? Is there a better way?
  That will always work as long as the parent is not ahead or behind where you were when you lost the file. If the parent is behind, you are out of luck. If the parent is ahead, then you can actually strip it backwards to make it match your environment.
  Remember that you can always run bk -r check -a to make sure BitKeeper is happy with the state of the repository.

• I have gotten myself into trouble by doing some part of the checkout, edit, commit operation as root. Now when I try to push, I get:

  bk push ----------------------- Sending the following csets ----------------------- 1.336 --------------------------------------------------------------------------- --------------------------------------------------------------------------- takepatch: saved entire patch in PENDING/2001-03-06.07 --------------------------------------------------------------------------- =================================== ERROR ==================================== takepatch: SCCS/s.ChangeSet is locked w/o writable gfile? takepatch: patch left in PENDING/2001-03-06.07 ==============================================================================

  What can I do about this?
  Try:

  bk -R unlock -p ChangeSet

Event triggers

• Can I get automatic email to individuals within a defined group whenever changes are checked in?
  Yes, this is done by using triggers, commands which run before or after a repository level command. In this case, you would want to set up a post-commit trigger. That is, in the BitKeeper/triggers/post-commit directory you would setup a shell script to send mail to those people you want to notify. Pre-triggers can be used to control events within a repository. For more information, see bk helptool triggers. But note that triggers are available only with the BK/Pro product.

• How difficult is it to pass user-specified environment variables to the triggers? For example, I want to be able to pass the environment variable MAILTO containing the email address of the user.
  It's easy. Use:

  bk pull -E/bk push -E

Configuration

• How do I automatically checkout files in Read-Write mode after I do a checkin? Add a checkout mode line to the BitKeeper/etc/config file, see bk help config-etc for more information.

  checkout: get checkout: edit [akushner]checkout: edit

  Make sure there is a space after the colon, i.e., ``checkout: edit'' and make sure the config file has been checked in.

  Another tip is that if you just alias vi='bk vi' then bk will check out the file in edit mode and then run vi on it. The BitMover development staff runs with this alias all of the time.

• bk citool always displays a long list of irrelevant files. Is there some way to hide these files?
  If there are files in your repository you won't ever want to check in, such as core, *.exe, etc., you should put them in the ``ignore'' list. You can either use the ``Ignore'' button in citool, or create your own ignore file. See bk helptool ignore for more information.

• Is there any way to specify the exact X11 font one wants?
  Yes. Here's an example from one of our users:

  # this font is *much* easier to read with the default X setup set gc(fixedFont) "-*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-iso8859-1" set gc(fixedBoldFont) "-*-lucidatypewriter-bold-r-*-*-12-*-*-*-*-*-iso8859-1"

Error messages

• What does this message mean?

  Running resolve to apply new work... Check: found in ChangeSet but not found in repository:

  This means you may have deleted an sfile after having committed it to a changeset.

• Sometimes bk clean acts confused and responds with: <filename> writable but not edited What's going on?
  Just do a bk edit -g <your file> (this changes your file to edit status without overwriting your existing gfile) and then run bk citool again.

• What would cause Entire Repository locked by RESYNC error:

  Entire repository is locked by: RESYNC directory. Cannot do pull into locked repository.

  The RESYNC directory exists because a previous bk pull failed due to a conflict that hasn't yet been resolved. At the end of that pull, there should have been a message stating something like "pull failed due to unresolved conflict, run resolve".

  At this point, you have two options: if you want to resolve the previous conflict and continue with a new pull, you should run 'bk resolve' and then type 'e', fix the conflict, get out of the editor, and then type 'C' to commit the fix.
  Or, if you don't want to do the conflict resolution, you can do a 'bk abort' and that will get rid of the RESYNC directory, but you will eventually have to resolve the conflict in order to pull.

• What does this error message mean?

  getRegBody: Can't open bk-names.1 for writing get of SCCS/s.bk-names.1 failed, skipping it. getRegBody: Can't open bk-unpark.1 for writing get of SCCS/s.bk-unpark.1 failed, skipping it. getRegBody: Can't open bk-level.1 for writing

  
  It most likely means that your system has run out of inodes.

• Is there some way to get better information when debugging the logging process?

  bk _log -d

  will tell you what is going on.

• I am trying to push up to my repository and I get the following errors:

  Running resolved to apply new work .... ============================ sane: bad host name: "red-hat". BitKeeper wants fully qualified hostname. =========================== {bk}{-r}{check}{-cR} failed. Resolve not even started.

  Actually, the name of my computer IS red-hat. What can I do to get around this?
  BitKeeper requires fully-qualified DNS names in order to ensure we do not create BK keys that are not unique. A key looks like this:

  user@host.domain|src/foo.c|YYYYMMDDHHSS|12345

  and we use the user@host.domain part to know that we are not creating the same key twice to name two different things. So, instead of red-hat, your machine should be named red-hat.com. To verify the rename worked, use the bk gethost command. And in general, you can make sure BitKeeper is happy about this sort of thing by running the bk sane command.

Windows/NT

• We have some project files that must not have EOL conversions (DOS->UNIX) done on them. How can we ensure that these files have native EOLs preserved?
  

  bk admin -fEOLN_NATIVE filename

  should do the trick. This says to use the operating system's native end-of-line termination. On Windows, the gfile is generated with CRLF as EOL. On Unix, the gfile is generated with LF as EOL.

  Note: if you check the file back out on Unix, the file will have LF only.

BK/Web

• BK/Web is "missing" the most recent changeset in one repository here. That is, revtool shows 1.13 (a merge cset) as the last cset, and BK/Web in the same place showing a pre-merge version as the most recent one. 1.13 doesn't show in BK/Web anywhere.
  We do not show merge changesets in BK/Web if there is no content. We did this because the no content merges just take up space without showing you anything.

Linux

"How do I install BitKeeper?"

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.

"How do I get a copy of the Linux kernel source repository?"

BitMover maintains BitKeeper repositories of the Linux kernel on bkbits.net. Web access is available for free and includes a way to extract any changeset as a patch. BitKeeper access requires a commercial license and an ssh1 public key. Contact us to get your key installed.

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

HOWTO's

License Keys: Closed Source

For most closed source projects, the license keys are installed in a repository. They may also be stored in a system level config file. Please see bk help config-etc for more information about the system level config file.

Installation (New Repositories)

• save the email message with license keys as a text (.txt) file
• download bk and install if you haven't done so already

• bk setuptool

• when prompted for key and signatures, click "From file..." and choose the saved message.

Installation (Existing Repositories)

cd repo/BitKeeper/etc bk edit config # edit the config file: # remove license line if there is one (ditto for licsign lines) # add the license and licsign lines you were sent bk delta config bk commit

License Keys: Open Source

What needs to be done

In order to start using BitKeeper license keys in your open source projects, you need to be able to use the keys without putting them in the repository. See the explanation below for why the keys need to remain outside of repositories.

To use the license keys you can do one of two things, you can use a system level config file or set an environment variable.

System level config file
To install keys into a system level config file do the following:

vi /etc/BitKeeper/etc/config # cut and paste the license/licsign lines you were sent into the file

You will need to repeat this for all machines on which BitKeeper will be used.

Environment Variable
Instead of having license keys in a system level config, you may also choose to use the BK_CONFIG environment variable. The syntax for setting that variable and running a (sh) command is as follows:

BK_CONFIG='option:value;option2:value2;' bk cmd

or

# bash export BK_CONFIG='option:value;option2:value2;' # csh setenv BK_CONFIG='option:value;option2:value2;'

Explanation of why that needs to be done

License keys thus far have only been needed by commercial developers. Users of the free product have not needed license keys for BitKeeper to function. Beginning July 1 2005, license keys will be required for all versions of BitKeeper to function.

In commercial installation, license keys normally get installed in the BitKeeper/etc/config file of the repository. BitKeeper's license keys do not put hard restrictions on the number of users on a key. In commercial installations, this is okay because there are protections made in house that restrict usage to in-house developers and repositories are rarely made public. In the free-use world, repositories are almost always public so there must be restrictions in how license keys are installed for use on open repositories.

For customers moving status from free to commercial there are special considerations that need to be made in order to continue to publish source and also protect license keys. There are two methods that can be employed, using a system level config file or using a BK_CONFIG environment variable.

Hosted Projects
You can still continue to use bkbits.net and openlogging for your projects.

No license keys are needed for the open source bitkeeper client. Consumers of your open source projects can use the client to do "clones" and "pulls" from bkbits.net.

Multiple code lines

Suppose that you have "dev" and "bugs" as your two lines of development. Further suppose that fixes added to "bugs" line should go into "dev" but not the other way around (this matches a large percentage of all software development efforts).

Create two copies of the same repository and name them "bugs" and "dev". We put them in /home/bk/bugs and /home/bk/dev.

When you need to do a bugfix, clone the bugs tree; when you want to do development, clone the dev tree.

A project lead will periodically pull changes from the main bugs tree into the dev tree to keep it up to date.

PROS:

• simple to explain
• all work tends to converge on the trunk
• works for most people
• follows the "work forward model"

CONS:

• you have to be careful not to push the dev tree into bugs, use bk level to prevent this from happening.
• can only easily work "forward", i.e., work may flow from bugs to dev but not backwards. It's possible to move stuff backwards as patches but it isn't as easy as the other way.

CVS to BitKeeper This section is for people familiar with CVS and is sort of a translation of commonly used CVS commands and actions into BitKeeper commands.

In CVS, the central/master repository is set as follows:

setenv CVSROOT username@hostname:/path/name

In BitKeeper, you would use:

bk parent username@hostname:/path/name

See bk help parent for all uses of the command.

In CVS, run all remote traffic is run over ssh with the following:

setenv CVS_RSH /usr/bin/ssh

BitKeeper defaults to using ssh, but it's possible to do the following:

setenv BK_RSH /usr/bin/rsh	# csh
export BK_RSH=/usr/bin/rsh	# sh

In CVS, checking out a first-time clone for making changes is done as follows:

cvs co [files or dirs]

In BitKeeper, the equivalent is:

bk clone username@hostname:/path/name [destination]

Note that BitKeeper currently allows you to get only the whole tree.

In CVS, to add changes there is no file locking, you simply edit your file copies and then commit. The ``locking'' and conflict checking is done on write back. To lock a file for editing in BitKeeper:

setenv EDITOR /usr/bin/vi
alias vi 'bk editor'
vi foo.c	# checks out and locks foo.c and then execs $EDITOR; works with multiple file args

Alternatively:

bk edit	# locks everything
vi foo.c bar.c whatever.c

Changes are committed to a central repository in CVS in one of the following ways:

cvs commit [file...]
cvs commit
cd some/dir; cvs commit	# will only commit all changes from some/dir

The equivalent in BitKeeper is: