--- Quick Guide to Starting Development with Monotone --- **Introduction** The first suggestion is read the documentation- there is a great tutorial on the Monotone website, located here: http://www.venge.net/monotone/ After looking through the tutorial, you should have a basic idea how to use Monotone's basic features. The Wiki is also a good resource for beginners, although it is not very expansive. **Suggestions for beginning use** The first important step is to generate your keypair, the command for which is stated in the Basic Command Set section below this one. I would recommend setting the permissions on this file to 600 once you have it generated; by default the key is placed in ~/.monotone/keys. Another great file to create is ~/.monotone/monotonerc. This is an interesting file, as it holds hooks that monotone will call during its execution. Here is a typical (OK, it's mine) monotonerc file: -- monotonerc - lua hooks for certain events -- allows automatic entry of password on all actions dealing with signing function get_passphrase(keypair_id) if (keypair_id == "") then return "" end end -- returning true means we won't be prompted multiple times for password function persist_phrase_ok() return true end external_diff_default_args = "-up" -- vim: set filetype=lua : This file should also have permissions of 600 as it contains your password. The second function I have listed is not truely necessary since we have the get_passphrase hook, but I put it there in case you didn't want to use the first. Other functions you may want to include in monotonerc, all of which are well documented on the Monotone website in the documentation: -- allows you to set the editor used for commit messages function edit_comment(basetext, user_log_message) -- set the program used for 3-way merges when Monotone needs help merger = Two other files are important if you decide to serve projects from your local database. These are also placed in ~/.monotone/ and are named read-permissions and write-permissions. Read the tutorial in the Monotone documentation which does a great job of explaining what should be placed in these files. Monotone best practices is a great read, especially for those used to the CVS way of version control: http://www.venge.net/monotone/wiki/BestPractices. Those used to CVS will want to look at the CVS Comparison section below. Monotone-viz is an excellent tool to get a view of the tree of a monotone database. Because it is not straight history like CVS, looking at logs can be confusing at times. Looking at the revisions in tree form can be very helpful to see who did what and where it occurred in the tree. **Basic Command Set** For most of these commands, if you are already in a project working directory, the --db argument can be omitted. Making a new empty database: mtn db init --db=.mtn Generating a keypair: mtn genkey Starting a new project: mtn --db=.mtn --branch= setup [] Checkout working copy of branch: mtn checkout --db=.mtn --branch= [] Add files to project (assuming it is setup and you are in directory): mtn add Get status of current working directory: mtn status Get diff of current working directory against parent: mtn diff Commit current work to the database: mtn commit [--branch=] [--message=""] Update working directory against database: (WARNING: unlike CVS, do a commit first if you have made local changes) mtn update For the below operations, the default hostname is the one last synced with. A sync is both a push and pull- it copies over your database changes and pulls remote database changes. The other two operations should explain themselves. In any case, to do a remote sync, one host or the other must run the 'serve' command. Sync modifications with remote host: mtn sync --db=.mtn "" Pull modifications from remote host: mtn pull --db=.mtn "" Push modifications to remote host: mtn push --db=.mtn "" Serve database for connections: mtn serve --db=.mtn Merge branch when multiple heads exist: (WARNING: unlike CVS, a merge does not automatically update your workspace) mtn merge [--branch=] Propagate changes from one branch to another mtn propagate --db=.mtn **Other helpful commands** List all public/private keys in your database: mtn list keys Export your public key: mtn --db=.mtn pubkey Import a public key: mtn --db=.mtn read < **CVS Comparison** The first thing that is stressed when moving from CVS to Monotone is this- branching and merging is NOT a bad thing. CVS has atomic commits, Monotone does not. This means two people can both make a commit to the same parent revision in Monotone, unlike in CVS. Monotone is very good at merging these changes, and if it thinks it cannot do so, it will prompt you to manually merge. Branching is the best way to enhance development using monotone. It is very easy to create your own working branch (e.g. for the "org.archlinux.pacman" project, I can create a local branch named "org.archlinux.pacman.private".) You can prevent this branch from being public by never pushing it to a server. (I believe this can be done by setting it in read-permissions? But I'm not sure.) As another option, you can name the branch after your name or something that will not conflict with anyone else. Branches are also very useful for implementing a feature that will affect many parts of the project. By creating a branch and working on your implementation in this branch, you can later propagate changes from the mainline into your branch before finally merging the two branches together once the feature is fully implemented. Do not be scared to create a branch! In essence, creating a branch simply delays merges from happening without your explicit permission. Below, I try to match CVS commands with Monotone ones. Obviously, not everything is a one-to-one translation, but the general ideas below should help you out. Checkout a branch: CVSROOT=:pserver: <-> mtn pull "" cvs checkout -r mtn checkout [--revision=] Commit changes to a branch: cvs commit -m "" <-> mtn commit --message="" mtn push "" Check status of working directory: cvs status <-> mtn status Get diff from current branch: cvs diff <-> mtn diff Get diff between two revisions: cvs diff -r -r <-> mtn diff -r -r Add files to workspace: cvs add <-> mtn add Removing files from workspace: rm <-> mtn drop cvs remove Undo changes to a file: cvs update -C <-> mtn revert View file log: cvs log <-> mtn log Incorporate branch changes (with Monotone, usually better to commit FIRST): cvs update -d <-> mtn pull "" mtn merge mtn update Tag a revision (for mtn, tags head of a branch): cvs tag . <-> mtn tag h: **Reference** Commands: automation automate database db debug fdiff fload fmerge get_roster identify rcs_import informative annotate cat complete diff help list log ls show_conflicts status key and cert cert chkeypass dropkey genkey trusted network pull push serve sync packet i/o privkey pubkey read rcs cvs_import review approve comment disapprove tag testresult tree checkout co explicit_merge heads import merge merge_into_dir migrate_workspace propagate refresh_inodeprints setup vars set unset workspace add attr ci commit drop mkdir mv pivot_root pluck rename revert rm update Common Options: --db= set name of database --branch= set branch name --help get help **Sources for this guide** Monotone Wiki http://www.venge.net/monotone/wiki Monotone Documentation http://www.venge.net/monotone/monotone.html