Next: , Previous: Advanced Uses, Up: Top


4 CVS Phrasebook

This chapter translates common CVS commands into monotone commands. It is an easy alternative to reading through the complete command reference.

Checking Out a Tree

     $ CVSROOT=:pserver:cvs.foo.com/wobbler
     $ cvs -d $CVSROOT checkout -r 1.2

     $ mtn pull www.foo.com com.foo.wobbler*
     $ mtn checkout --revision=fe37 wobbler


The CVS command contacts a network server, retrieves a revision, and stores it in your workspace. There are two cosmetic differences with the monotone command: remote databases are specified by hostnames and globs, and revisions are denoted by sha1 values (or selectors).

There is also one deep difference: pulling revisions into your database is a separate step from checking out a single revision; after you have pulled from a network server, your database will contain several revisions, possibly the entire history of a project. Checking out is a separate step, after communication, which only copies a particular revision out of your database and into a named directory.

Committing Changes

     $ cvs commit -m "log message"

     $ mtn commit --message="log message"
     $ mtn push www.foo.com com.foo.wobbler*


As with other networking commands, the communication step with monotone is explicit: committing changes only saves them to the local database. A separate command, push, sends the changes to a remote database.

Undoing Changes

     $ cvs update -C file

     $ mtn revert file


Unlike CVS, monotone includes a separate revert command for undoing local changes and restoring the workspace to the original contents of the base revision. Because this can be dangerous, revert insists on an explicit argument to name the files or directories to be reverted; use the current directory "." at the top of the workspace to revert everything. The revert command is also used to restore deleted files (with a convenient --missing option for naming these files).

In CVS, you would need to use update to restore missing or changed files, and you might get back a newer version of the file than you started with. In monotone, revert always takes you back to where you started, and the update command is only used to move the workspace to a different (usually newer) base revision.

Incorporating New Changes

     $ cvs update -d

     $ mtn pull www.foo.com com.foo.wobbler*
     $ mtn merge
     $ mtn update


This command, like other networking commands, involves a separate communication step with monotone. The extra command, merge, ensures that the branch your are working on has a unique head. You can omit the merge step if you only want update to examine descendants of your base revision, and ignore other heads on your branch.

Tagging Revisions

     $ cvs tag FOO_TAG .

     $ mtn tag h: FOO_TAG


With CVS, tags are placed on individual files, and the closest thing to identifying a consistent repository-wide revision is a set of files with the same tag. In monotone, all changes are part of a repository-wide revision, and some of those revisions may be tagged. Monotone has no partial tags that apply only to a subset of files.

Moving Workspace to Another Revision

     $ cvs update -r FOO_TAG -d

     $ mtn update -r 830ac1a5f033825ab364f911608ec294fe37f7bc
     $ mtn update -r t:FOO_TAG


With a revision parameter, the update command operates similarly in monotone and CVS. One difference is that a subsequent commit will be based off the chosen revision in monotone, while a commit in the CVS case is not possible without going back to the branch head again. This version of update can thus be very useful if, for example, you discover that the tree you are working against is somehow broken — you can update to an older non-broken version, and continue to work normally while waiting for the tree to be fixed.

Viewing Differences

     $ cvs diff

     $ mtn diff


     $ cvs diff -r 1.2 -r 1.4 myfile

     $ mtn diff -r 3e7db -r 278df myfile


Monotone's diff command is modeled on that of CVS, so the main features are the same: diff alone prints the differences between your workspace and its base revision, whereas diff accompanied by two revision numbers prints the difference between those two revisions. The major difference between CVS and monotone here is that monotone's revision numbers are revision IDs, rather than file IDs. If one leaves off the file argument, then diff can print the difference between two entire trees.

Showing Workspace Status

     $ cvs status

     $ mtn status


This command operates similarly in monotone and CVS. The only major difference is that monotone's status command always gives a status of the whole tree, and outputs a more compact summary than CVS.

Adding Directories and Files to Workspace

     $ cvs add dir
     $ cvs add dir/subdir
     $ cvs add dir/subdir/file.txt

     $ mtn add dir/subdir/file.txt


Monotone does not explicitly store directories, so adding a file only involves adding the file's complete path, including any directories. Directories are created as needed, and empty directories are ignored.

Removing Directories and Files from Workspace

     $ rm file.txt
     $ cvs remove file.txt

     $ mtn drop file.txt


Monotone does not require that you erase a file from the workspace before you drop it. Dropping a file both removes its entry in the manifest of the current revision and removes it from the filesystem.

Viewing History

     $ cvs log [file]

     $ mtn log [file]


Unlike CVS log, monotone log can also be used without a workspace; but in this case you must pass a --from revision argument to tell monotone where to start displaying the log from.

Importing a New Project

     $ cvs import wobbler vendor start

     $ mtn --db=/path/to/database.mtn --branch=com.foo.wobbler setup .
     $ mtn add .
     $ mtn commit


The setup command turns an ordinary directory into a monotone workspace. After that, you can add your files and commit them as usual.

Initializing a Repository

     $ cvs init -d /path/to/repository

     $ mtn db init --db=/path/to/database.mtn


Monotone's “repository” is a single-file database, which is created and initialized by this command. This file is only ever used by you, and does not need to be in any special location, or readable by other users.