CVS Phrasebook

Here we translate common CVS commands into monotone commands.

Checking Out a Tree

CVS:

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

Monotone:

$ mtn pull "mtn://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 @sc{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 @emph{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:

$ cvs commit -m "log message"

Monotone:

$ mtn commit --message="log message"
$ mtn push "mtn://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:

$ cvs update -C file

Monotone:

$ 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 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:

$ cvs update -d

Monotone:

$ mtn pull "mtn://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.

Monotone handles conflicts differently than CVS; see the [Monotone manual][http://www.monotone.ca/docs/Merge-Conflicts.html#Merge-Conflicts] for more on this.

Tagging Revisions

CVS:

$ cvs tag FOO_TAG .

Monotone:

$ 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:

$ cvs update -r FOO_TAG -d

Monotone:

$ 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:

$ cvs diff

Monotone:

$ mtn diff

CVS:

$ cvs diff -r 1.2 -r 1.4 myfile

Monotone:

$ 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:

$ cvs status

Monotone:

$ 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:

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

Monotone:

$ mtn add dir/subdir/file.txt

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

CVS:

$ rm file.txt
$ cvs remove file.txt

Monotone:

$ 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:

$ cvs log [file]

Monotone:

$ 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:

$ cvs import wobbler vendor start

Monotone:

$ mtn --db=/path/to/database.mtn --branch=com.foo.wobbler setup .
$ mtn add -R .
$ 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:

$ cvs init -d /path/to/repository

Monotone:

$ 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.