[Monotone-devel] A quickstart for Monotone - "3 Minutes to Monotone"

[Adam Logghe]

I've created this short quickstart to Monotone. I've tried to keep it 
short and you'll also noticed that I've oriented around netsync from the 
beginning. As I evaluated Monotone the easy peer to peer model that 
solved the simple problem I present here was what clinched the deal for 
me. I hope this helps someone else see Monotone's value quickly and clearly.

This has been debugged by only two people so far. If you have ANY 
questions or suggestions about this, including even the basic philosophy 
of my emphasis I would love to hear them. I'll plan on posting this to 
the wiki.

3 Minutes to Monotone for a single developer with multiple machines.

Problem-

You work from several machines- a workstation at home, a laptop and a 
workstation at work. You would like the ability to develop (or version 
control your home directories) from all of these machines with as little 
hassle as possible. You want these machines to seemlessly exchange with 
each other. You sometimes want to work when you have no network access 
at all. In this solution you'll concentrate on the networking and 
synchronization capabilities of Monotone, to get yourself comfortable 
with the ease of transporting your code and files around. Branching, 
merging and other developers come later. Notice the Section pointers to 
the actual Monotone manual.

Solution-

Create a database on your home workstation to hold your trees of files 
(see Section 2.1) You may wish to do this in a "test" directory as 
Monotone does have a few files it creates in its working directory, you 
should also precopy a "bookmarks.html" file or nonempty text file into 
that "test" directory

monotone --db=yournewdb.db db init

Create your key, it will ask for a password which you're going to need 
to enter periodically as you do things (see Section 2.2)

monotone --db=yournewdb.db genkey address@hidden

Copy your empty database (the key you created is stored in the database) 
to your laptop.

scp yournewdb.db address@hidden:

Add a file on your workstation to your database and give it a 
descriptive branch name(see Section 2.3)

monotone --db=yournewdb.db --branch=org.yourdomain.bookmarks add 
bookmarks.html

Commit that file into the actual database (see Section 2.4)

monotone commit "My first import of a branch in monotone."

Create a text file "permissions.lua" defining access to your server with 
the following contents (see Section 3.3)

function get_netsync_read_permitted (collection, identity)
     if (identity == "address@hidden") then return true end
     return false
end

function get_netsync_write_permitted (collection, identity)
     if (identity == "address@hidden") then return true end
     return false
end

Start a monotone server on your workstation serving the "org.yourdomain" 
(and everything below it) branch from the database  (see Section 3.3)

monotone --db=yournewdb.db --rcfile=permissions.lua serve 
yourworkstationip org.yourdomain

Go to your laptop and grab the branch you committed on your workstation 
(see Section 3.2)

monotone --db=yournewdb.db sync yourworkstationip org.yourdomain

For now you will have to enter your password on BOTH the workstation and 
the laptop to start the netsync (you can change this behaviour later)

Take a look at the branch that you just grabbed (see Section 6.1 and 
Section 4.1)

monotone --db=yournewdb.db list branches

This will list the branch org.yourdomain.bookmarks You can checkout this 
branch by giving the command (notice the trailing . for current directory)

monotone --db=yournewdb.db --branch=org.yourdomain.bookmarks checkout .

Now change a word or character in bookmarks.html with an editor and 
check it back in

monotone commit "Another commit"

You should now "sync" again with your workstation by issuing the same 
command as before (see Section 3.2)

monotone --db=yournewdb.db sync yourworkstationip org.yourdomain

To tinker a bit you might now return to your workstation and see that 
your changed branch propagated by checking it out at the workstation.

Now that you have the basic workings of the setup, networking and 
replication of Monotone, if you'd like to proceed further you really 
should read the excellent (and concise!) manual that comes with 
Monotone. The mailing list and irc channel are quite friendly if you 
want a hand with Monotone.

Adam