Style Conventions:
• Commands are styled in teletype.
• Additional information about a command is (enclosed in parentheses).
• User-defined command arguments are styled in italic.

cvs co directory or module

bk clone bk://server:port/parent_repo parent_name
bk get or bk edit filename

cvs co and bk clone are not exactly commensurate. While cvs co checks out a working copy of a version of the repository -- TOT or a version based on a tag, date, or revision number -- bk clone makes a copy of the repository itself. Cloning a repository is like doing cp -r /path/to/cvs/repo/* ~/myrepo/ (not that you'd ever do that!). bk clone creates a private instance of the repository from and to which you can checkout, modify, merge, remove, and check in files.

To work with files in your repository clone, check them out:

• bk get filename
  (read-only checkout, similar to cvs export)
• bk edit filename
  (read-write checkout, just like cvs co)
• bk edit or bk get
  (checks out all files in the current directory)
• bk -r edit or bk -r get
  (checks out entire repository)
• bk clean
  (removes all unmodified files checked out with bk edit or bk get. Only operates on files in the current directory)

Details:

• What happens if I bk clone twice?
  BitKeeper reports "clone: clone name exists already."
• What happens if I bk edit the same file twice?
  Because bk edit means "checkout file(s) in read-write mode," BitKeeper reports "Writable filename already exists, skipping it."
• Some BitKeeper commands seem to ignore directory context. For example, running bk -r edit deep in the tree still (a) checks out the entire tree and (b) puts all the files in the correct location. This behavior is markedly different than in CVS, which is highly "directory contextual." What gives?

  BitKeeper performs filename expansion in the following order:

  1. bk command dir
     (when directory is specified and if dir/ exists, then implied file list is dir/SCCS/s.*)
  2. bk command <NULL>
     (when no directory or files are specified and if SCCS/ exists, then implied file list is SCCS/s.*)
  3. bk command [file1 file2 file3]
     (when one or more files is specified, then each file name is converted to SCCS/s.file1 SCCS/s.file2, etc.)

  Some commands accept an option -r flag. Here's the implied behavior:

  bk command	=>	bk command SCCS/s.*
  bk -r command	=>	cd `bk root`; bk sfiles | bk command -
  bk -r. command	=>	bk sfiles | bk command -
  bk command dir	=>	bk command dir

cd ~/mytree; cvs update

cd ~/myclone; bk pull bk://server:port/reponame

Your private repository is a "child" of the "parent" repository that you cloned.

Use bk pull to update your repository with changes committed to the parent since the time that you either created your clone or last pulled.

If merge conflicts occur during the pull, Bitkeeper will report them. Use bk resolve to resolve the conflicts.

cvs add [-kb]

bk new [-b]

bk new adds and checks in one or more files to your repository, placing it under revision control. Like cvs add, bk new is not recursive.

• bk new filename
  (add a single file)
• bk sfiles -x | bk new -
  (add multiple files [bk sfiles -x finds all files not under revision control])
• bk sfiles -x *.[ch] | bk new -
  (add multiple files in current directory based on a pattern)
• bk new -b
  (add a binary file, similar to cvs add -kb. Turns off keyword expansion)

To add many files in multiple directories, try this:

• cd ~/myrepo
• cp -r ~/to_add/* .
• bk sfiles -x . > /tmp/LIST
• vi /tmp/LIST
  (remove whatever shouldn't be added)
• bk new - < /tmp/LIST

Details:

• In CVS, to add new files and directories, you first cvs add the directory, then add each file, then cvs commit the directory. In BitKeeper, bk new filename adds and checks in the directory and file in a single step.

cvs commit -m "checkin comment"

bk ci -y"checkin comment"
bk commit -y"changeset comment"
bk push

No space is allowed between the -y and the quoted comment.

Note: You are strongly encouraged to use bk citool for all of your check-ins and commits. It's cleaner, easier, and fosters better comments!

• bk ci -l -y"checkin comment" filename
  (checks in changes and, afterward, does a bk edit filename)
• bk sfiles -U -c | bk ci -y"your checkin comments" -
  (check in lots of files from the command line)

Checkins and changesets:

• Use bk ci to check in a change.
• Use bk commit to define and check in a changeset.
• Use bk pending to get a list of checkins that are not grouped in a changeset.
• It bears repeating: bk commit is for defining a changeset, NOT for checking in individual changes.
• It's okay to use bk ci to check in changes and, later, use the graphical bk citool to define a changeset.
• Use bk push to propogate changeset to the parent repository.

Details:

What is the general "best-practice" guideline for a defining changeset? That is, when should checkins be grouped into a changeset?

The simple answer is, whenever you need to exchange data with another repository -- e.g., update your repository with bk pull or promote your changes to your repository's parent with bk push. Stated simply, you cannot pull or push without first grouping your checked-in changes into a changeset.

cvs remove filename or directory

bk rm or bk rmdir

The files and directories are moved to BitKeeper's version of the CVS Attic, ~/myrepo/BitKeeper/deleted.

n/a

bk mv

bk mv has no corollary in CVS. bk mv renames the checked-out file (if any) as well as the revision control file in the SCCS directory. Edited files are also renamed and then re-edited (i.e., checked out), preserving any changes that are not yet checked in. bk mv operations appear as a change when you commit the next changeset.

Moves propagate like content changes, that is, they are applied in the next pull or clone.

Use bk mvdir, not bk mv, to rename directories.

cvs diff

bk diffs or bk difftool

View differences between your checked-out file and the latest or earlier committed version in your repository.

Just like CVS, bk diffs can be used with a revision number, as in bk diffs -r1.2 filename.ext.

Details:

How can I get a diff of changes between my checked-out, locally modified files and what's in the parent repository?

The short answer is, you can't -- not without pulling an update from the parent. That said, if the parent has changesets that you do not have and if both the parent and child repository are on the same file system, you could get a meaningful diff with bk treediff.

cvs history

bk cmdlog [-a]

cvs import

bk import or "bk extras | bk new -"

cvs log

bk prs or bk changes

bk prs shows the revision summary for a single file or directory of files. It is not recursive.

bk changes shows the changeset history for the entire repository. Again, this command operates on the entire repository, even if you cd deep into your tree and specify a single file.

cvs release filename or directory

bk ci -y"comment" filename or directory
bk clean

bk edit checks out and locks a file for modification. To release the lock, check in your changes and run bk clean to remove the file. If don't want to keep your modifications, use bk unedit filename to unlock the file (use with caution!)

Details:

• A checkout "lock" blocks you from running bk edit on the same file more than once, thereby avoiding overwriting uncommitted changes with a new checkout.

cvs status

bk status [-v]

cvs status | grep "nothing known about"

bk extras or bk status -v