Monotone is a distributed version control tool. It can help automate many tedious and error-prone tasks in group software development.
Please be aware that monotone is a slightly unorthodox version control tool, and many of its concepts are similar — but subtly or significantly different — from concepts with similar names in other version control tools.
Complete table of contents
This chapter should familiarize you with the concepts, terminology, and behavior described in the remainder of the user manual. Please take a moment to read it, as later sections will assume familiarity with these terms.
Suppose you wish to modify a file file.txt on your computer. You begin with one version of the file, load it into an editor, make some changes, and save the file again. Doing so produces a new version of the file. We will say that the older version of the file was a parent, and the new version is a child, and that you have performed an edit between the parent and the child. We may draw the relationship between parent and child using a graph, where the arrow in the graph indicates the direction of the edit, from parent to child.
We may want to identify the parent and the child precisely, for sake of reference. To do so, we will compute a cryptographic hash function, called sha1, of each version. The details of this function are beyond the scope of this document; in summary, the sha1 function takes a version of a file and produces a short string of 20 bytes, which we will use to uniquely identify the version1. Now our graph does not refer to some “abstract” parent and child, but rather to the exact edit we performed between a specific parent and a specific child.
When dealing with versions of files, we will dispense with writing out “file names”, and identify versions purely by their sha1 value, which we will also refer to as their file ID. Using IDs alone will often help us accommodate the fact that people often wish to call files by different names. So now our graph of parent and child is just a relationship between two versions, only identified by ID.
Version control systems, such as monotone, are principally concerned
with the storage and management of multiple versions of some files.
One way to store multiple versions of a file is, literally, to save a
separate complete copy of the file, every time you make a
change. When necessary, monotone will save complete copies of your
files, compressed with the zlib compression format.
Often we find that successive versions of a file are very similar to one another, so storing multiple complete copies is a waste of space. In these cases, rather than store complete copies of each version of a file, we store a compact description of only the changes which are made between versions. Such a description of changes is called a delta.
Storing deltas between files is, practically speaking, as good as
storing complete versions of files. It lets you undo changes from a
new version, by applying the delta backwards, and lets your friends
change their old version of the file into the new version, by applying
the delta forwards. Deltas are usually smaller than full files, so
when possible monotone stores deltas, using a modified xdelta
format. The details of this format are beyond the scope of this
document.
After you have made many different files, you may wish to capture a “snapshot” of the versions of all the files in a particular collection. Since files are typically collected into trees in a file system, we say that you want to capture a version of your tree. Doing so will permit you to undo changes to multiple files at once, or send your friend a set of changes to many files at once.
To make a snapshot of a tree, we begin by writing a special file called a manifest. In fact, monotone will write this file for us, but we could write it ourselves too. It is just a plain text file, in a structured but human-readable format used by several parts of monotone. Each file entry of a manifest binds a specific name, as a full path from the root of the workspace, to a specific file ID, as the hash of its content. In this way, the manifest collects together the snapshot of the file names and contents you have at this point in time; other snapshots with other manifests can use different names for the same file, or different contents for the same name.
Other entries in the manifest format name directories or store file attrs, which we will cover later.
Now we note that a manifest is itself a file. Therefore a manifest can serve as input to the sha1 function, and thus every manifest has an ID of its own. By calculating the sha1 value of a manifest, we capture the state of our tree in a single manifest ID. In other words, the ID of the manifest essentially captures all the IDs and file names of every file in our tree, combined. So we may treat manifests and their IDs as snapshots of a tree of files, though lacking the actual contents of the files themselves.
As with versions of files, we may decide to store manifests in their entirety, or else we may store only a compact description of changes which occur between different versions of manifests. As with files, when possible monotone stores compact descriptions of changes between manifests; when necessary it stores complete versions of manifests.
Suppose you sit down to edit some files. Before you start working, you may record a manifest of the files, for reference sake. When you finish working, you may record another manifest. These “before and after” snapshots of the tree of files you worked on can serve as historical records of the set of changes, or changeset, that you made. In order to capture a “complete” view of history – both the changes made and the state of your file tree on either side of those changes – monotone builds a special composite file called a revision each time you make changes. Like manifests, revisions are ordinary text files which can be passed through the sha1 function and thus assigned a revision ID.
The content of a revision includes one or more changesets. These changesets make reference to file IDs, to describe how the tree changed. The revision also contains manifest IDs, as another way of describing the tree “before and after” the changeset — storing this information in two forms allows monotone to detect any bugs or corrupted data before they can enter your history. Finally and crucially, revisions also make reference to other revision IDs. This fact – that revisions include the IDs of other revisions – causes the set of revisions to join together into a historical chain of events, somewhat like a “linked list”. Each revision in the chain has a unique ID, which includes by reference all the revisions preceding it. Even if you undo a changeset, and return to a previously-visited manifest ID during the course of your edits, each revision will incorporate the ID of its predecessor, thus forming a new unique ID for each point in history.
Often, you will wish to make a statement about a revision, such as stating the reason that you made some changes, or stating the time at which you made the changes, or stating that the revision passes a test suite. Statements such as these can be thought of, generally, as a bundle of information with three parts:
For example, if you want to say that a particular revision was composed on April 4, 2003, you might make a statement like this:
In an ideal world, these are all the parts of a statement we would need in order to go about our work. In the real world, however, there are sometimes malicious people who would make false or misleading statements; so we need a way to verify that a particular person made a particular statement about a revision. We therefore will add two more pieces of information to our bundle:
When these 2 items accompany a statement, we call the total bundle of 5 items a certificate, or cert. A cert makes a statement in a secure fashion. The security of the signature in a cert is derived from the rsa cryptography system, the details of which are beyond the scope of this document.
Warning: because our certificates give the name of the signing key instead of the hash (ID), all key names must be globally unique forever. If you lose a key and need to generate a replacement, make sure that you give the replacement a different name.
Monotone uses certs extensively. Any “extra” information which needs to be stored, transmitted or retrieved — above and beyond files, manifests, and revisions — is kept in the form of certs. This includes change logs, time and date records, branch membership, authorship, test results, and more. When monotone makes a decision about storing, transmitting, or extracting files, manifests, or revisions, the decision is often based on certs it has seen, and the trustworthiness you assign to those certs.
The rsa cryptography system — and therefore monotone itself — requires that you exchange special “public” numbers with your friends, before they will trust certificates signed by you. These numbers are called public keys. Giving someone your public key does not give them the power to impersonate you, only to verify signatures made by you. Exchanging public keys should be done over a trusted medium, in person, or via a trusted third party. Advanced secure key exchange techniques are beyond the scope of this document.
Monotone moves information in and out of four different types of storage:
The keystore is a directory .monotone/keys in your home directory which contains copies of all your private keys. Each key is stored in a file whose name is the key identifier with some characters converted to underscores. When you use a key to sign a cert, the public half of that key is copied into your local database along with the cert.
All information passes through your local database, en route to some other destination. For example, when changes are made in a workspace, you may save those changes to your database, and later you may synchronize your database with someone else's. Monotone will not move information directly between a workspace and a remote database, or between workspaces. Your local database is always the “switching point” for communication.
A workspace is a tree of files in your file system, arranged according to the list of file paths and IDs in a particular manifest. A special directory called _MTN exists in the root of any workspace. Monotone keeps some special files in the _MTN directory, in order to track changes you make to your workspace. If you ever want to know if a directory is a monotone workspace, just look for this _MTN directory.
Aside from the special _MTN directory, a workspace is just a normal tree of files. You can directly edit the files in a workspace using a plain text editor or other program; monotone will automatically notice when you make any changes. If you wish to add files, remove files, or move files within your workspace, you must tell monotone explicitly what you are doing, as these actions cannot be deduced.
If you do not yet have a workspace, you can check out a workspace from a database, or construct one from scratch and add it into a database. As you work, you will occasionally commit changes you have made in a workspace to a database, and update a workspace to receive changes that have arrived in a database. Committing and updating take place purely between a database and a workspace; the network is not involved.
A database is a single, regular file. You can copy or back it up using standard methods. Typically you keep a database in your home directory. Databases are portable between different machine types. You can have multiple databases and divide your work between them, or keep everything in a single database if you prefer. You can dump portions of your database out as text, and read them back into other databases, or send them to your friends. Underneath, databases are accessed using a standard, robust data manager, which makes using even very large databases efficient. In dire emergencies, you can directly examine and manipulate a database using a simple SQL interface.
A database contains many files, manifests, revisions, and certificates, some of which are not immediately of interest, some of which may be unwanted or even false. It is a collection of information received from network servers, workspaces, and other databases. You can inspect and modify your databases without affecting your workspaces, and vice-versa.
Monotone knows how to exchange information in your database with other remote databases, using an interactive protocol called netsync. It supports three modes of exchange: pushing, pulling, and synchronizing. A pull operation copies data from a remote database to your local database. A push operation copies data from your local database to a remote database. A sync operation copies data both directions. In each case, only the data missing from the destination is copied. The netsync protocol calculates the data to send “on the fly” by exchanging partial hash values of each database.
In general, work flow with monotone involves 3 distinct stages:
The last stage of workflow is worth clarifying: monotone does not blindly apply all changes it receives from a remote database to your workspace. Doing so would be very dangerous, because remote databases are not always trustworthy systems. Rather, monotone evaluates the certificates it has received along with the changes, and decides which particular changes are safe and desirable to apply to your workspace.
You can always adjust the criteria monotone uses to judge the trustworthiness and desirability of changes in your database. But keep in mind that it always uses some criteria; receiving changes from a remote server is a different activity than applying changes to a workspace. Sometimes you may receive changes which monotone judges to be untrusted or bad; such changes may stay in your database but will not be applied to your workspace.
Remote databases, in other words, are just untrusted “buckets” of data, which you can trade with promiscuously. There is no trust implied in communication.
So far we have been talking about revisions as though each logically follows exactly one revision before it, in a simple sequence of revisions.
This is a rosy picture, but sometimes it does not work out this way. Sometimes when you make new revisions, other people are simultaneously making new revisions as well, and their revisions might be derived from the same parent as yours, or contain different changesets. Without loss of generality, we will assume simultaneous edits only happen two-at-a-time; in fact many more edits may happen at once but our reasoning will be the same.
We call this situation of simultaneous edits a fork, and will refer to the two children of a fork as the left child and right child. In a large collection of revisions with many people editing files, especially on many different computers spread all around the world, forks are a common occurrence.
If we analyze the changes in each child revision, we will often find that the changeset between the parent and the left child are unrelated to the changeset between the parent and the right child. When this happens, we can usually merge the fork, producing a common grandchild revision which contains both changesets.
Sometimes, people intentionally produce forks which are not supposed to be merged; perhaps they have agreed to work independently for a time, or wish to change their files in ways which are not logically compatible with each other. When someone produces a fork which is supposed to last for a while (or perhaps permanently) we say that the fork has produced a new branch. Branches tell monotone which revisions you would like to merge, and which you would like to keep separate.
You can see all the available branches using mtn list branches.
Branches are indicated with certs. The cert name branch is
reserved for use by monotone, for the purpose of identifying the
revisions which are members of a branch. A branch cert has a
symbolic “branch name” as its value. When we refer to “a branch”,
we mean all revisions with a common branch name in their branch
certs.
For example, suppose you are working on a program called “wobbler”.
You might develop many revisions of wobbler and then decide to split
your revisions into a “stable branch” and an “unstable branch”, to
help organize your work. In this case, you might call the new branches
“wobbler-stable” and “wobbler-unstable”. From then on, all
revisions in the stable branch would get a cert with name branch
and value wobbler-stable; all revisions in the unstable branch
would get a cert with name branch and value
wobbler-unstable. When a wobbler-stable revision forks,
the children of the fork will be merged. When a
wobbler-unstable revision forks, the children of the fork will
be merged. However, the wobbler-stable and
wobbler-unstable branches will not be merged together, despite
having a common ancestor.
For each branch, the set of revisions with no children is called the heads of the branch. Monotone can automatically locate, and attempt to merge, the heads of a branch. If it fails to automatically merge the heads, it may ask you for assistance or else fail cleanly, leaving the branch alone.
For example, if a fork's left child has a child of its own (a “left grandchild”), monotone will merge the fork's right child with the left grandchild, since those revisions are the heads of the branch. It will not merge the left child with the right child, because the left child is not a member of the heads.
When there is only one revision in the heads of a branch, we say that the heads are merged, or more generally that the branch is merged, since the heads is the logical set of candidates for any merging activity. If there are two or more revisions in the heads of a branch, and you ask to merge the branch, monotone will merge them two-at-a-time until there is only one.
The branch names used in the above section are fine for an example, but they would be bad to use in a real project. The reason is, monotone branch names must be globally unique, over all branches in the world. Otherwise, bad things can happen. Fortunately, we have a handy source of globally unique names — the DNS system.
When naming a branch, always prepend the reversed, fully qualified, domain name of a host that
you control or are otherwise authorized to use. For example, monotone
development happens on the branch net.venge.monotone, because
venge.net belongs to monotone's primary author. The idea is that
this way, you can coordinate with other people using a host to make sure
there are no conflicts — in the example, monotone's primary author can
be certain that no-one else using venge.net will start up a
different program named monotone. If you work for Yoyodyne,
Inc. (owners of yoyodyne.com), then all your branch names should look
like com.yoyodyne.something.
What the something part looks like is up to you, but
usually the first part is the project name (the monotone in
net.venge.monotone), and then possibly more stuff after that to
describe a particular branch. For example, monotone's win32 support
was initially developed on the branch net.venge.monotone.win32.
(For more information, see Naming Conventions.)
This chapter illustrates the basic uses of monotone by means of an example, fictional software project.
Before we walk through the tutorial, there are two minor issues to address: standard options and revision selectors.
Before operating monotone, two important command-line options should be explained.
Monotone will cache the settings for these options in your workspace, so ordinarily once you have checked out a project, you will not need to specify them again. We will therefore only mention these arguments in the first example.
Many commands require you to supply 40-character sha1 values as arguments, which identify revisions. These “revision IDs” are tedious to type, so monotone permits you to supply “revision selectors” rather than complete revision IDs. Selectors are a more “human friendly” way of specifying revisions by combining certificate values into unique identifiers. This “selector” mechanism can be used anywhere a revision ID would normally be used. For details on selector syntax, see Selectors.
We are now ready to explore our fictional project.
Our fictional project involves 3 programmers cooperating to write firmware for a robot, the JuiceBot 7, which dispenses fruit juice. The programmers are named Jim, Abe and Beth.
In our example the programmers work privately on laptops, and are usually disconnected from the network. They share no storage system. Thus when each programmer enters a command, it affects only his or her own computer, unless otherwise stated.
In the following, our fictional project team will work through several version control tasks. Some tasks must be done by each member of our example team; other tasks involve only one member.
The first step Jim, Abe and Beth each need to perform is to create a new database. This is done with the mtn db init command, providing a --db option to specify the location of the new database. Each programmer creates their own database, which will reside in their home directory and store all the revisions, files and manifests they work on. Monotone requires this step as an explicit command, to prevent spurious creation of databases when an invalid --db option is given.
In real life, most people prefer to keep one database for each project
they work on. If we followed that convention here in the tutorial,
though, then all the databases would be called juicebot.mtn, and
that would make things more confusing to read. So instead, we'll have
them each name their database after themselves.
Thus Jim issues the command:
$ mtn db init --db=~/jim.mtn
Abe issues the command:
$ mtn db init --db=~/abe.mtn
And Beth issues the command:
$ mtn db init --db=~/beth.mtn
Now Jim, Abe and Beth must each generate an rsa key pair for themselves. This step requires choosing a key identifier. Typical key identifiers are similar to email addresses, possibly modified with some prefix or suffix to distinguish multiple keys held by the same owner. Our example programmers will use their email addresses at the fictional “juicebot.co.jp” domain name. When we ask for a key to be generated, monotone will ask us for a passphrase. This phrase is used to encrypt the key when storing it on disk, as a security measure.
Jim does the following:
$ mtn genkey jim@juicebot.co.jp enter passphrase for key ID [jim@juicebot.co.jp] (...): <Jim enters his passphrase> confirm passphrase for key ID [jim@juicebot.co.jp] (...): <Jim confirms his passphrase> mtn: generating key-pair 'jim@juicebot.co.jp' mtn: storing key-pair 'jim@juicebot.co.jp' in /home/jim/.monotone/keys mtn: key 'jim@juicebot.co.jp' has hash '398cb10dcd4fadf4f7849a3734b626a83e0bb2ae'
Abe does something similar:
$ mtn genkey abe@juicebot.co.jp enter passphrase for key ID [abe@juicebot.co.jp] (...): <Abe enters his passphrase> confirm passphrase for key ID [abe@juicebot.co.jp] (...): <Abe confirms his passphrase> mtn: generating key-pair 'abe@juicebot.co.jp' mtn: storing key-pair 'abe@juicebot.co.jp' in /home/abe/.monotone/keys mtn: key 'abe@juicebot.co.jp' has hash '62d8d1798e716868acde75c0fc4c84760003863d'
as does Beth:
$ mtn genkey beth@juicebot.co.jp enter passphrase for key ID [beth@juicebot.co.jp] (...): <Beth enters her passphrase> confirm passphrase for key ID [beth@juicebot.co.jp] (...): <Beth confirms her passphrase> mtn: generating key-pair 'beth@juicebot.co.jp' mtn: storing key-pair 'beth@juicebot.co.jp' in /home/beth/.monotone/keys mtn: key 'beth@juicebot.co.jp' has hash 'c1d47c065a21f1e1c4fbdefaa2f37bd2c15ee4b1'
Each programmer has now generated a key pair and placed it in their keystore. Each can list the keys in their keystore, to ensure the correct key was generated. For example, Jim might see this:
$ mtn list keys [public keys] 398cb10dcd4fadf4f7849a3734b626a83e0bb2ae jim@juicebot.co.jp (*) (*) - only in /home/jim/.monotone/keys/ [private keys] 398cb10dcd4fadf4f7849a3734b626a83e0bb2ae jim@juicebot.co.jp
The hexadecimal string printed out before each key name is a fingerprint of the key, and can be used to verify that the key you have stored under a given name is the one you intended to store. Monotone will never permit one keystore to store two keys with the same fingerprint, however distincts keys with equal names are possible.
This output shows one private and one public key stored under the name
jim@juicebot.co.jp, so it indicates that Jim's key-pair has been
successfully generated and stored. On subsequent commands, Jim will need
to re-enter his passphrase in order to perform security-sensitive
tasks.
Pretty soon Jim gets annoyed when he has to enter his passphrase every
time he invokes mtn (and, more importantly, it simplifies the
tutorial text to skip the passphrase prompts) so he decides to use
ssh-agent to store his key. He does this by using the
ssh_agent_export command to export his key into a format that
ssh-agent can understand and adding it with ssh-add.
$ mtn ssh_agent_export ~/.ssh/id_monotone enter passphrase for key ID [user@example.com] (1234abcd...): enter new passphrase for key ID [user@example.com] (1234abcd...): confirm passphrase for key ID [user@example.com] (1234abcd...): $ chmod 600 ~/.ssh/id_monotone
From now on, Jim just needs to add his key to ssh-agent when he logs in and he will not need to enter his passphrase every time he uses monotone.
$ ssh-agent /bin/bash $ ssh-add ~/.ssh/id_monotone Enter passphrase for /home/user/.ssh/id_monotone: Identity added: /home/user/.ssh/id_monotone (/home/user/.ssh/id_monotone) $ mtn ci -m"Changed foo to bar" $ mtn push
The following procedure is deprecated and not suggested for general use as it is very insecure.
Jim isn't very worried about security so he decides to store his passphrase in his monotonerc file. He does this by writing a hook function which returns the passphrase:
$ mkdir ~/.monotone $ cat >>~/.monotone/monotonerc function get_passphrase(key_identity) return "jimsekret" end ^D
Now whenever monotone needs his passphrase, it will call this function
instead of prompting him to type it. Note that we are appending the new
hook to the (possibly existing) file. We do this to avoid losing other
changes by mistake; therefore, be sure to check that no other
get_passphrase function appears in the configuration file.
Abe and Beth do the same, with their secret passphrases.
Before he can begin work on the project, Jim needs to create a workspace — a directory whose contents monotone will keep track of. Often, one works on projects that someone else has started, and creates workspaces with the checkout command, which you'll learn about later. Jim is starting a new project, though, so he does something a little bit different. He uses the mtn setup command to create a new workspace.
This command creates the named directory (if it doesn't already exist), and creates the _MTN directory within it. The _MTN directory is how monotone recognizes that a directory is a workspace, and monotone stores some bookkeeping files within it. For instance, command line values for the --db, --branch or --key options to the setup command will be cached in a file called _MTN/options, so you don't have to keep passing them to monotone all the time.
He chooses jp.co.juicebot.jb7 as a branch name. (See
Naming Conventions for more information about appropriate branch
names.) Jim then creates his workspace:
/home/jim$ mtn --db=jim.mtn --branch=jp.co.juicebot.jb7 setup juice /home/jim$ cd juice /home/jim/juice$
Notice that Jim has changed his current directory to his newly created workspace. For the rest of this example we will assume that everyone issues all further monotone commands from their workspace directories.
Next Jim decides to add some files to the project. He writes up a file containing the prototypes for the JuiceBot 7:
$ mkdir include $ cat >include/jb.h /* Standard JuiceBot hw interface */ #define FLOW_JUICE 0x1 #define POLL_JUICE 0x2 int spoutctl(int port, int cmd, void *x); /* JuiceBot 7 API */ #define APPLE_SPOUT 0x7e #define BANANA_SPOUT 0x7f void dispense_apple_juice (); void dispense_banana_juice (); ^D
Then adds a couple skeleton source files which he wants Abe and Beth to fill in:
$ mkdir src
$ cat >src/apple.c
#include "jb.h"
void
dispense_apple_juice()
{
/* Fill this in please, Abe. */
}
^D
$ cat >src/banana.c
#include "jb.h"
void
dispense_banana_juice()
{
/* Fill this in please, Beth. */
}
^D
Now Jim tells monotone to add these files to its record of his workspace. He specifies one filename and one directory; monotone recursively scans the directory and adds all its files.
$ mtn add include/jb.h src mtn: adding include/jb.h to workspace manifest mtn: adding src/apple.c to workspace manifest mtn: adding src/banana.c to workspace manifest
This command produces a record of Jim's intentions in a special file called _MTN/revision, stored in the workspace. The file is plain text:
$ cat _MTN/revision format_version "1" new_manifest [2098eddbe833046174de28172a813150a6cbda7b] old_revision [] add_file "include/jb.h" content [3b12b2d0b31439bd50976633db1895cff8b19da0] add_file "src/apple.c" content [2650ffc660dd00a08b659b883b65a060cac7e560] add_file "src/banana.c" content [e8f147e5b4d5667f3228b7bba1c5c1e639f5db9f]
You will never have to look at this file, but it is nice to know that it is there.
Jim then gets up from his machine to get a coffee. When he returns he has forgotten what he was doing. He asks monotone:
$ mtn status Current branch: jp.co.juicebot.jb7 Changes against parent : added include/jb.h added src/apple.c added src/banana.c
The output of this command tells Jim that his edits, so far, constitute only the addition of some files.
Jim wants to see the actual details of the files he added, however, so he runs a command which prints out the status and a GNU “unified diff” of the patches involved in the changeset:
$ mtn diff
#
# old_revision []
#
# add_file "include/jb.h"
# content [3b12b2d0b31439bd50976633db1895cff8b19da0]
#
# add_file "src/apple.c"
# content [2650ffc660dd00a08b659b883b65a060cac7e560]
#
# add_file "src/banana.c"
# content [e8f147e5b4d5667f3228b7bba1c5c1e639f5db9f]
#
============================================================================
--- include/jb.h
+++ include/jb.h 3b12b2d0b31439bd50976633db1895cff8b19da0
@ -0,0 +1,13 @
+/* Standard JuiceBot hw interface */
+
+#define FLOW_JUICE 0x1
+#define POLL_JUICE 0x2
+#define SET_INTR 0x3
+int spoutctl(int port, int cmd, void *x);
+
+/* JuiceBot 7 API */
+
+#define APPLE_SPOUT 0x7e
+#define BANANA_SPOUT 0x7f
+void dispense_apple_juice ();
+void dispense_banana_juice ();
============================================================================
--- src/apple.c
+++ src/apple.c 2650ffc660dd00a08b659b883b65a060cac7e560
@ -0,0 +1,7 @
+#include "jb.h"
+
+void
+dispense_apple_juice()
+{
+ /* Fill this in please, Abe. */
+}
============================================================================
--- src/banana.c
+++ src/banana.c e8f147e5b4d5667f3228b7bba1c5c1e639f5db9f
@ -0,0 +1,7 @
+#include "jb.h"
+
+void
+dispense_banana_juice()
+{
+ /* Fill this in please, Beth. */
+}
Satisfied with the work he's done, Jim wants to save his changes. He then commits his workspace, which causes monotone to process the _MTN/revision file and record the file contents, manifest, and revision into the database. Since he provided a branch name when he ran setup, monotone will use this as the default branch name when he commits.
$ mtn commit --message="initial checkin of project" mtn: beginning commit on branch 'jp.co.juicebot.jb7' mtn: committed revision 2e24d49a48adf9acf3a1b6391a080008cbef9c21
When monotone committed Jim's revision, it updated _MTN/revision to record the workspace's new base revision ID. Jim can use this revision ID in the future, as an argument to the checkout command, if he wishes to return to this revision:
$ mtn automate get_base_revision_id 2e24d49a48adf9acf3a1b6391a080008cbef9c21
Monotone also generated a number of certificates attached to the new revision, and made sure that the database contained a copy of Jim's public key. These certs store metadata about the commit. Jim can ask monotone for a list of certs on this revision.
$ mtn ls certs 2e24d49a48adf9acf3a1b6391a080008cbef9c21 ----------------------------------------------------------------- Key : jim@juicebot.co.jp (398cb10d...) Sig : ok Name : branch Value : jp.co.juicebot.jb7 ----------------------------------------------------------------- Key : jim@juicebot.co.jp (398cb10d...) Sig : ok Name : date Value : 2004-10-26T02:53:08 ----------------------------------------------------------------- Key : jim@juicebot.co.jp (398cb10d...) Sig : ok Name : author Value : jim@juicebot.co.jp ----------------------------------------------------------------- Key : jim@juicebot.co.jp (398cb10d...) Sig : ok Name : changelog Value : initial checkin of project
The output of this command has a block for each cert found. Each block
has 4 significant pieces of information. The first indicates the
signer of the cert, in this case jim@juicebot.co.jp. The
second indicates whether this cert is “ok”, meaning whether the
rsa signature provided is correct for the cert data. The third is
the cert name, and the fourth is the cert value. This list shows us
that monotone has confirmed that, according to
jim@juicebot.co.jp, the revision
2e24d49a48adf9acf3a1b6391a080008cbef9c21 is a member of the
branch jp.co.juicebot.jb7, written by
jim@juicebot.co.jp, with the given date and changelog.
It is important to keep in mind that revisions are not “in” or “out” of a branch in any global sense, nor are any of these cert values true or false in any global sense. Each cert indicates that some person – in this case Jim – would like to associate a revision with some value; it is up to you to decide if you want to accept that association.
Jim can now check the status of his branch using the “heads” command, which lists all the head revisions in the branch:
$ mtn heads branch 'jp.co.juicebot.jb7' is currently merged: 2e24d49a48adf9acf3a1b6391a080008cbef9c21 jim@juicebot.co.jp 2004-10-26T02:53:08
The output of this command tells us that there is only one current
“head” revision in the branch jp.co.juicebot.jb7, and it is
the revision Jim just committed. A head revision is one without any
descendants. Since Jim has not committed any changes to this revision
yet, it has no descendants.
Jim now decides he will make his base revision available to his employees. To do this, he arranges for Abe and Beth to synchronise their databases with his, over the network. There are two pre-requisites for this: first, he has to get a copy of each of their public keys; then, he has to tell monotone that the holders of those keys are permitted to access his database. Finally, with these pre-requisites in place, he needs to tell monotone to provide network access to his database.
First, Abe exports his public key:
$ mtn --db=~/abe.mtn pubkey abe@juicebot.co.jp >~/abe.pubkey
His public key is just a plain block of ASCII text:
$ cat ~/abe.pubkey [pubkey abe@juicebot.co.jp] MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCbaVff9SF78FiB/1nUdmjbU/TtPyQqe/fW CDg7hSg1yY/hWgClXE9FI0bHtjPMIx1kBOig09AkCT7tBXM9z6iGWxTBhSR7D/qsJQGPorOD DO7xovIHthMbZZ9FnvyB/BCyiibdWgGT0Gtq94OKdvCRNuT59e5v9L4pBkvajb+IzQIBEQ== [end]
Beth also exports her public key:
$ mtn --db=~/beth.mtn pubkey beth@juicebot.co.jp >~/beth.pubkey
Then Abe and Beth both send their keys to Jim. The keys are not secret, but the team members must be relatively certain that they are exchanging keys with the person they intend to trust, and not some malicious person pretending to be a team member. Key exchange may involve sending keys over an encrypted medium, or meeting in person to exchange physical copies, or any number of techniques. All that matters, ultimately, is that Jim receives both Abe's and Beth's key in a way that he can be sure of.
So eventually, after key exchange, Jim has the public key files in his home directory. He tells monotone to read the associated key packets into his database:
$ cat ~/abe.pubkey ~/beth.pubkey | mtn --db=~/jim.mtn read mtn: read 2 packets
Now Jim's monotone is able to identify Beth and Abe, and he is ready to give them permission to access his database. He does this by editing a pair of small files in his ~/.monotone directory:
$ cat >>~/.monotone/read-permissions pattern "*" allow "abe@juicebot.co.jp" allow "beth@juicebot.co.jp" ^D $ cat >>~/.monotone/write-permissions abe@juicebot.co.jp beth@juicebot.co.jp ^D
These files are read by the default monotone hooks that will decide whether remote monotone users will be allowed access to Jim's database, identified by the named keys.
Jim then makes sure that his TCP port 4691 is open to incoming connections, adjusting his firewall settings as necessary, and runs the monotone serve command:
$ mtn --db=jim.mtn serve
This command starts monotone listening on all network interfaces of his laptop on the default port 4691, serving everything in his database.
With Jim's server preparations done, now Abe is ready to fetch Jim's code. To do this he issues the monotone sync command:
$ mtn --db=abe.mtn sync jim-laptop.juicebot.co.jp "jp.co.juicebot.jb7*" mtn: setting default server to jim-laptop.juicebot.co.jp mtn: setting default branch include pattern to 'jp.co.juicebot.jb7*' mtn: setting default branch exclude pattern to '' mtn: connecting to jim-laptop.juicebot.co.jp mtn: first time connecting to server jim-laptop.juicebot.co.jp:4691 mtn: I'll assume it's really them, but you might want to double-check mtn: their key's fingerprint: 9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c mtn: warning: saving public key for jim@juicebot.co.jp to database mtn: finding items to synchronize: mtn: bytes in | bytes out | revs in | revs out | revs written mtn: 2587 | 1025 | 1 | 0 | 1 mtn: successful exchange with jim-laptop.juicebot.co.jp
Abe now has, in his database, a copy of everything Jim put in the branch. Therefore Abe can disconnect from the expensive network connection he's on and work locally for a while. Remember that, in monotone, work is done between workspaces in the filesystem and the local database; network connectivity is necessary only when that work is to be shared with others.
As we follow the juicebot team through the next several steps, we'll see them run the sync command again with Jim, and work will flow both ways. The first time you sync a new database, monotone remembers the server and branch patterns you use, and makes them the default for future operations.
At the end of each exchange, information about all changes in the branch known to each database have been sent to the other party - including the work of the third team member that had previously been exchanged. As well as allowing each team member to learn about the others' work, this also means that each party's laptop contains a backup of the others' work too.
Jim, Abe and Beth will continue working like this while they're getting started, and we'll revisit the issue of network service with them a little later as the project grows.
Abe decides to do some work on his part of the code. He has a copy of
Jim's database contents, but cannot edit any of that data yet. He
begins his editing by checking out the head of the
jp.co.juicebot.jb7 branch into a workspace, so he can edit
it:
$ mtn --db=abe.mtn --branch=jp.co.juicebot.jb7 checkout .
Monotone unpacks the set of files in the head revision's manifest directly into Abe's current directory. (If he had specified something other than . at the end, monotone would have created that directory and unpacked the files into it.) Abe then opens up one of the files, src/apple.c, and edits it:
$ vi src/apple.c <Abe writes some apple-juice dispensing code>
The file src/apple.c has now been changed. Abe gets up to answer a phone call, and when he returns to his work he has forgotten what he changed. He can ask monotone for details:
$ mtn diff
#
# old_revision [2e24d49a48adf9acf3a1b6391a080008cbef9c21]
#
# patch "src/apple.c"
# from [2650ffc660dd00a08b659b883b65a060cac7e560]
# to [e2c418703c863eabe70f9bde988765406f885fd0]
#
============================================================================
--- src/apple.c 2650ffc660dd00a08b659b883b65a060cac7e560
+++ src/apple.c e2c418703c863eabe70f9bde988765406f885fd0
@ -1,7 +1,10 @
#include "jb.h"
void
dispense_apple_juice()
{
- /* Fill this in please, Abe. */
+ spoutctl(APPLE_SPOUT, FLOW_JUICE, 1);
+ while (spoutctl(APPLE_SPOUT, POLL_JUICE, 1) == 0)
+ usleep (1000);
+ spoutctl(APPLE_SPOUT, FLOW_JUICE, 0);
}
Satisfied with his day's work, Abe decides to commit.
$ mtn commit mtn: beginning commit on branch 'jp.co.juicebot.jb7'
Abe neglected to provide a --message option specifying the change log on the command line and the file _MTN/log is empty because he did not document his changes there. Monotone therefore invokes an external “log message editor” — typically an editor like vi — with an explanation of the changes being committed and the opportunity to enter a log message.
polling implementation of src/apple.c MTN: ---------------------------------------------------------------------- MTN: Enter a description of this change. MTN: Lines beginning with `MTN:' are removed automatically. MTN: MTN: Current branch: jp.co.juicebot.jb7 MTN: Changes against parent 2e24d49a48adf9acf3a1b6391a080008cbef9c21 MTN: patched src/apple.c MTN: ---------------------------------------------------------------------- MTN:
Abe enters a single line above the explanatory message, saying “polling implementation of src/apple.c”. He then saves the file and quits the editor. Monotone deletes all the lines beginning with “MTN:” and leaves only Abe's short message. Returning to the shell, Abe's commit completes:
mtn: committed revision 70decb4b31a8227a629c0e364495286c5c75f979
Abe then sends his new revision back to Jim:
$ mtn sync mtn: connecting to jim-laptop.juicebot.co.jp mtn: finding items to synchronize: mtn: certs | keys | revisions mtn: 8 | 2 | 2 mtn: bytes in | bytes out | revs in | revs out | revs written mtn: 615 | 2822 | 0 | 1 | 0 mtn: successful exchange with jim-laptop.juicebot.co.jp
Beth does a similar sequence. First she syncs her database with Jim's:
$ mtn --db=beth.mtn sync jim-laptop.juicebot.co.jp "jp.co.juicebot.jb7*" mtn: setting default server to jim-laptop.juicebot.co.jp mtn: setting default branch include pattern to 'jp.co.juicebot.jb7*' mtn: setting default branch exclude pattern to '' mtn: connecting to jim-laptop.juicebot.co.jp mtn: first time connecting to server jim-laptop.juicebot.co.jp:4691 mtn: I'll assume it's really them, but you might want to double-check mtn: their key's fingerprint: 9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c mtn: warning: saving public key for jim@juicebot.co.jp to database mtn: finding items to synchronize: mtn: bytes in | bytes out | revs in | revs out | revs written mtn: 4601 | 1239 | 2 | 0 | 1 mtn: verifying new revisions (this may take a while) mtn: bytes in | bytes out | revs in | revs out | revs written mtn: 4601 | 1285 | 2 | 0 | 2 mtn: successful exchange with jim-laptop.juicebot.co.jp
She checks out a copy of the tree from her database:
$ mtn --db=beth.mtn --branch=jp.co.juicebot.jb7 checkout .
She edits the file src/banana.c:
$ vi src/banana.c <Beth writes some banana-juice dispensing code>
and logs her changes in _MTN/log right away so she does not forget what she has done like Abe.
$ vi _MTN/log * src/banana.c: Added polling implementation
Later, she commits her work. Monotone again invokes an external editor for her to edit her log message, but this time it fills in the messages she's written so far, and she simply checks them over one last time before finishing her commit:
$ mtn commit mtn: beginning commit on branch 'jp.co.juicebot.jb7' mtn: committed revision 80ef9c9d251d39074d37e72abf4897e0bbae1cfb
And she syncs with Jim again:
$ mtn sync mtn: connecting to jim-laptop.juicebot.co.jp mtn: finding items to synchronize: mtn: certs | keys | revisions mtn: 12 | 3 | 3 mtn: bytes in | bytes out | revs in | revs out | revs written mtn: 709 | 2879 | 0 | 1 | 0 mtn: successful exchange with jim-laptop.juicebot.co.jp
Careful readers will note that, in the previous section, the JuiceBot company's work was perfectly serialized:
The result of this ordering is that Jim's work entirely preceded Abe's work, which entirely preceded Beth's work. Moreover, each worker was fully informed of the “up-stream” worker's actions, and produced purely derivative, “down-stream” work:
This is a simple, but sadly unrealistic, ordering of events. In real companies or work groups, people often work in parallel, diverging from commonly known revisions and merging their work together, sometime after each unit of work is complete.
Monotone supports this diverge/merge style of operation naturally; any time two revisions diverge from a common parent revision, we say that the revision graph has a fork in it. Forks can happen at any time, and require no coordination between workers. In fact any interleaving of the previous events would work equally well; with one exception: if forks were produced, someone would eventually have to run the merge command, and possibly resolve any conflicts in the fork.
To illustrate this, we return to our workers Beth and Abe. Suppose Jim sends out an email saying that the current polling juice dispensers use too much CPU time, and must be rewritten to use the JuiceBot's interrupt system. Beth wakes up first and begins working immediately, basing her work off the revision 80ef9... which is currently in her workspace:
$ vi src/banana.c <Beth changes her banana-juice dispenser to use interrupts>
Beth finishes and examines her changes:
$ mtn diff
#
# old_revision [80ef9c9d251d39074d37e72abf4897e0bbae1cfb]
#
# patch "src/banana.c"
# from [7381d6b3adfddaf16dc0fdb05e0f2d1873e3132a]
# to [5e6622cf5c8805bcbd50921ce7db86dad40f2ec6]
#
============================================================================
--- src/banana.c 7381d6b3adfddaf16dc0fdb05e0f2d1873e3132a
+++ src/banana.c 5e6622cf5c8805bcbd50921ce7db86dad40f2ec6
@ -1,10 +1,15 @
#include "jb.h"
+static void
+shut_off_banana()
+{
+ spoutctl(BANANA_SPOUT, SET_INTR, 0);
+ spoutctl(BANANA_SPOUT, FLOW_JUICE, 0);
+}
+
void
-dispense_banana_juice()
+dispense_banana_juice()
{
+ spoutctl(BANANA_SPOUT, SET_INTR, &shut_off_banana);
spoutctl(BANANA_SPOUT, FLOW_JUICE, 1);
- while (spoutctl(BANANA_SPOUT, POLL_JUICE, 1) == 0)
- usleep (1000);
- spoutctl(BANANA_SPOUT, FLOW_JUICE, 0);
}
She commits her work:
$ mtn commit --message="interrupt implementation of src/banana.c" mtn: beginning commit on branch 'jp.co.juicebot.jb7' mtn: committed revision 8b41b5399a564494993063287a737d26ede3dee4
And she syncs with Jim:
$ mtn sync
Unfortunately, before Beth managed to sync with Jim, Abe had woken up and implemented a similar interrupt-based apple juice dispenser, but his workspace is 70dec..., which is still “upstream” of Beth's.
$ vi apple.c <Abe changes his apple-juice dispenser to use interrupts>
Thus when Abe commits, he unknowingly creates a fork:
$ mtn commit --message="interrupt implementation of src/apple.c"
Abe does not see the fork yet; Abe has not actually seen any of Beth's work yet, because he has not synchronized with Jim. Since he has new work to contribute, however, he now syncs:
$ mtn sync
Now Jim and Abe will be aware of the fork. Jim sees it when he sits down at his desk and asks monotone for the current set of heads of the branch:
$ mtn heads mtn: branch 'jp.co.juicebot.jb7' is currently unmerged: 39969614e5a14316c7ffefc588771f491c709152 abe@juicebot.co.jp 2004-10-26T02:53:16 8b41b5399a564494993063287a737d26ede3dee4 beth@juicebot.co.jp 2004-10-26T02:53:15
Clearly there are two heads to the branch: it contains an un-merged fork. Beth will not yet know about the fork, but in this case it doesn't matter: anyone can merge the fork, and since there are no conflicts Jim does so himself:
$ mtn merge mtn: starting with revision 1 / 2 mtn: merging with revision 2 / 2 mtn: [source] 39969614e5a14316c7ffefc588771f491c709152 mtn: [source] 8b41b5399a564494993063287a737d26ede3dee4 mtn: common ancestor 70decb4b31a8227a629c0e364495286c5c75f979 abe@juicebot.co.jp 2004-10-26T:02:50:01 found mtn: trying 3-way merge mtn: [merged] da499b9d9465a0e003a4c6b2909102ef98bf4e6d mtn: your workspaces have not been updated
The output of this command shows Jim that two heads were found, combined via a 3-way merge with their ancestor, and saved to a new revision. This happened automatically, because the changes between the common ancestor and heads did not conflict. If there had been a conflict, monotone would have invoked an external merging tool to help resolve it, or Jim could have used the conflicts set of commands to resolve it (see Conflicts).
After merging, the branch has a single head again, and Jim updates his workspace.
$ mtn update mtn: selected update target da499b9d9465a0e003a4c6b2909102ef98bf4e6d mtn: updating src/apple.c to f088e24beb43ab1468d7243e36ce214a559bdc96 mtn: updating src/banana.c to 5e6622cf5c8805bcbd50921ce7db86dad40f2ec6 mtn: updated to base revision da499b9d9465a0e003a4c6b2909102ef98bf4e6d
The update command selected an update target — in this case the newly merged head — and performed an in-memory merge between Jim's workspace and the chosen target. The result was then written to Jim's workspace. If Jim's workspace had any uncommitted changes in it, they would have been merged with the update in exactly the same manner as the merge of multiple committed heads.
Monotone makes very little distinction between a “pre-commit” merge (an update) and a “post-commit” merge. Both sorts of merge use the exact same algorithm. The major difference concerns the recoverability of the pre-merge state: if you commit your work first, and merge after committing, then even if the merge somehow fails (due to difficulty in a manual merge step, for instance), your committed state is still safe. If you update, on the other hand, you are requesting that monotone directly modify your workspace, and while monotone will try hard not to break anything, this process is inherently more open to error. It is therefore recommended that you commit your work first, before merging.
If you have previously used another version control system, this may at first seem surprising; there are some systems where you are required to update, and risk the above problems, before you can commit. Monotone, however, was designed with this problem in mind, and thus always allows you to commit before merging. A good rule of thumb is to only use update in workspaces with no local modifications, or when you actually want to work against a different base revision (perhaps because finishing your change turns out to require some fixes made in another revision, or because you discover that you have accidentally started working against a revision that contains unrelated bugs, and need to back out to a working revision for testing).
So by now you're familiar with making changes, sharing them with other people, and integrating your changes with their changes. Sometimes, though, you may want to make some changes, and not integrate them with other people's — or at least not right away. One way to do this would be to simply never run mtn merge; but it would quickly become confusing to try and keep track of which changes were in which revisions. This is where branches are useful.
Continuing our example, suppose that Jim is so impressed by Beth's work on banana juice support that he assigns her to work on the JuiceBot 7's surprise new feature: muffins. In the mean time, Abe will continue working on the JuiceBot's basic juice-related functions.
The changes required to support muffins are somewhat complicated, and Beth is worried that her work might destabilize the program, and interfere with Abe's work. In fact, she isn't even sure her first attempt will turn out to be the right approach; she might work on it for a while and then decide it was a bad idea, and should be discarded. For all these reasons, she decides that she will work on a branch, and then once she is satisfied with the new code, she will merge back onto the mainline.
She decides that since main development is in branch
jp.co.juicebot.jb7, she will use branch
jp.co.juicebot.jb7.muffins. So, she makes the first few edits to
the new muffins code, and commits it on a new branch by simply passing
--branch to commit:
$ mtn commit --branch=jp.co.juicebot.jb7.muffins --message='autobake framework' mtn: beginning commit on branch 'jp.co.juicebot.jb7.muffins' mtn: committed revision d33caefd61823ecbb605c39ffb84705dec449857
That's all there is to it — there is now a
jp.co.juicebot.jb7.muffins branch, with her initial checkin on
it. She can make further checkins from the same workspace, and they
will automatically go to the muffins branch; if anyone else wants to
help her work on muffins, they can check out that branch as usual.
Of course, while Beth is working on the new muffins code, Abe is still making fixes to the main line. Occasionally, Beth wants to integrate his latest work into the muffins branch, so that her version doesn't fall too far behind. She does this by using the propagate command:
$ mtn propagate jp.co.juicebot.jb7 jp.co.juicebot.jb7.muffins mtn: propagating jp.co.juicebot.jb7 -> jp.co.juicebot.jb7.muffins mtn: [source] da003f115752ac6e4750b89aaca9dbba178ac80c mtn: [target] d0e5c93bb61e5fd25a0dadf41426f209b73f40af mtn: common ancestor 853b8c7ac5689181d4b958504adfb5d07fd959ab jim@juicebot.co.jp 2004-10-26T:12:44:23 found mtn: trying 3-way merge mtn: [merged] 89585b3c5e51a5a75f5d1a05dda859c5b7dde52f
The propagate merges all of the new changes on one branch onto another.
When the muffins code is eventually stable and ready to be integrated into the main line of development, she simply propagates the other way:
$ mtn propagate jp.co.juicebot.jb7.muffins jp.co.juicebot.jb7 mtn: propagating jp.co.juicebot.jb7.muffins -> jp.co.juicebot.jb7 mtn: [source] 4e48e2c9a3d2ca8a708cb0cc545700544efb5021 mtn: [target] bd29b2bfd07644ab370f50e0d68f26dcfd3bb4af mtn: common ancestor 652b1035343281a0d2a5de79919f9a31a30c9028 jim@juicebot.co.jp 2004-10-26T:15:25:05 found mtn: [merged] 03f7495b51cc70b76872ed019d19dee1b73e89b6
Monotone always records the full history of all merges, and is designed to handle an arbitrarily complicated graph of changes. You can make a branch, then branch off from that branch, propagate changes between arbitrary branches, and so on; monotone will track all of it, and do something sensible for each merge. Of course, it is still probably a good idea to come up with some organization of branches and a plan for which should be merged to which other ones. Monotone may keep track of graphs of arbitrary complexity — but you will have more trouble. Whatever arrangement of branches you come up with, though, monotone should be able to handle it.
If you are unsure of the name of a branch, you can list all branches using the ls branches command. This is very useful, but if you create a lot of branches then the list can become very long and unwieldy. To help this monotone has the suspend command which partially hides revisions/branches you are no longer using. Further commits on hidden branches will automatically unhide the branches.
For example, if Beth is now finished with the muffins branch, she can stop it from cluttering the list of branches by suspending the last revision in that branch:
$ mtn ls branches jp.co.juicebot.jb7 jp.co.juicebot.jb7.muffins $ mtn heads mtn: branch 'jp.co.juicebot.jb7.muffins' is currently merged: 4e48e2c9a3d2ca8a708cb0cc545700544efb5021 beth@juicebot.co.jp 2007-07-08T02:17:37 $ mtn suspend 4e48e2c9a3d2ca8a708cb0cc545700544efb5021 $ mtn ls branches jp.co.juicebot.jb7
Up until now, Jim has been using his laptop and database as a sort of “central server” for the company; Abe and Beth have been syncing with Jim, and learning of each other's work via Jim's database. This has worked fine while the product has been in early development; Jim has good network connectivity in Japan, and has been staying home concentrating on programming. He has been able to leave his laptop connected and running all the time, while his employees in different time-zones work and sync their databases. This is now starting to change, and two problems are starting to cause occasional difficulties.
This doesn't prevent them doing any work, but it does have some uncomfortable consequences: they're more likely to have to manually merge conflicting changes when they finally sync up and discover they've both come up with slightly different fixes for the same bug in the meantime, and they're more exposed to loss of work if one of them suffers a disk failure before they've had a chance to sync that work with another database.
The level of project activity is picking up, and there are more and more changes to be synced in the narrower window of time while Jim is connected. He finds he sometimes needs to take down the server process to do this local work, further exacerbating the first problem.
The juicebot team are resourceful, and by now quite used to working independently. While Jim has been away travelling, Abe and Beth have come up with their own solution to the first problem: they'll run servers from their databases, setting them up just like Jim did previously. That way, if Jim's database is offline, either Beth or Abe can run the serve command and provide access for the other to sync with. Beth also has the idea to create a second database for the serve process, and to sync her development database with that server locally, avoiding locking contention between multiple monotone processes on the one database file.
When Jim reappears, the next person to sync with him will often pass him information about both employees' work that they've sync'ed with each other in the meantime, just as he used to do. In fact, Jim now finds it more convenient to initiate the sync with one of the other servers when he has a spare moment and dynamic connectivity from a hotel room or airport. Changes will flow between servers automatically as clients access them and trade with one another.
This gets them by for a while, but there are still occasional inconveniences. Abe and Beth live in very different time-zones, and don't always have reliable network connectivity, so sometimes Jim finds that neither of them is online to sync with when he has the chance. Jim now also has several customers interested in beta-testing the new code, and following changes as the bugs and issues they report are addressed.
Jim decides it's time for a permanent server they can all sync with; this way, everyone always knows where to go to get the latest changes, and people can push their changes out without first calling their friends and making sure that they have their servers running.
Jim has rented some web server space on a service provider's shared
system for the JuiceBot Inc. public website, www.juicebot.co.jp;
he thinks this server will be a good place to host the central monotone
server too. He sets up a new monotone database on the server,
generates a new key specially for the server (so he doesn't have to
expose his own development private key on the shared system), and loads
in the team-members' keys:
$ mtn --db=server.mtn db init $ mtn genkey monotone-server@www.juicebot.co.jp enter passphrase for key ID [monotone-server@www.juicebot.co.jp] (...): <Jim enters a new passphrase> confirm passphrase for key ID [monotone-server@www.juicebot.co.jp] (...): <Jim confirms the passphrase> mtn: generating key-pair 'monotone-server@www.juicebot.co.jp' mtn: storing key-pair 'monotone-server@www.juicebot.co.jp' in /home/jim/.monotone/keys mtn: key 'abe@juicebot.co.jp' has hash '78be08f7a2a316a9f7c6b0db544ed20673ea2190' $ cat abe.pubkey beth.pubkey jim.pubkey | mtn --db=server.mtn read mtn: read 3 packets
For the team members, he sets up the permissions files on the server
much like before — except that of course he needs to also grant his
jim@juicebot.co.jp key permission to access the new server. For
the beta-testers, Jim wants to allow them read-only access just to the
main JuiceBot 7 development line, but not to any of the sub-branches
where other experimental development is going on. He adds some lines at
the top of the ~/.monotone/read-permissions on the server, above
the broader permissions given to team-members. See the Hook Reference for get_netsync_read_permitted for more details; the
resulting file looks like this:
comment "Provide beta-testers with specific read-only access" pattern "jp.co.juicebot.jb7" allow "beta1@juicebot.co.jp" allow "beta2@juicebot.co.jp" continue "true" comment "Fall-through, and allow staff access to all branches" pattern "*" allow "abe@juicebot.co.jp" allow "beth@juicebot.co.jp" allow "jim@juicebot.co.jp"
Jim could log in and start the monotone process manually from his shell
account on the server, perhaps under a program like screen to let it
stay running while he's away. This would be one way of giving it the
server-key's passphrase each startup, but he wants to make sure that the
server is up all the time; if the host reboots while he's travelling and
the monotone server is down until he next logs in, things aren't much
better than before. For the server to start automatically each time,
he'll need to use the get_passphrase hook in the server's
monotonerc file again.
Because he's running on a shared server, Jim needs to be a little more restrictive about which interfaces and addresses his new server process will listen on. He should only accept connections at the address used for his website, because some of the provider's other customers might also want to publish their own monotone projects on this host. Jim uses the --bind=address:port argument like so:
$ mtn --db=server.mtn --bind=www.juicebot.co.jp serve
This will start monotone listening on the default port (4691), but only
on the IP address associated with www.juicebot.co.jp. Jim can do
this because his hosting provider has given him a dedicated IP address
for his website. If the hosting provider offered only a single shared
IP address belonging to the server, each customer could bind a different
port number on that address.
While he's first testing the setup, Jim uses --bind=localhost:1234. This causes the monotone process to listen only to port 1234 on the loopback interface 127.0.0.1, which is not accessible from the network, so Jim doesn't expose an open port to the rest of the world until he's satisfied with the permissions configuration. You can cause monotone to listen on all interfaces on port 1234 by leaving out the address part like --bind=:1234.
When he's satisfied the server is set up correctly, Jim does an initial sync with the new database, filling it with all the revision history currently on his laptop. While Jim has been busy setting up the server, Abe and Beth have kept working; the server will catch up with their latest changes when they next sync, too.
All of the team members now want to sync with the new monotone server by default. Previously, they had been syncing with Jim's laptop by default, even if they occasionally specified another team-member's server on the command line when Jim was away, because monotone had remembered the first server and branch patterns used in database Vars. These vars can be seen as follows:
$ mtn list vars database: default-exclude-pattern database: default-include-pattern jp.co.juicebot.jb7* database: default-server jim-laptop.juicebot.co.jp known-servers: jim-laptop.juicebot.co.jp 9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c known-servers: abe-laptop.juicebot.co.jp a2bb16a183247af4133621f7f5aefb21a9d13855 known-servers: www.juicebot.co.jp 120a99ch93b4f174432c13d3e3e9f2234aa92612
The team members can reset their local database vars accordingly:
$ mtn set database default-server www.juicebot.co.jp
With their new server, the juicebot team have gained the convenience of a readily available common point of reference for syncs. However, they also know that this is there only as a convenience, and doesn't prevent them working as they did before:
Hopefully, their new server won't ever be down, but sometimes they might be working together while away from ready network access — fixing up the last few issues and finalising presentation materials while travelling to a sales conference, for example. The server will learn of these changes on the next sync.
They now develop a new habit out of courtesy, though — they try not to leave multiple heads and unmerged changes on the server, at least not for long. This saves them from repeating work, and also helps prevent confusion for the beta-testers. When each team member is ready to sync, they develop the habit of doing a pull from the server first. If new revisions were received from the server, they first merge their new revisions with the head(s) from the server, and finally sync to publish their merged changes as one. If the last sync happens to pull in new revisions again from the server, it means someone else has deposited new work at the same time, and another merge and sync would probably be polite.
He does, however, take a copy of the server's private key, so he can restore that if necessary.
jp.co.juicebot.www, and keep a backup of that content too.
Now he can use monotone to work on the website offline, and let other team members add and edit the content; he can also preview changes locally before updating the production content. He keeps a workspace checkout of this content in the webroot on the server, and runs a monotone update in there when he wants to bring the public web site up to date. Later, he'll think about using monotone's Quality Assurance mechanisms and Event Notification Hooks, so that the web server can update itself automatically when appropriate new revisions are received.
In monotone, the important trust consideration is on the signed content, rather than on the replication path by which that content arrived in your database.
This chapter covers slightly less common aspects of using monotone. Some users of monotone will find these helpful, though possibly not all. We assume that you have read through the taxonomy and tutorial, and possibly spent some time playing with the program to familiarize yourself with its operation.
Monotone's database synchronization system is based on a protocol
called netsync. By default, monotone transports this protocol over a
plain TCP connection, but this is not the only transport monotone can
use. It can also transport netsync through SSH, or any program which
can provide a full-duplex connection over stdio.
When a monotone client initiates a push, pull, or sync operation, it parses the first command-line argument as a URI and calls a Lua hook to convert that URI into a connection command. If the Lua hook returns a connection command, monotone spawns the command locally and speaks netsync over a pipe connected to the command's standard I/O handles.
If the Lua hook does not return a connection command, monotone attempts to parse the command-line argument as a TCP address – a hostname with an optional port number – connects a TCP socket the host and port, and speaks netsync over the socket.
By default, monotone understands two URI schemes:
ssh://[user@]hostname[:port]/path/to/db.mtn,
to synchronize between private databases on hosts accessible only
through SSH. (These paths are absolute; to refer to a path relative
to a home directory, use
ssh://host-part/~/relative/path.mtn or
ssh://host-part/~user/relative/path.mtn.)
file:/path/to/db.mtn, to synchronize between local databases.
ssh: and file: are currently not supported on the native
Win32 platform; they are supported on Cygwin and all other platforms.
In the case of SSH URIs, the ssh program must be in your command execution path, either $PATH on Unix-like systems or %PATH% on Windows systems. Monotone will execute ssh as a subprocess, running mtn serve on the other end of the SSH connection. You will need mtn to be in the command execution path of the remote shell environment.
In the case of File URIs, mtn is run locally, so must be in your command execution path.
In both cases, the database specified in the URI needs to exist already, and will be locked for the duration of the synchronization operation. Therefore, it must also be writable, even when monotone isn't going to modify it, as it is the case for pull. Also note that monotone's default transport authentication is disabled over these transports, to reduce the complexity of configuration and eliminate redundant protocol cost.
Additional URI schemes can be supported by customization of the Lua
hooks get_netsync_connect_command and
use_transport_auth. For details on these hooks, see
Netsync Transport Hooks.
Revisions can be specified on the monotone command line, precisely, by entering the entire 40-character hexadecimal sha1 code. This can be cumbersome, so monotone also allows a more general syntax called “selectors” which is less precise but more “human friendly”. Any command which expects a precise revision ID can also accept a selector in its place; in fact a revision ID is just a special type of selector which is very precise.
Some selector examples are helpful in clarifying the idea:
a432a432
graydon@pobox.com/2004-04graydon@pobox.com in April 2004.
"jrh@example.org/2 weeks ago"jrh@example.org 2 weeks ago.
graydon/net.venge.monotone.win32/yesterdaynet.venge.monotone.win32 branch, written by
graydon, yesterday.
A moment's examination reveals that these specifications are “fuzzy” and indeed may return multiple values, or may be ambiguous. When ambiguity arises, monotone will inform you that more detail is required, and list various possibilities. The precise specification of selectors follows.
A selector is a combination of a selector type, which is a single
ASCII character, followed by a : character and a selector
string. All selectors strings except for selector type c
are just values. The value is matched against identifiers or certs,
depending on its type, in an attempt to match a single revision.
Selectors are matched as prefixes. The current set of selection
types are:
c. The selector string has the syntax
name or name=value. The former syntax will
select any revision that has a cert with that name, regardless of
value; the latter will match any revision that has a cert with that
name and value. Values to match for can have shell wildcards. For
example, c:tag matches all revisions that have a tag, and
c:tag=monotone-0.25 will match the revision tagged
monotone-0.25. (See also the t selector below.)
a. For example, a:graydon matches
author certs where the cert value contains graydon.
b. For example, b:net.venge.monotone matches
branch certs where the cert value is net.venge.monotone.
Values to match for can have shell wildcards. If you give a bare b:
monotone will require you to be in a workspace, and will use the branch
value recorded in your _MTN/options file.
h. For example, h:net.venge.monotone matches
branch certs where the cert value is net.venge.monotone and
the associated revision is a head revision on that branch. Values to match
for can have shell wildcards like the branch selector. If you give a bare
h: monotone will require you to be in a workspace, and use the branch
recorded in your _MTN/options file.
d. For example, d:2004-04 matches
date certs where the cert value begins with
2004-04. This selector also accepts expanded date syntax (see below).
m. For example m:*foobar* matches
changelog and comment certs where the cert value
contains the glob *foobar*.
e. For example, e:2004-04-25 matches
date certs where the cert value is less or equal than
2004-04-25T00:00:00. If the time component is unspecified,
monotone will assume 00:00:00. This selector also accepts expanded date
syntax (see below)
l. For example, l:2004-04-25 matches
date certs where the cert value is strictly greater than
2004-04-25T00:00:00. If the time component is unspecified,
monotone will assume 00:00:00. This selector also accepts expanded date
syntax (see below)
i. For example, i:0f3a matches
revision IDs which begin with 0f3a.
p. For example, p:0f3a matches the
revision IDs which are the parent of the revision ID which begins with
0f3a. If you give a bare p:, monotone will require you to be in
a workspace, and query the parent of the base workspace revision.
u. This selector must be used from within a
workspace and must not have any associated value. It matches the base
revision ID of the workspace before the last update command
was executed. This can be useful for reviewing incoming
revisions. After each update operation, or at least before the next
update operation, run a command similar to the following:
$ mtn log --to u: --diffs
to log all revisions back to the last update. It can also be used for quickly jumping between two different revisions. For example, the following command:
$ mtn update -r u:
will update back to the previous update revision. Repeating this
command will swap the current and previous update revision.
t. For example, t:monotone-0.11 matches
tag certs where the cert value begins with monotone-0.11.
Values to match for can have shell wildcards.
w. This selector must be used from within a
workspace and must not have any associated value. It matches the base
revision ID(s) this workspace is based on.
Further selector types may be added in the future.
Selectors may be combined with the / character. The combination
acts as database intersection (or logical and). For example,
the selector a:graydon/d:2004-04 can be used to select a
revision which has an author cert beginning with graydon
as well as a date cert beginning with 2004-04. The
/ character can be escaped using the \ character if necessary.
Before selectors are passed to the database, they are expanded using a
Lua hook: expand_selector. The default definition of this hook
attempts to guess a number of common forms for selection, allowing you
to omit selector types in many cases. For example, the hook guesses
that the typeless selector jrh@example.org is an author
selector, due to its syntactic form, so modifies it to read
a:jrh@example.org. This hook will generally assign a selector
type to values which “look like” partial hex strings, email
addresses, branch names, or date specifications. For the complete
source code of the hook, see Hook Reference.
All date-related selectors (d, e, l) support an
English-like syntax similar to CVS. This syntax is expanded to the
numeric format by a Lua hook: expand_date.
The allowed date formats are:
nowtodaye and l selectors assume time 00:00:00
yesterdaye and l selectors assume
time 00:00:00
<number> {minute|hour} <ago>number of
minutes|hours.
<number> {day|week|month|year} <ago>number of
days|weeks|months|years. e and l selectors assume time
00:00:00
<year>-<month>[-day[Thour:minute:second]]e and l selectors assume the first
day of month and time 00:00:00.
The time component, if supplied, must be complete to the second.
For the complete source code of the hook, see Hook Reference.
If, after expansion, a selector still has no type, it is matched as a
special “unknown” selector type, which will match either a tag, an
author, or a branch. This costs slightly more database access, but
often permits simple selection using an author's login name and a
date. For example, the selector
graydon/net.venge.monotone.win32/yesterday would pass through
the selector graydon as an unknown selector; so long as there
are no branches or tags beginning with the string graydon this
is just as effective as specifying a:graydon.
Several monotone commands accept optional pathname... arguments in order to establish a “restriction”. Restrictions are used to limit the files and directories these commands examine for changes when comparing the workspace to the revision it is based on. Restricting a command to a specified set of files or directories simply ignores changes to files or directories not included by the restriction.
The following commands all support restrictions using optional pathname... arguments:
Including either the old or new name of a renamed file or directory will cause both names to be included in a restriction. If in doubt, the status command can be used to “test” a set of pathnames to ensure that the expected files are included or excluded by a restriction.
Commands which support restrictions also support the --depth=n option, where n specifies the maximum number of directories to descend. For example, n=0 disables recursion, n=1 means descend at most one directory, and so on.
The update command does not allow for updates to a restricted set of files, which may be slightly different than other version control systems. Partial updates don't really make sense in monotone, as they would leave the workspace based on a revision that doesn't exist in the database, starting an entirely new line of development.
The restrictions facility also allows commands to operate from within a subdirectory of the workspace. By default, the entire workspace is always examined for changes. However, specifying an explicit "." pathname to a command will restrict it to the current subdirectory. Note that this is quite different from other version control systems and may seem somewhat surprising.
The expectation is that requiring a single "." to restrict to the current subdirectory should be simple to use. While the alternative, defaulting to restricting to the current subdirectory, would require a somewhat complicated ../../.. sequence to remove the restriction and operate on the whole tree.
This default was chosen because monotone versions whole project trees and generally expects to commit all changes in the workspace as a single atomic unit. Other version control systems often version individual files or directories and may not support atomic commits at all.
When working from within a subdirectory of the workspace all paths specified to monotone commands must be relative to the current subdirectory.
Monotone only stores a single _MTN directory at the root of a workspace. Because of this, a search is done to find the _MTN directory in case a command is executed from within a subdirectory of a workspace. Before a command is executed, the search for a workspace directory is done by traversing parent directories until an _MTN directory is found or the filesystem root is reached. Upon finding an _MTN directory, the _MTN/options file is read for default options. The --root option may be used to stop the search early, before reaching the root of the physical filesystem. The --no-workspace option may be used to prevent the search entirely.
Many monotone commands don't require a workspace and will simply proceed with no default options if no _MTN directory is found. However, some monotone commands do require a workspace and will fail if no _MTN directory can be found.
The checkout, clone and setup commands create a new workspace and initialize a new _MTN/options file based on their current option settings.
People often want to write programs that call monotone — for example, to create a graphical interface to monotone's functionality, or to automate some task. For most programs, if you want to do this sort of thing, you just call the command line interface, and do some sort of parsing of the output. Monotone's output, however, is designed for humans: it's localized, it tries to prompt the user with helpful information depending on their request, if it detects that something unusual is happening it may give different output in an attempt to make this clear to the user, and so on. As a result, it is not particularly suitable for programs to parse.
Rather than trying to design output to work for both humans and computers, and serving neither audience well, we elected to create a separate interface to make programmatically extracting information from monotone easier. The command line interface has a command automate; this command has subcommands that print various sorts of information on standard output, in simple, consistent, and easily parseable form.
For details of this interface, see Automation.
Fairly often, in order to accomplish its job, monotone has to look at your workspace and figure out what has been changed in it since your last commit. Commands that do this include status, diff, update, commit, and others. There are two different techniques it can use to do this. The default, which is sufficient for most projects, is to simply read every file in the workspace, compute their sha1 hash, and compare them to the hashes monotone has stored. This is very safe and reliable, and turns out to be fast enough for most projects. However, on very large projects, ones whose source trees are many megabytes in size, it can become unacceptably slow.
The other technique, known as inodeprints, is designed for this situation. When running in inodeprints mode, monotone does not read the whole workspace; rather, it keeps a cache of interesting information about each file (its size, its last modification time, and so on), and skips reading any file for which these values have not changed. This is inherently somewhat less safe, and, as mentioned above, unnecessary for most projects, so it is disabled by default.
If you do determine that it is necessary to use inodeprints with your project, it is simple to enable them. Simply run mtn refresh_inodeprints; this will enable inodeprints mode and generate an initial cache. If you ever wish to turn them off again, simply delete the file _MTN/inodeprints. You can at any time delete or truncate the _MTN/inodeprints file; monotone uses it only as a cache and will continue to operate correctly.
Normally, instead of enabling this up on a per-workspace basis, you
will want to simply define the use_inodeprints hook to return
true; this will automatically enable inodeprints mode in any new
workspaces you create. See Hook Reference for details.
Several different types of conflicts may be encountered when merging two revisions using the database merge commands merge, explicit_merge, propagate and merge_into_dir or when using the workspace merge commands update, pluck and merge_into_workspace.
The show_conflicts and automate show_conflicts commands can be used to list conflicts between database revisions which would be encountered by the database merge commands. Unfortunately, these commands can't yet list conflicts between a database revision and the current workspace.
In addition, the conflicts set of commands can be used to specify resolutions for some conflicts. The resolutions are stored in a file, and given to the merge command via the --resolve-conflicts-file=filename or --resolve-conflicts option; see See Conflicts.
The merge command normally will perform as many merges as necessary to merge all current heads of a branch. However, when --resolve-conflicts-file is given, the conflicts and their resolutions apply only to the first merge, so the subsequent merges are not done; the merge command must be repeated, possibly with new conflicts and resolutions, to merge the remaining heads.
If conflicts supports resolving a particular conflict, that is the simplest way to resolve it. Otherwise, resolving the different types of conflicts is accomplished by checking out one of the conflicting revisions, making changes as described below, committing these changes as a new revision and then running the merge again using this new revision as one of the merge parents. This process can be repeated as necessary to get two revisions into a state where they will merge cleanly, or with a minimum of file content conflicts.
The possible conflict resolutions are discussed with each conflict in the following sections.
Monotone versions both files and directories explicitly and it tracks individual file and directory identity from birth to death so that name changes throughout the full life-cycle can be tracked exactly. Partly because of these qualities, monotone also notices several types of conflicts that other version control systems may not.
The two most common conflicts are described first, then all other possible conflicts.
This type of conflict is generally the one encountered most commonly and represents conflicting changes made to lines of text within two versions of a single file.
Monotone does not generally use CVS style conflict markers for content
conflicts. Instead it makes the content of both conflicting files and
the content of their common ancestor available for interactive use
during the merge with your favorite merge tool. See the merge3
hook for more information.
Alternatively, rather than using a merge tool it is possible to make further changes to one or both of the conflicting file versions so that they will merge cleanly. This can also be a very helpful strategy if the merge conflicts are due to sections of text in the file being moved from one location to another. Rather than struggling to merge such conflicting changes with a merge tool, similar rearrangements can be made to one of the conflicting files before redoing the merge.
Finally, you can use your favorite merge tool asychronously with the merge, and specify the result file in the conflicts file, using the conflicts command (see Conflicts):
mtn conflicts resolve_first user filename
A duplicate name conflict occurs when two distinct files or directories have been given the same name in the two merge parents. This can occur when each of the merge parents adds a new file or directory with the conflicting name, or when one parent adds a new file or directory with the conflicting name and the other renames an existing file or directory to the conflicting name, or when both parents rename an existing file or directory to the conflicting name.
In earlier versions of monotone (before version 0.39) this type of conflict was referred to as a rename target conflict although it doesn't necessarily have anything to do with renames.
There are two main situations in which duplicate name conflicts occur:
These conflicts are reported when someone tries to merge the two revisions containing the new files.
There are similar conflicts for directories; the process for resolving them is different, because we need to worry about the files in the directories.
For the first case, the conflict is resolved by dropping one file, using conflicts commands. The contents should be manually merged, in case they are slightly different. Typically, a user will have one of the files in their current workspace; the other can be retrieved via automate get_file_of; the revision id is shown in the merge error message.
The process for files can be confusing; here's a detailed example.
Suppose Beth and Abe each commit a new file checkout.sh. When Beth attempts to merge the two heads, she gets a message like:
mtn: 2 heads on branch 'testbranch' mtn: [left] ae94e6677b8e31692c67d98744dccf5fa9ccffe5 mtn: [right] dfdf50b19fb971f502671b0cfa6d15d69a0d04bb mtn: conflict: duplicate name 'checkout.sh' mtn: added as a new file on the left mtn: added as a new file on the right mtn: error: merge failed due to unresolved conflicts
The file labeled right is the file in Beth's workspace. To
start the conflict resolution process, Beth first saves the list of
conflicts:
mtn conflicts store
In order to merge Beth's and Abe's file versions, Beth retrieves a copy of Abe's file:
mtn automate get_file_of checkout.sh \ --revision=ae94e6677b8e31692c67d98744dccf5fa9ccffe5 \ > _MTN/resolutions/checkout.sh-abe
Now Beth manually merges (using her favorite merge tool) checkout.sh and _MTN/resolutions/checkout.sh-abe, leaving the results in _MTN/resolutions/checkout.sh-merge (not in her copy).
Then Beth specifies the conflict resolution, and finishes the merge:
mtn conflicts resolve_first_left drop mtn conflicts resolve_first_right user _MTN/resolutions/checkout.sh-merge mtn merge --resolve-conflicts-file=_MTN/conflicts mtn conflicts clean mtn update
When Abe later syncs and updates, he will get the merged version.
The second case, where two different files accidently have the same name, is resolved by renaming one or both of them.
Suppose Beth and Abe each start working on different thermostat models (say Honeywell and Westinghouse), but they both name the file thermostat. When Beth attempts to merge, she will get the same error message as in the first case. When she retrieves Abe's file, she will see that they should be different files. So she renames her file, merges, and updates:
mtn conflicts store mtn conflicts resolve_first_left rename thermostat-westinghouse mtn conflicts resolve_first_right rename thermostat-honeywell mtn merge --resolve-conflicts-file=_MTN/conflicts mtn conflicts clean mtn update
Now she has her file in thermostat-honeywell, and Abe's in thermostat-westinghouse.
When two directories are given the same name, there are still the two basic approaches to resolving the conflict; drop or rename. However, if a directory is dropped, all the files in it must also be dropped. Therefore, it is almost always better to first rename one of the directories to a temporary name as the conflict resolution, and then deal with the files individually, renaming or merging and dropping each. Then finally drop the temporary directory.
Monotone's merge strategy is sometimes referred to as die-die-die merge, with reference to the fact that when a file or directory is deleted there is no means of resurrecting it. Merging the deletion of a file or directory will always result in that file or directory being deleted.
A missing root conflict occurs when some directory has been moved to the root directory in one of the merge parents and has been deleted in the other merge parent. Because of die-die-die merge the result will not contain the directory that has been moved to the root.
Missing root conflicts should be very rare because it is unlikely that a project's root directory will change. It is even more unlikely that a project's root directory will be changed to some other directory in one merge parent and that this directory will also be deleted in the other merge parent. Even still, a missing root directory conflict can be easily resolved by moving another directory to the root in the merge parent where the root directory was previously changed. Because of die-die-die merge, no change to resolve the conflict can be made to the merge parent that deleted the directory which was moved to the root in the other merge parent.
See the pivot_root command for more information on moving another directory to the project root.
conflicts does not yet support resolving this conflict.
Monotone reserves the name _MTN in a workspace root directory for internal use and treats this name as illegal for a versioned file or directory in the project root. This name is legal for a versioned file or directory as long as it is not in the project root directory.
An invalid name conflict occurs when some directory is moved to the project root in one of the merge parents and a file or directory that exists in this new root directory is renamed to _MTN or a new file or directory is added with the name _MTN to this directory in the other merge parent.
Invalid name conflicts should be very rare because it is unlikely that a project's root directory will change. It is even more unlikely that a project's root directory will change and the new root directory will contain a file or directory named _MTN. Even still, an invalid name conflict can be easily resolved in several different ways. A different root directory can be chosen, the offending _MTN file or directory can be renamed or deleted, or it can be moved to some other subdirectory in the project.
See the pivot_root command for more information on moving another directory to the project root.
conflicts does not yet support resolving this conflict.
A directory loop conflict occurs when one directory is moved under a second in one of the merge parents and the second directory is moved under the first in the other merge parent.
Directory loop conflicts should be rare but can be easily resolved by moving one of the conflicting directories out from under the other.
conflicts does not yet support resolving this conflict.
An orphaned node conflict occurs when a directory and all of its contents are deleted in one of the merge parents and further files or directories are added to this deleted directory, or renamed into it, in the other merge parent.
Orphaned node conflicts do happen occasionally but can be easily resolved by renaming the orphaned files or directories out of the directory that has been deleted and into another directory that exists in both merge parents, or that has been added in the revision containing the orphaned files or directories.
conflicts supports resolving this conflict. However, if the orphaned node is a directory that is not empty, and the desired resolution is 'drop', the user must drop the directory contents and commit before invoking the conflicts commands.
A multiple name conflict occurs when a single file or directory has been renamed to two different names in the two merge parents. Monotone does not allow this and requires that each file and directory has exactly one unique name.
Multiple name conflicts do happen occasionally but can be easily resolved by renaming the conflicting file or directory in one or both of the merge parents so that both agree on the name.
conflicts does not yet support resolving this conflict.
In earlier versions of monotone (those before version 0.39) this type of conflict was referred to as a name conflict.
An attribute conflict occurs when a versioned attribute on a file or directory is set to two different values by the two merge parents or if one of the merge parents changes the attribute's value and the other deletes the attribute entirely.
Attribute conflicts may happen occasionally but can be easily resolved by ensuring that the attribute is set to the same value or is deleted in both of the merge parents. Attributes are not merged using the die-die-die rules and may be resurrected by simply setting their values.
conflicts does not yet support resolving this conflict.
Sometimes when you work on a project, several people make similar changes in parallel. When these changes occur in an existing file that is known to both sides, monotone can merge the edits when the two revisions meet (possibly after getting help to resolve content conflicts). Other kinds of changes cannot be merged so readily, especially ones that involve files in your workspace that are not tracked by monotone.
Workspace collisions can happen for many reasons; some examples include:
These examples describe collisions on update; the same kinds of things can happen with other commands that can bring changes into your workspace, such as checkout, pivot_root or pluck too.
Monotone is careful to avoid hitting such collisions. Before changing the workspace, it will try and detect the possibility of collisions, and the command will fail, warning you about the names that collide. The file content in the database is safe and can be recovered at any time, so monotone is conservative and will refuse to destroy the information in your workspace contents. Furthermore, all workspace-changing commands have an option --move-conflicting-paths, which moves unversioned, but conflicting files and directories from the workspace into a new subdirectory under _MTN/conflicts. This is useful if you want to ensure that an update always succeeds and you just want to move blocking paths out of the way.
However, monotone cannot detect all kinds of failures and collisions in your workspace. For example:
These are all hopefully very rare occurrences. If such a filesystem error does cause a failure part-way during a workspace alteration, monotone will stop immediately rather than risk potentially doing further damage, and your workspace may be left in an incomplete state. If this happens, you will need to resolve the issue and clean up the workspace manually. If you need to do so, understanding how monotone manipulates the workspace is helpful.
When monotone applies renaming changes to the workspace, each file is first detached from the workspace under its old name, then attached under the new name. This is done by moving it to the _MTN/detached directory. Newly added files are created here before being moved into place, too. While inside _MTN/detached, the file or directory is named as a simple integer (these numbers come from monotone's internal identification of the node). If the detached node is a directory, the directory is moved with all of its contents (including unversioned files); this can help identify which directory has been detached.
If a previous workspace alteration failed part-way, the _MTN/detached directory will still exist, and monotone will refuse to attempt another alteration while the workspace is in this inconsistent state. This also acts as a lock against multiple monotone processes performing workspace alterations (but not other programs).
The best way to avoid a messy recovery from such a failure is simply to ensure that you always commit before trying to update (or pluck, etc) other changes from the database into your workspace. This ensures that your current workspace contents are safely stored, and can be retrieved later (such as with revert).
Monotone was constructed to serve both as a version control tool and as a quality assurance tool. The quality assurance features permit users to ignore, or “filter out”, versions which do not meet their criteria for quality. This section describes the way monotone represents and reasons about quality information.
Monotone often views the collection of revisions as a directed graph,
in which revisions are the nodes and changes between revisions are the
edges. We call this the revision graph. The revision graph has a
number of important subgraphs, many of which overlap. For example,
each branch is a subgraph of the revision graph, containing only the
nodes carrying a particular branch cert.
Many of monotone's operations involve searching the revision graph for the ancestors or descendants of a particular revision, or extracting the “heads” of a subgraph, which is the subgraph's set of nodes with no descendants. For example, when you run the update command, monotone searches the subgraph consisting of descendants of the base revision of the current workspace, trying to locate a unique head to update the base revision to.
Monotone's quality assurance mechanisms are mostly based on restricting the subgraph each command operates on. There are two methods used to restrict the subgraph:
branch certificates, you
can require that specific code reviewers have approved of each edge in
the subgraph you focus on.
testresult certificates, you
can require that the endpoints of an update operation have a
certificate asserting that the revision in question passed a certain
test, or testsuite.
The evaluation of trust is done on a cert-by-cert basis by calling a
set of Lua hooks: get_revision_cert_trust,
get_manifest_cert_trust and get_file_cert_trust. These
hooks are only called when a cert has at least one good signature from
a known key, and are passed all the keys which have signed the
cert, as well as the cert's ID, name and value. The hook can then
evaluate the set of signers, as a group, and decide whether to grant
or deny trust to the assertion made by the cert.
The evaluation of testresults is controlled by the
accept_testresult_change hook. This hook is called when
selecting update candidates, and is passed a pair of tables describing
the testresult certs present on the source and proposed
destination of an update. Only if the change in test results are
deemed “acceptable” does monotone actually select an update target
to merge into your workspace.
For details on these hooks, see the Hook Reference.
Every monotone database has a set of vars associated with it. Vars are simple configuration variables that monotone refers to in some circumstances; they are used for configuration that monotone needs to be able to modify itself, and that should be per-database (rather than per-user or per-workspace, both of which are supported by monotonerc scripts). Vars are local to a database, and never transferred by netsync.
A var is a name = value pairing inside a domain. Domains define what the vars inside it are used for; for instance, one domain might contain database-global settings, and particular vars inside it would define things like that database's default netsync server. Another domain might contain key fingerprints for servers that monotone has interacted with in the past, to detect man-in-the-middle attacks; the vars inside this domain would map server names to their fingerprints.
You can set vars with the set command, delete them with the unset command, and see them with the ls vars command. See the documentation for these specific commands for more details.
There are several pre-defined domains that monotone knows about:
databasedefault-exclude-patterndefault-include-patterndefault-serverdelta-directionChanging this value does not affect deltas that have already been stored.
known-serversA monotone workspace consists of control files and non-control files. Each type of file can be versioned or non-versioned. These classifications lead to four groups of files:
Control files contain special content formatted for use by monotone. Versioned files are recorded in a monotone database and have their state tracked as they are modified.
If a control file is versioned, it is considered part of the state of the workspace, and will be recorded as a manifest entry. If a control file is not versioned, it is used to manage the state of the workspace, but it not considered an intrinsic part of it.
Most files you manage with monotone will be versioned non-control files. For example, if you keep source code or documents in a monotone database, they are versioned non-control files. Non-versioned, non-control files in your workspace are generally temporary or junk files, such as backups made by editors or object files made by compilers. Such files are ignored by monotone.
Control files are identified by their names. Non-control files can have any name except the names reserved for control files. The names of control files follow a regular pattern:
The general intention is that versioned control files are things that you may want to edit directly. In comparison, you should never have to edit non-versioned control files directly; monotone should do that for you whenever it is appropriate. However, both are documented here, just in case a situation arises where you need to go “under the hood”.
The following control files are currently used. More control files may be added in the future, but they will follow the patterns given above.
Every workspace has a base revision, which is the revision that was
originally checked out to create that workspace. When the workspace
is committed, the base revision is considered to be the ancestor of
the committed revision.
Every certificate has a name. Some names have meaning which is built
in to monotone, others may be used for customization by a particular
user, site, or community. If you wish to define custom certificates,
you should prefix such certificate names with x-. For example,
if you want to make a certificate describing the existence of security
vulnerabilities in a revision, you might wish to create a certificate
called x-vulnerability. Monotone reserves all names which do
not begin with x- for possible internal use. If an x-
certificate becomes widely used, monotone will likely adopt it as a
reserved cert name and standardize its semantics.
Most reserved certificate names have no meaning yet; some do. Usually monotone is also responsible for generating many of these certs as part of normal operation, such as during a commit. Others will be added explicitly via other commands, like tag or approve.
As well as carrying other information, certs (and combinations of certs)
are useful for identifying revisions with Selectors; in
particular, this is the primary purpose of the tag cert.
The pre-defined, reserved certificate names are:
authorbranchbranch cert
associates a revision with a branch. The revision is said to be “in
the branch” named by the cert. The cert is generated when you commit
a revision, either directly with the commit command or
indirectly with the merge or propagate commands. The
branch certs are read and directly interpreted by many
monotone commands, and play a fundamental role in organizing work in
any monotone database.
changelogcommentcomment will be
shown together with changelog certs by the log command.
datesuspendbranch cert).
This cert is generated by the suspend command. A suspended
revision is removed from the list of head revisions of a branch in most
cases. A branch with all its heads suspended will not appear in the
list of branches. Suspended revisions can still have children, and those
children are in no way affected by the suspend cert on their parent.
tagtestresult0
or 1. It is generated by the testresult command and
represents the results of running a particular test on the underlying
revision. Typically you will make a separate signing key for each test
you intend to run on revisions. This cert influences the
update algorithm.
Some names in monotone are private to your work, such as filenames. Other names are potentially visible outside your project, such as rsa key identifiers or branch names. It is possible that if you choose such names carelessly, you will choose a name which someone else in the world is using, and subsequently you may cause confusion when your work and theirs is received simultaneously by some third party.
We therefore recommend two naming conventions:
graydon@pobox.com.
net.venge.monotone branch, because the
author owns the DNS domain venge.net.
Monotone contains a support for storing persistent attributes on files and directories, generally known as attrs for short. An attr associates a simple name/value pair with a file or directory, and is stored in the manifest. Attrs are first-class versioned data; they can be changed in a workspace, and those changes will be saved when the workspace is committed. The merger knows how to intelligently merge attrs.
The attribute mechanism was originally motivated by the fact that some people like to store executable programs in version control systems, and would like the programs to remain executable when they check out a workspace. For example, the configure shell script commonly shipped with many programs should be executable. Similarly, some people would like to store devices, symbolic links, read-only files, and all manner of extra attributes of a file, not directly related to a file's data content.
Monotone comes with support for some attrs built-in; for instance, if
an executable file is given to mtn add, then it will
automatically mark the new file with a mtn:execute attr, and
when the file is checked out later, the executable bit will be set
automatically. (Of course, if it is checked out on Windows, which
does not support the executable bit, then the executable bit will not
be set. However, monotone will still know that the attr is set, and
Windows users can view and modify the attr like anyone else.)
Attrs in the current workspace can be seen and modified using the mtn attr command; see Workspace. Attrs can also be found by examining any manifest directly.
You can tell monotone to automatically take actions based on these
attributes by defining hooks; see the attr_functions entry in
Hook Reference. Every time your workspace is written to,
monotone will run the corresponding hooks registered for each attr in
your workspace. This way, you can extend the vocabulary of attrs
understood by monotone simply by writing new hooks.
You can make up your own attrs for anything you find useful; the
mechanism is fully general. (If you make up some particularly useful
ones, we may even be interested in adding support to monotone proper.)
We only ask that if you do use custom attrs, you use some prefix for
them besides mtn:; attrs beginning with mtn: are
reserved for monotone's own use.
Monotone has two merging modes, controlled by the manual_merge
attribute.
By default all files are merged in automatic mode, unless the
manual_merge attribute for that file is present and
true.
In automatic mode files are merged without user intervention, using
monotone's internal three-way merging algorithm.
Only if there are conflicts or an ancestor is not available monotone
switches to manual mode, essentially escalating the merging to the user.
When working in manual mode, monotone invokes the merge3 hook
to start an user defined external merge tool.
If the tool terminates without writing the merged file, monotone aborts the
merging, reverting any changes made.
By redefining the aforementioned hooks the user can not only choose a
preferred merge tool, but even select different programs for different
file types. For example, gimp for .png files, OpenOffice.org for
.doc, and so on.
Starting with monotone 0.20, the manual_merge attribute is
automatically set at add time for all “binary” files, i.e. all files
for which the binary_file hook returns true.
Currently, this means all files with extension gif, jpeg, png, bz2, gz
and zip, plus files containing at least one of the following
bytes:
0x00 thru 0x06 0x0E thru 0x1a 0x1c thru 0x1f
The attribute could also be manually forced or removed using the
appropriate monotone commands.
Remember that monotone switches to manual merging even if only one of
the files to be merged has the manual_merge attribute set.
While the state of your database is logically captured in terms of a packet stream, it is sometimes necessary or desirable (especially while monotone is still in active development) to modify the SQL table layout or storage parameters of your version database, or to make backup copies of your database in plain text. These issues are not properly addressed by generating packet streams: instead, you must use migration or dumping commands.
The mtn db migrate command is used to alter the SQL schema of a database. The schema of a monotone database is identified by a special hash of its generating SQL, which is stored in the database's auxiliary tables. Each version of monotone knows which schema version it is able to work with, and it will refuse to operate on databases with different schemas. When you run the migrate command, monotone looks in an internal list of SQL logic which can be used to perform in-place upgrades. It applies entries from this list, in order, attempting to change the database it has into the database it wants. Each step of this migration is checked to ensure no errors occurred and the resulting schema hashes to the intended value. The migration is attempted inside a transaction, so if it fails — for example if the result of migration hashes to an unexpected value — the migration is aborted.
If more drastic changes to the underlying database are made, such as changing the page size of SQLite, or if you simply want to keep a plain text version of your database on hand, the mtn db dump command can produce a plain ASCII SQL statement which generates the state of your database. This dump can later be reloaded using the mtn db load command.
Note that when reloading a dumped database, the schema of the dumped database is included in the dump, so you should not try to init your database before a load.
Monotone is capable of reading CVS files directly and importing them into a database. This feature is still somewhat immature, but moderately large “real world” CVS trees on the order of 1GB have successfully been imported.
Note however that the machine requirements for CVS trees of this size are not trivial: it can take several hours on a modern system to reconstruct the history of such a tree and calculate the millions of cryptographic certificates involved. We recommend experimenting with smaller trees first, to get a feel for the import process.
We will assume certain values for this example which will differ in your case:
example.net in this example.
import@example.net in this example.
wobbler in this example.
wobbler in this example.
Accounting for these differences at your site, the following is an example procedure for importing a CVS repository “from scratch”, and checking the resulting head version of the import out into a workspace:
$ mtn --db=test.mtn db init $ mtn --db=test.mtn genkey import@example.net $ mtn --db=test.mtn --branch=net.example.wobbler cvs_import /usr/local/cvsroot/wobbler $ mtn --db=test.mtn --branch=net.example.wobbler checkout wobber-checkout
Monotone is capable of exporting the contents of a database to
stdout in a form suitable to be piped to git-fast-import(1):
$ mkdir test.git $ cd test.git $ git init $ mtn --db test.mtn git_export | git fast import
While this feature has been tested and verified to some extent with
various “real-world” monotone databases it is important to realize
that translating from one version control system to another can be a
lossy process. Git represents things somewhat differently than
monotone does and cannot fully represent some things that monotone
can. In particular git does not treat directories as first class
objects as monotone does and does not use certificates to represent
author, date, branch and tag values so
some differences are to be expected.
Git separates the concept of committer from the concept of
author while monotone allows multiple author certs. In
an attempt to represent these different concepts the git exporter uses
the value of the author cert as the git author and the
key used to sign the author cert as the git committer. When
there are multiple author certs the git exporter arbitrarily choses
one of them. The full list of monotone certs may be exported in the
git commit message using the --log-certs option described in
GIT.
Monotone author names often look like raw email addresses such as
"user@example.com". These are not considered valid by git
which requires leading `<' and trailing `>' characters around email
addresses and by convention often includes the display name with the
email address such as "User Name <user@example.com>". The git
exporter deals with this difference in several ways:
<unknown> for both the author and committer.
Branch names used by monotone are allowed to contain characters that are not considered valid by git. These may be mapped to other names using the --branches-file option described in GIT
A monotone revision may have multiple changelog certs and
multiple comment certs. The git exporter deals with these by
first concatenating all of the changelog certs followed by all of the
comment certs into one message to use as the git commit
message. Duplicate changelog or comment cert messages that may exist
due to automated merges are removed.
Exporting a database may be a time consuming and involved process, depending on the size and nature of the database. A 200MB database should export in less than an hour but may take several hours or longer depending on factors such as hardware, revision sizes, roster sizes and many others. The monotone process exporting such a database should require less than 200MB of RAM but may require considerably more in some cases. If the exported file is written to disk it will likely be substantially larger than the associated database, perhaps between 400MB to 4GB in size.
Anyone using the git exporter must take full responsibility for verifying that the exported repository matches their expectations and requirements.
Suppose you made changes to your database, and want to send those changes to someone else but for some reason you cannot use netsync. Or maybe you want to extract and inject individual revisions automatically via an external program. In this case, you can convert the information into packets. Packets are a convenient way to represent revisions and other database contents as plain text with wrapped lines – just what you need if you want to send them in the body of an email.
This is a tutorial on how to transfer single revisions between databases by dumping them from one database to a text file and then reading the dump into a second database.
We will create two databases, A and B, then create a few revisions in A, and transfer part of them to B.
First we initialize the databases:
$ mtn -d A db init $ mtn -d B db init
Now set up a branch in A:
$ mtn -d A setup -b test test
And let's put some revisions in that branch:
$ cd test/ $ cat > file xyz ^D $ mtn add file $ mtn ci -m "One" You may need to select a key and type a passphrase here $ cat > file2 file 2 getting in ^D $ cat > file ERASE ^D $ mtn add file2 $ mtn ci -m "Two" $ cat > file THIRD ^D $ mtn ci -m "Three"
OK, that's enough. Let's see what we have:
$ cd .. $ mtn -d A automate select i: | mtn -d A automate toposort - a423db0ad651c74e41ab2529eca6f17513ccf714 d14e89582ad9030e1eb62f563c8721be02ca0b65 151f1fb125f19ebe11eb8bfe3a5798fcbea4e736
Three revisions! Let's transfer the first one to the database B. First we get the meta-information on that revision:
$ mtn -d A automate get_revision a423db0ad651c74e41ab2529eca6f17513ccf714 format_version "1" new_manifest [b6dbdbbe0e7f41e44d9b72f9fe29b1f1a4f47f18] old_revision [] add_dir "" add_file "file" content [8714e0ef31edb00e33683f575274379955b3526c]
OK, one file was added in this revision. We'll transfer it. Now, ORDER MATTERS! We should transfer:
In that order. This is because certs make reference to release data, and release data makes reference to file data and file deltas.
mtn -d A automate packet_for_fdata 8714e0ef31edb00e33683f575274379955b3526c > PACKETS mtn -d A automate packet_for_rdata a423db0ad651c74e41ab2529eca6f17513ccf714 >> PACKETS mtn -d A automate packets_for_certs a423db0ad651c74e41ab2529eca6f17513ccf714 >> PACKETS mtn -d B read < PACKETS
This revision (a423db0ad651c74e41ab2529eca6f17513ccf714) was already sent to database B. You may want to check the PACKETS file to see what the packets look like.
Now let's transfer one more revision:
mtn -d A automate get_revision d14e89582ad9030e1eb62f563c8721be02ca0b65 format_version "1" new_manifest [48a03530005d46ed9c31c8f83ad96c4fa22b8b28] old_revision [a423db0ad651c74e41ab2529eca6f17513ccf714] add_file "file2" content [d2178687226560032947c1deacb39d16a16ea5c6] patch "file" from [8714e0ef31edb00e33683f575274379955b3526c] to [8b52d96d4fab6c1e56d6364b0a2673f4111b228e]
From what we see, in this revision we have one new file and one patch, so we do the same we did before for them:
mtn -d A automate packet_for_fdata d2178687226560032947c1deacb39d16a16ea5c6 > PACKETS2 mtn -d A automate packet_for_fdelta 8714e0ef31edb00e33683f575274379955b3526c 8b52d96d4fab6c1e56d6364b0a2673f4111b228e >> PACKETS2 mtn -d A automate packet_for_rdata d14e89582ad9030e1eb62f563c8721be02ca0b65 >> PACKETS2 mtn -d A automate packets_for_certs d14e89582ad9030e1eb62f563c8721be02ca0b65 >> PACKETS2 mtn -d B read < PACKETS2
Fine. The two revisions should be in the second database now. Let's take a look at what's in each database:
$ mtn -d A automate select i: | mtn -d A automate toposort - a423db0ad651c74e41ab2529eca6f17513ccf714 d14e89582ad9030e1eb62f563c8721be02ca0b65 151f1fb125f19ebe11eb8bfe3a5798fcbea4e736 $ mtn -d B automate select i: | mtn -d B automate toposort - a423db0ad651c74e41ab2529eca6f17513ccf714 d14e89582ad9030e1eb62f563c8721be02ca0b65
Good! B has the two first revisions (as expected), and A has all three. However, a checkout
of that branch on B will not work, because the certificate signatures cannot be verified.
We need to transfer the signatures too (suppose the key used had the ID "johndoe@domain.com"):
mtn -d A pubkey johndoe@domain.com > KEY_PACKETS mtn -d B read < KEY_PACKETS
Done.
$ mtn -d B co -b test test-B $ ls test-B file2 _MTN x $ more test-B/file2 file 2 getting in
And that's it! The revisions were successfully transferred.
Bisecting is an efficient means of finding the earliest revision that introduced a bug known to exist in some later revision. Given a set of “good” earlier revisions that do not contain the bug and a set of “bad” later revisions that do contain the bug bisect performs a binary search over the set of revisions between these two sets to identify the specific revision that introduced the bug.
Bisection is started by marking revisions with the bisect good and bisect bad commands. Once both good and bad revisions have been specified the set of candidate revisions between the good and bad revisions is determined. The midpoint of this set is selected as the next revision to be tested and the workspace is updated to this selected revision. After the selected revision has been tested bisection continues when the revision is marked with bisect good or bisect bad. If the selected revision is marked as good, it and all of its ancestors are considered to be good and excluded from the remaining search set. If the selected revision is marked as bad, all of its descendants are considered to be bad and excluded from the remaining search set. After each selected revision is marked as good or bad the size of the remaining search set is halved.
Revisions that are untestable for some reason (e.g. they don't compile) may be ignored with the bisect skip command. This excludes the specified revisions from the candidate set and allows the bisection operation to continue. Skipping revisions may cause the search to fail or end on the wrong revision if the revision being searched for is skipped.
If the workspace is updated to some unrelated revision during a bisection operation the bisect update command can be used to update back to the next revision selected for bisection. This command can also be used if a previous bisect good, bisect bad or bisect skip command fails to update the workspace due to the existence of conflicting unversioned paths.
The current status of the bisection operation and the next revision to be tested is reported by the bisect status command. This command can be run at any stage of the bisection operation to see how many revisions remain to be tested and how many revisions have been ruled out.
Currently bisect updates the workspace but does not update the workspace branch option. This may leave the workspace at a revision that is not in the branch specified by the workspace branch option and cause subsequent commits to be made to the wrong branch. To help avoid this error the status command will indicate when the workspace branch does not match any of the parent revision branches. Take care when committing new revisions during a bisection operation and be sure to use the bisect reset command once the bisection is complete to update the workspace back to the revision from which the bisection started.
The bisection operation completes successfully when the last remaining revision is marked as “bad”. If the last remaining revision is marked as “good” the bisection fails without finding the initial bad revision.
Once bisection is complete the workspace can be updated back to the starting revision with the bisect reset command. This command also removes all stored bisection information in preparation for future bisect operations.
This chapter translates common CVS commands into monotone commands. It is an easy alternative to reading through the complete command reference.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
$ 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.
Monotone has a large number of commands. To help navigate through them all, commands are grouped into logical categories.
Without a --revision argument, the command outputs the contents of path as found in the current revision. This requires the command be executed from within a workspace.
With an explicit --revision argument, the command outputs
contents of path at that revision.
dir ""
file "Makefile"
content [84e2c30a2571bd627918deee1e6613d34e64a29e]
file "include/hello.h"
content [c61af2e67eb9b81e46357bb3c409a9a53a7cdfc6]
file "src/hello.c"
content [97dfc6fd4f486df95868d85b4b81197014ae2a84]
Then the following files are created:
directory/
directory/Makefile
directory/include/hello.h
directory/src/hello.c
If you wish to checkout in the current directory, you can supply the special name . (a single period) for directory. When running checkout into an existing directory, it is sometimes possible for Workspace Collisions to occur.
If no id is provided, as in the latter two commands, you
must provide a branchname; monotone will attempt to infer
id as the unique head of branchname if it exists.
Conceptually, disapproves contract is that disapprove(A) gives a revision B such that whenever B is merged with a descendant D of A the merge will result in what D “would have looked like” if A had never happened.
Note that as a consequence of this contract the disapprove command
only works if id has exactly one ancestor, since it hasn't been
worked out how to generate such a descendant in the multi-ancestor case.
The “heads” of a branch is the set of revisions which are members of
the branch, but which have no descendants. These revisions are
generally the “newest” revisions committed by you or your
colleagues, at least in terms of ancestry. The heads of a branch may
not be the newest revisions, in terms of time, but synchronization of
computer clocks is not reliable, so monotone usually ignores time.
A commit message may be provided. A message stating the revision ids that were merged will be prepended to any user commit message.
Merging is performed by repeated pairwise merges: two heads are
selected, then their least common ancestor is located in the ancestry
graph and these 3 revisions are provided to the built-in 3-way merge
algorithm. The process then repeats for each additional head, using
the result of each previous merge as an input to the next.
A commit message may be provided. A message stating the source and target branches will be prepended to any user commit message.
The purpose of propagate is to copy all the changes on
sourcebranch, since the last propagate, to
destbranch. This command supports the idea of making separate
branches for medium-length development activities, such as
maintenance branches for stable software releases, trivial bug fix
branches, public contribution branches, or branches devoted to the
development of a single module within a larger project.
The purpose of merge_into_dir is to permit a project to contain another project in such a way that propagate can be used to keep the contained project up-to-date. It is meant to replace the use of nested checkouts in many circumstances.
Note that merge_into_dir does not permit changes made to the
contained project in destbranch to be propagated back to
sourcebranch. Attempting this would lead to sourcebranch containing
both projects nested as in destbranch instead of only the project
originally in sourcebranch, which is almost certainly not what would be
intended.
If the given branch doesn't exist, it is created automatically. If the branch already exists, any missing files are dropped and any unknown files are added before committing.
If --dry-run is given, no commit is done.
Roughly speaking, mtn import does the following:
$ mtn setup (with a twist)
$ mtn drop --missing
$ mtn add --unknown
$ mtn commit
The twist with the mtn setup part is that it sets the parent to be the given revision or the head of the given branch instead of the null revision.
The conflicts set of commands is used to specify conflict resolutions for merges, asynchronously from the merge command itself. This lets the user take as much time as needed to prepare all the conflict resolutions, and avoids losing work when a merge is aborted due to a complicated conflict.
These commands require a workspace, to provide a place to store the conflicts and user resolution files.
For all of these commands, if the --conflicts-file option is not given, the file _MTN/conflicts is used. If the --conflicts-file option is given, the file must be in the bookkeeping directory.
Files given in these commands are relative to the current working directory, or absolute. In the conflict file, they are relative to the workspace root, or absolute.
If left_rev_id and right_rev_id are not given, the first two heads that the merge command would merge are used.
The conflicts file format is as output by the automate show_conflicts command; see See Automation.
Content conflicts that can be resolved by the internal line merger
have resolutions, so they will not show up in subsequent
show_first commands.
For single file conflicts, there are several possible resolutions:
merge3 hook is called to allow the user to manually
merge the left and right files, leaving the result in the specified file.
file must be a bookkeeping path; under _MTN.
This inserts a resolved_user file conflict resolution in the
conflicts file.
This inserts a resolved_user file conflict resolution in the
conflicts file.
This inserts a resolved_drop_left conflict resolution in the
conflicts file.
This inserts a resolved_rename_left filename conflict resolution in the conflicts file.
For two file conflicts, the possible resolutions are:
This inserts a resolved_drop_left or resolved_drop_right
conflict resolution in the conflicts file.
This inserts a resolved_keep_left or resolved_keep_right
conflict resolution in the conflicts file.
This inserts a resolved_rename_left filename or
resolved_rename_right filename conflict resolution in the
conflicts file.
This inserts a resolved_user_left file or resolved_user_right file conflict resolution in the conflicts file.
monotone internals note: we don't provide an interactive
resolution for two-file conflicts, because monotone currently does not
provide a merge2 Lua hook. two-file conflicts don't have a
shared ancestor, so merge3 is not applicable.
This can be used with an empty directory to start a new blank project,
or within an existing directory full of files, prior to using
mtn commit. If no directory is specified, the current
directory is used.
As a convenience, the --unknown option can be used; this option will cause all of the files listed by mtn list unknown to be added.
While this command places an “add” entry on your work list, it does not immediately affect your database. When you commit your workspace, monotone will use the work list to build a new revision, which it will then commit to the database. The new revision will have any added entries inserted in its manifest.
Adding directories, whether explicitly or using the --unknown
option, is non-recursive by default. The add command can be
made recursive using the --recursive option. When adding a
directory non-recursively, monotone will warn if the directory has
any files that would be added by a recursive add.
While this command places a “drop” entry on your work list, it does not immediately affect your database. When you commit your workspace, monotone will use the work list to build a new revision, which it will then commit to the database. The new revision will have any dropped entries removed from its manifest.
There are situations in which drop will tell monotone
to remove the file from the revision at commit time, but where it will
not to remove the file from the workspace immediately. One
is if the --bookkeep-only option is supplied. Another is
if a file has un-committed changes or if a directory is not empty.
For each edited file, a delta is copied into the database. Then the newly constructed manifest is recorded (as a delta) and finally the new revision. Once all these objects are recorded in you database, commit updates _MTN/revision to indicate that the base revision is now the newly created revision, and that there are no pathname changes to apply.
Specifying pathnames to commit restricts the set of changes that are visible and results in only a partial commit of the workspace. Changes to files not included in the specified set of pathnames will be ignored and will remain in the workspace until they are included in a future commit. With a partial commit, only the relevant entries in _MTN/revision will be removed and other entries will remain for future commits.
From within a subdirectory of the workspace the commit command will, by default, include all changes in the workspace. Specifying only the pathname "." will restrict commit to files changed within the current subdirectory of the workspace.
The --message and --message-file options are mutually exclusive. Both provide a logmsg describing the commit. --message-file actually specifies the name of the file containing the log message, while --message provides it directly.
Multiple --message options may be provided on the command line. The log message will be formed by concatenating the --message options provided, with each one starting at the beginning of a new line.
The _MTN/log file can be edited by the user during their daily
work to record the changes made to the workspace. When running the
commit command without a logmsg supplied, the contents of
the _MTN/log file will be read and passed to the Lua hook
edit_comment as a second parameter named user_log_content.
The log message will be prepended with a 'magic' string that must be
removed to confirm the commit. This allows the user to easily cancel a
commit, without emptying the entire log message. If the commit is
successful, the _MTN/log file is cleared of all content making it
ready for another edit/commit cycle.
If --message-file=_MTN/log is specified, the contents of _MTN/log will be used without confirmation.
If a --branch option is specified, the commit command commits to this branch (creating it if necessary). The branch becomes the new default branch of the workspace.
The commit command also synthesizes a number of certificates, which it attaches to the new manifest version and copies into your database:
author cert, indicating the person responsible for the changes
leading to the new revision. Normally this defaults to your signing key
or the return value of the get_author hook; you may override this
by passing the --author option to commit. This is useful when
committing a patch on behalf of someone else, or when importing “by
hand” from another version control system.
branch cert, indicating the branch the committed revision
belongs to.
date cert, indicating when the new revision was created.
Normally this defaults to the current time; you may override this by
passing the --date option to commit. This is useful when
importing “by hand” from another version control system.
changelog cert, containing the “log message” for these
changes. If you provided logmsg on the command line, this text
will be used, otherwise commit will run the Lua hook
edit_comment (commentary, user_log_content), which
typically invokes an external editor program, in which you can compose
and/or review your log message for the change.
If the flag --missing is given it reverts (ie, restores) any
files which monotone has listed in its manifest, but which have been
deleted from the workspace. Only missing files matching the given
file or directory arguments are reverted.
With an explicit --revision argument, the command uses that revision as the update target instead of finding an acceptable candidate.
The effect is always to take whatever changes you have made in the workspace, and to “transpose” them onto a new revision, using monotone's 3-way merge algorithm to achieve good results. Note that with the explicit --revision argument, it is possible to update “backwards” or “sideways” in history — for example, reverting to an earlier revision, or if your branch has two heads, updating to the other. In all cases, the end result will be whatever revision you specified, with your local changes (and only your local changes) applied.
If a --branch option is specified, the update command tries to select the revision to update to from this branch. The branch becomes the new default branch of the workspace (even if you also specify an explicit --revision argument).
When running update, it is sometimes possible for
Workspace Collisions to occur.
If only one revision is given, applies the changes made in to as compared with to's parent. If two revisions are given, applies the changes made to get from from to to.
Note that this is not a true cherrypick operation. A true cherrypick, as that word is used in version control theory, involves applying some changes out of context, and then recording the identity between the original changes and the newly applied changes for the use of later merges. This command does the first part, not the second. As far as monotone is concerned, the changes made by mtn pluck are exactly like those made in an editor; the command is simply a convenient way to make certain edits quickly. In practice, this is rarely a problem. mtn pluck should almost always be used between branches that will never be merged — for instance, backporting fixes from a development branch to a stable branch.
When you use pluck you are going behind monotone's back, and reducing its ability to help you keep track of what has happened in your history. Never use pluck where a true merging command like merge, propagate, or explicit_merge will do. If you find yourself using pluck often, you should consider carefully whether there is any way to change your workflow to reduce your need for plucking.
When running pluck, it is sometimes possible for
Workspace Collisions to occur.
Its effect is to rename the directory whose name is currently new_root to become the root directory of the versioned tree, and to at the same time rename the directory that is currently the root of the versioned tree to have the name put_old. Conceptually, it is equivalent to executing the following commands in the root of the workspace:
$ mtn rename . new_root/put_old
$ mtn rename new_root .
Except, of course, that these rename commands are illegal, because after the first command the tree has no root at all, and there is a directory loop. This illegality is the only reason for pivot_root's existence; internally, the result is treated exactly like two renames, including with respect to merges and updates.
The use of --bookkeep-only with this command is not recommended. It causes the changes to be made in monotone's records, but not in the filesystem itself.
When running pivot_root, it is sometimes possible for
Workspace Collisions to occur.
If the update is blocked by conflicting unversioned paths existing in
the workspace this command may be re-issued with the
--move-conflicting-paths option. Alternatively, the
bisect update command can be used with this option to update
the workspace and move the conflicting paths out of the way.
If the update is blocked by conflicting unversioned paths existing in
the workspace this command may be re-issued with the
--move-conflicting-paths option. Alternatively, the
bisect update command can be used with this option to update
the workspace and move the conflicting paths out of the way.
If the update is blocked by conflicting unversioned paths existing in
the workspace this command may be re-issued with the
--move-conflicting-paths option. Alternatively, the
bisect update command can be used with this option to update
the workspace and move the conflicting paths out of the way.
The network address given to serve as an argument to --bind should be a host name to listen on, optionally followed by a colon and a port number. The default port number is 4691. If no --bind option is given, the server listens on port 4691 of every network interface.
If serve is run with --stdio, a single netsync
session is served over the stdin and stdout file
descriptors. If --no-transport-auth is provided along with
--stdio, transport authentication and access control mechanisms
are disabled. Only use --no-transport-auth if you are certain
that the transport channel in use already provides sufficient
authentication and authorization facilities.
The uri-or-address arguments given to push, pull, and sync can be of two possible forms. If the argument is a URI, a Lua hook may transform the URI into a connection command, and execute the command as a transport channel for netsync. If the argument is a simple hostname (with optional port number), monotone will use a TCP socket to the specified host and port as a transport channel for netsync.
The glob parameters indicate a set of branches to exchange. Multiple glob and --exclude options can be specified; every branch which matches a glob exactly, and does not match an exclude-glob, will be indexed and made available for synchronization.
For example, perhaps Bob and Alice wish to synchronize their
net.venge.monotone.win32 and net.venge.monotone.i18n
branches. Supposing Alice's computer has hostname
alice.someisp.com, then Alice might run:
$ mtn --bind=alice.someisp.com serve
And Bob might run
$ mtn sync alice.someisp.com "net.venge.monotone*"
When the operation completes, all branches matching
net.venge.monotone* will be synchronized between Alice and Bob's
databases.
The pull, push, and sync commands only require you pass address and glob the first time you use one of them; monotone will memorize this use and in the future default to the same server and glob. For instance, if Bob wants to sync with Alice again, he can simply run:
$ mtn sync
Of course, he can still sync with other people and other branches by passing an address or address plus globs on the command line; this will not affect his default affinity for Alice. If you ever do want to change your defaults, simply pass the --set-default option when connecting to the server and branch pattern that you want to make the new default.
In the server, different permissions can be applied to each branch; see
the hooks get_netsync_read_permitted and
get_netsync_write_permitted (see Hook Reference).
If a --pid-file option is specified, the command serve will create the specified file and record the process identifier of the server in the file. This file can then be read to identify specific monotone server processes.
The syntax for patterns is very simple. * matches 0 or more
arbitrary characters. ? matches exactly 1 arbitrary character.
{foo,bar,baz} matches “foo”, or “bar”, or “baz”. These
can be combined arbitrarily. A backslash, \, can be prefixed to
any character, to match exactly that character — this might be useful
in case someone, for some odd reason, decides to put a “*” into their
branch name.
Specifying optional pathname... arguments to the status command restricts the set of changes that are visible and results in only a partial status of the workspace. Changes to files not included in the specified set of pathnames will be ignored.
From within a subdirectory of the workspace the status command
will, by default, include all changes in the workspace.
Specifying only the pathname "." will restrict status to files
changed within the current subdirectory of the workspace.
If --brief is given, the output consists of two lines per revision with the revision ID, the author, the date and the branches (separated with commas). If the --no-graph option is also given the output contains only one line per revision.
If --last=n is given, at most n log entries will be given and log will trace through history in reverse-ancestry order, from newer revisions to older revisions.
If --next=n is given, at most n log entries will be given and log will trace through history in forward-ancestry order, from older revisions to newer revisions. This is useful to review changes that will be applied to the workspace when update is run.
If --from=id is given, log starts tracing through history from the specified revisions, otherwise it starts from the base revision of your workspace. Log will stop when it reaches the end of the revision history or revisions specified by the --to option.
When tracing through history in reverse-ancestry order and --to=id is given, log will stop when it reaches the specified revisions or any of their ancestors or the end of the revision history. When tracing through history in forward-ancestry order log will stop when it reaches the specified revisions or any of their descendants or the end of the revision history.
If --revision=id is given, log will print only the specified revisions.
If both --from and --revision are given only revisions included by both options will be logged. Revisions specified by --revision that are beyond the starting points specified by --from will be excluded.
Additionally, each of the --from, --to and --revision options accept selectors, see Selectors. These can be used in various ways to log interesting revisions. For example:
$ mtn log --revision b:
$ mtn log --revision today
$ mtn log --revision bob
will log all revisions from the current branch, all revisions dated
today and all revisions with bob as the author, respectively.
By default, the log entries for merge nodes are shown. If --no-merges is given, the log entries for these nodes will be excluded.
If --no-files is given, the log output excludes the list of files changed in each revision.
If --no-graph is given, the log output excludes the ASCII revision graph prefix on log output lines.
Specifying --diffs causes the log output to include a unified diff of the changes in each revision.
If one or more files are given, the command will only log the revisions
where those files are changed.
@ or space character and the date field
is truncated to remove the time of day.
If --revs-only is specified, each line of the file is
translated to <revision id>: <line> in the output, where <revision id>
is the revision in which that line of the file was last edited.
file, manifest or
revision IDs depending on which variant is used. For
example, suppose you enter this command and get this result:
$ mtn complete revision fa36
fa36deead87811b0e15208da2853c39d2f6ebe90
fa36b76dd0139177b28b379fe1d56b22342e5306
fa36965ec190bee14c5afcac235f1b8e2239bb2a
Then monotone is telling you that there are 3 revisions it knows
about, in its database, which begin with the 4 hex digits
fa36. This command is intended to be used by programmable
completion systems, such as those in bash and zsh.
The complete command for keys and revisions have a --verbose option. Programmable completion systems can use --verbose output to present users with additional information about each completion option.
For example, verbose output for revision looks like this:
$ mtn complete revision 01f
01f5da490941bee1f0000f0561fc62eabfb2fa23 graydon@dub.net 2003-12-03T03:14:35
01f992577bd8bcdcade0f89e724fd5dc2d2bbe8a kinetik@orcon.nz 2005-05-11T05:19:29
01faad191d8d0474777c70b4d606782942333a78 kinetik@orcon.nz 2005-04-11T04:24:01
With one --revision option, diff will print the difference from the revision id to the current revision in the workspace. If --reverse is given, the order of the diff is reversed.
With two --revision options diff will print the difference from revision id1 to id2, ignoring any workspace.
In all cases, monotone will print a textual summary – identical to
the summary presented by mtn status – of the logical
differences between revisions in lines proceeding the diff. These
lines begin with a single hash mark #, and should be ignored by
a program processing the diff, such as patch.
Specifying pathnames to the diff command restricts the set of changes that are visible and results in only a partial diff between two revisions. Changes to files not included in the specified set of pathnames will be ignored.
From within a subdirectory of the workspace the diff command will, by default, include all changes in the workspace. Specifying only the pathname "." will restrict diff to files changed within the current subdirectory of the workspace.
The output format of diff is controlled by the options --unified, --context, --no-show-encloser, and --external. By default, monotone uses its built-in diff algorithm to produce a listing in “unified diff” format (analogous to running the program diff -u); you can also explicitly request this with --unified. The built-in diff algorithm can also produce “context diff” format (analogous to diff -c), which you request by specifying --context. The short options that diff accepts for these modes, -u and -c, also work.
In either of these modes, monotone prints the name of the top-level code
construct that encloses each “hunk” of changes, unless suppressed with
the --no-show-encloser. The options that
diff accepts for this mode, -p and
--show-c-function, also work. Monotone finds the enclosing
construct by scanning backward from the first changed line in each
hunk for a line that matches a regular expression. The default
regular expression is correct for many programming languages. You can
adjust the expression used with the Lua hook
get_encloser_pattern; Hooks. For the regular expression
syntax, See Regexps.
--unified requests the “unified diff” format, the default. --context requests the “context diff” format (analogous to running the program diff -c). Both of these formats are generated directly by monotone, using its built-in diff algorithm.
Sometimes, you may want more flexibility in output formats; for these
cases, you can use --external, which causes monotone to invoke
an external program to generate the actual output. By default, the
external program is diff, and you can use the option
--diff-args to pass additional arguments controlling
formatting. The actual invocation of diff, default arguments
passed to it, and so on, are controlled by the hook
external_diff; see Hooks for more details.
ok or bad
For example, this command lists the certificates associated with a particular version of monotone itself, in the monotone development branch:
$ mtn list certs 4a96
mtn: expanding partial id '4a96'
mtn: expanded to '4a96a230293456baa9c6e7167cafb3c5b52a8e7f'
-----------------------------------------------------------------
Key : graydon@pobox.com (10b5b36b4a...)
Sig : ok
Name : author
Value : graydon@dub.venge.net
-----------------------------------------------------------------
Key : graydon@pobox.com (10b5b36b4a...)
Sig : ok
Name : branch
Value : monotone
-----------------------------------------------------------------
Key : graydon@pobox.com (10b5b36b4a...)
Sig : ok
Name : date
Value : 2003-10-17T03:20:27
-----------------------------------------------------------------
Key : graydon@pobox.com (10b5b36b4a...)
Sig : ok
Name : changelog
Value : 2003-10-16 graydon hoare <graydon@pobox.com>
:
: * sanity.hh: Add a const version of idx().
: * diff_patch.cc: Change to using idx() everywhere.
: * cert.cc (find_common_ancestor): Rewrite to recursive
: form, stepping over historic merges.
: * tests/t_cross.at: New test for merging merges.
: * testsuite.at: Call t_cross.at.
:
Two or more files are considered duplicates if the sha1 hashes of their
contents are equal.
If pattern is provided, it is used as a glob to limit the keys
listed. Otherwise all keys in your database are listed.
Specifying pathnames to the list known command restricts the set of paths that are searched for manifest files. Files not included in the specified set of pathnames will not be listed.
From within a subdirectory of the workspace the list
known command will, by default, search the entire workspace.
Specifying only the pathname "." will restrict the search for known
files to the current subdirectory of the workspace.
Specifying pathnames to the list unknown command restricts the set of paths that are searched for unknown files. Unknown files not included in the specified set of pathnames will not be listed.
From within a subdirectory of the workspace the list
unknown command will, by default, search the entire workspace.
Specifying only the pathname "." will restrict the search for unknown
files to the current subdirectory of the workspace.
ignore_file
(filename) hook.
Specifying pathnames to the list ignored command restricts the set of paths that are searched for ignored files. Ignored files not included in the specified set of pathnames will not be listed.
From within a subdirectory of the workspace the list
ignored command will, by default, search the entire workspace.
Specifying only the pathname "." will restrict the search for ignored
files to the current subdirectory of the workspace.
Specifying pathnames to the list missing command restricts the set of paths that are searched for missing files. Missing files not included in the specified set of pathnames will not be listed.
From within a subdirectory of the workspace the list
missing command will, by default, search the entire workspace.
Specifying only the pathname "." will restrict the search for missing
files to the current subdirectory of the workspace.
Specifying pathnames to the list changed command restricts the set of paths that are checked for changes. Files not included in the specified set of pathnames will not be listed.
From within a subdirectory of the workspace the list
changed command will, by default, search the entire workspace.
Specifying only the pathname "." will restrict the search for known
files to the current subdirectory of the workspace.
Note that this does not show conflicts due to update commands, since in that case one revision is the workspace.
The private half of the key is stored in an encrypted form, so that anyone
who can read your keystore cannot extract your private key and use it.
You must provide a passphrase for your key when it is generated, which is used
to determine the encryption key. In the future you will need to enter this
passphrase again each time you sign a certificate, which happens every
time you commit to your database. You can tell monotone to
automatically use a certain passphrase for a given key using the
get_passphrase(key_identity), but this significantly
increases the risk of a key compromise on your local computer. Be
careful using this hook.
The public key is stored in the database; the public and private keys are stored in the keystore. This allows copying the database without copying the private key.
The location of the keystore is specified by the --keydir
option; it defaults to the value stored in _MTN/options for
commands executed in a workspace, or to
the system default (~/.monotone/keys on Unix and Cygwin,
%APPDATA%/monotone/keys on native Win32).
get_revision_cert_trust (see Hook Reference). You pass it
a revision ID, a certificate name, a certificate value, and one or more
key IDs or key names, and it will tell you whether, under your current settings,
Monotone would trust a cert on that revision with that value signed by
those keys.
The specified keys mist exist either in your keystore or in the database.
This command is mainly for use in a session script as monotone will automatically add your keys to ssh-agent on first use if it is available. For example the following two examples are equivalent:
$ mtn ssh_agent_add
enter passphrase for key ID [user@example.com]:
$ mtn ci -m"Changed foo to bar"
$ mtn push -k user@example.com
$ mtn ci -m"Changed foo to bar"
enter passphrase for key ID [user@example.com]:
$ mtn push -k user@example.com
In the second example, monotone automatically added the key to ssh-agent, making
entering the passphrase not needed during the push.
$ mtn ssh_agent_export ~/.ssh/id_monotone
enter passphrase for key ID [user@example.com] (1234abcd...):
enter new passphrase for key ID [user@example.com] (1234abcd...):
confirm passphrase for key ID [user@example.com] (1234abcd...):
$ chmod 600 ~/.ssh/id_monotone
$ ssh-agent /bin/bash
$ ssh-add ~/.ssh/id_monotone
Enter passphrase for /home/user/.ssh/id_monotone:
Identity added: /home/user/.ssh/id_monotone (/home/user/.ssh/id_monotone)
$ mtn ci -m"Changed foo to bar"
$ mtn push -k user@example.com
You can also use the --ssh-sign option to control whether ssh-agent will be used for signing. If set to yes, ssh-agent will be used to sign. If your key has not been added to ssh-agent monotone will fall back to its internal signing code and ask you for your password. If set to only, monotone will sign only with ssh-agent. If set to no, monotone will always use its internal signing code even if ssh-agent is running and has your monotone key loaded. If set to check, monotone will sign with both ssh-agent (if your key is loaded into it) and monotone's internal signing code, then compare the results. check will be removed at some future time as it is meant only for testing and will not work with all signing algorithms.
h:branchname.
If certval is provided, it is the value of the certificate.
Otherwise the certificate value is read from stdin.
stdin.
This command is a synonym for mtn cert id tag
tagname.
Monotone can produce and consume data in a convenient, portable form called packets. A packet is a sequence of ASCII text, wrapped at 70-columns and easily sent through email or other transports. If you wish to manually transmit a piece of information – for example a public key – from one monotone database to another, it is often convenient to read and write packets.
Note: earlier versions of monotone queued and replayed packet streams for their networking system. This older networking system has been removed, as the netsync protocol has several properties which make it a superior communication system. However, the packet I/O facility will remain in monotone as a utility for moving individual data items around manually.
rcert packet for each cert in your
database associated with id. These can be used to transport
certificates safely between monotone databases. See Automation
for details of this command.
fdata or rdata packet for
the file, manifest or revision id in your database. These can
be used to transport files or revisions, in their entirety, safely
between monotone databases. See Automation for details of these
commands.
fdelta packet for the differences
between file versions id1 and id2, in your database.
These can be used to transport file differences safely between
monotone databases. See Automation for details of this
command.
keypair or pubkey packet for
the rsa key keyid. These can be used to transport public or
private keys safely between monotone databases.
stdin and stores them
in your database.
Note that when reloading a dumped database, the schema of the dumped
database is included in the dump, so you should not try to
init your database before a load.
If you have important information in your database, you should back up
a copy of it before migrating, in case there is an untrapped error
during migration.
However, it's also nice to notice such problems early, and in rarely used parts of history, while you still have backups. That's what this command is for. It systematically checks the database dbfile to ensure that it is complete and consistent. The following problems are detected:
This command also verifies that the sha1 hash of every file, manifest,
and revision is correct.
There are a number of other caveats with this command:
This section contains subcommands of the mtn automate command,
used for scripting monotone. All give output on stdout; they may
also give useful chatter on stderr, including warnings and error
messages.
1.2
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
The output does not include rev1, rev2, etc., except if
rev2 is itself an ancestor of rev1, then rev2 will be
included in the output.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
The output will include one of the argument revisions only if that revision is
an ancestor of all other revisions given as arguments.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
The output does not include rev1, rev2, etc., except that if
rev2 is itself a descendant of rev1, then rev2 will be
included in the output.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
0c05e8ec9c6af4224672c7cc4c9ef05ae8bdb794
27ebcae50e1814e35274cb89b5031a423c29f95a 5830984dec5c41d994bcadfeab4bf1bf67747b89
4e284617c80bec7da03925062a84f715c1b042bd 27ebcae50e1814e35274cb89b5031a423c29f95a 657c756d24fb65213d59f4ae07e117d830dcc95b
The output as a whole is alphabetically sorted by line; additionally,
the parents within each line are alphabetically sorted.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f
ignore_branch.
net.venge.monotone
net.venge.monotone.win32
If a branch name is ignored by means of the Lua hook
ignore_branch, it is neither printed, nor can it be matched by
a pattern.
tag "monotree-0.1"
revision [8a121346ce2920b6f85df68b3b620de96bd14a8d]
signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib" "net.venge.monotone.contrib.monotree"
tag "monotree-0.2"
revision [5d288b39b49613b0d9dca8ece6b9a42c3773f35b]
signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"
tag "monotree-0.3"
revision [35cff8e8ba14155f5f7ddf7965073f514fd60f61]
signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"
tag "monotree-0.4"
revision [f1afc520474f83c58262896ede027ef77226046e]
signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"
All stanzas are formatted by basic_io. Stanzas are separated by a blank line. Values will be escaped, '\' to '\\' and '"' to '\"'.
Each stanza has exactly the following four entries:
Stanzas are printed in arbitrary order.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
6265ab1312fbe38bdc3aafa92441139cb2b779b0
birth key
path "added"
new_type "file"
fs_type "file"
status "added" "known"
changes "content"
path "attributes_altered"
old_type "file"
new_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "known"
changes "attrs"
path "dropped"
old_type "file"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "dropped"
path "ignored~"
fs_type "file"
status "ignored"
path "missing"
old_type "file"
new_type "file"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "missing"
path "original"
old_type "file"
new_path "renamed"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
path "patched"
old_type "file"
new_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "known"
changes "content"
path "patched_and_attributes_altered"
old_type "file"
new_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "known"
changes "content" "attrs"
path "renamed"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "known"
path "unchanged"
old_type "file"
new_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "known"
path "unknown"
fs_type "file"
status "unknown"
Two files swapped in both the revision manifest and the workspace:
path "original"
old_type "file"
new_path "unchanged"
new_type "file"
old_path "unchanged"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
path "unchanged"
old_type "file"
new_path "original"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
Recorded in the revision manifest that two files were swapped, but they were not actually swapped in the workspace. Thus they both appear as patched:
path "original"
old_type "file"
new_path "unchanged"
new_type "file"
old_path "unchanged"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
changes "content"
path "unchanged"
old_type "file"
new_path "original"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
changes "content"
Rename (in the manifest and the workspace) foo to bar; add (in the manifest and the workspace) new file foo:
path "foo"
old_type "file"
new_path "bar"
new_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "added" "known"
path "bar"
new_type "file"
old_path "foo"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "known"
Rotated files foo -> bar -> baz -> foo (in the manifest and the workspace):
path "foo"
old_type "file"
new_path "bar"
new_type "file"
old_path "baz"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
path "bar"
old_type "file"
new_path "baz"
new_type "file"
old_path "foo"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
path "baz"
old_type "file"
new_path "foo"
new_type "file"
old_path "bar"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
Recorded in the revison manifest the rotation of files foo -> bar -> baz -> foo, but the actual files in the workspace were not moved, so monotone interprets all files as having been patched:
path "foo"
old_type "file"
new_path "bar"
new_type "file"
old_path "baz"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
changes "content"
path "bar"
old_type "file"
new_path "baz"
new_type "file"
old_path "foo"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
changes "content"
path "baz"
old_type "file"
new_path "foo"
new_type "file"
old_path "bar"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "rename_target" "known"
changes "content"
Dropped from the manifest but not removed in the workspace and thus unknown:
path "dropped"
old_type "file"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "dropped" "unknown"
Added in the manifest but not in the workspace, and thus missing:
path "added"
new_type "file"
fs_type "none"
status "added" "missing"
Recorded a rename in the manifest, but not moved in the workspace, and thus unknown source and missing target:
path "original"
old_type "file"
new_path "renamed"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source" "unknown"
path "renamed"
new_type "file"
old_path "original"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "missing"
Moved in the workspace but no rename recorded in the manifest, and thus missing source and unknown target:
path "original"
old_type "file"
new_type "file"
fs_type "none"
status "missing"
path "renamed"
fs_type "file"
status "unknown"
Renamed in the manifest and the workspace and patched:
path "original"
old_type "file"
new_path "renamed"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
path "renamed"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "known"
changes "content"
Renamed and restricted to original or renamed:
path "original"
old_type "file"
new_path "renamed"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
path "renamed"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "known"
changes "content"
Renamed and restricted to original with the --no-corresponding-renames option:
path "original"
old_type "file"
new_path "renamed"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
Renamed and restricted to renamed with the --no-corresponding-renames option:
path "renamed"
new_type "file"
old_path "original"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "known"
changes "content"
File is missing, an unversioned directory is in the way:
path "missing_file"
old_type "file"
new_type "file"
fs_type "directory"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "invalid"
changes "content"
Directory is missing, an unversioned file is in the way:
path "missing_directory"
old_type "directory"
new_type "directory"
fs_type "file"
status "invalid"
Directory source renamed to target, target is missing, an unversioned file is in the way:
path "source"
old_type "directory"
new_path "target"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
path "source/a"
old_type "file"
new_path "target/a"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_source"
path "target"
new_type "directory"
old_path "source"
fs_type "file"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "invalid"
path "target/a"
new_type "file"
old_path "source/a"
fs_type "none"
birth [cb271687054afd3c2b873c8994f206f08fb240d3]
status "rename_target" "missing"
path line, and contains
up to seven lines. The order of the lines is not important, and may
change in future revisions, except that the first line will always be
path.
A file will also be labeled missing if it is in a directory
that is ignored due to a regular expression in .mtn-ignore, but
is also in the revision manifest. A warning is issued in this case.
'key'
the hex-encoded hash of the key used to sign this certificate.
'signature'
a string indicating the status of the signature. Possible
values of this string are:
'ok' : the signature is correct
'bad' : the signature is invalid
'unknown' : signature was made with an unknown key
'name'
the name of this certificate
'value'
the value of this certificate
'trust'
is this certificate trusted by the defined trust metric?
Possible values of this string are:
'trusted' : this certificate is trusted
'untrusted' : this certificate is not trusted
key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
name "author"
value "emile@alumni.reed.edu"
trust "trusted"
key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
name "branch"
value "net.venge.monotone"
trust "trusted"
key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
name "changelog"
value "propagate from branch 'net.venge.monotone.annotate' (head 76a886ef7c8ae12a4bba5fc2bd252557bf863aff)
to branch 'net.venge.monotone' (head 2490479a4e4e99243fead6d627d78291fde592f0)
"
trust "trusted"
key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
name "date"
value "2005-05-20T20:19:25"
trust "trusted"
l6:leavese
l7:parents40:0e3171212f34839c2e3263e7282cdeea22fc5378e
o3:key11:foo@bar.come l4:cert40:0e3171212f34839c2e3263e7282cdeea22fc53783:foo3:bare
[ 'o' <string> <string> [ <string> <string> [ ... ] ] 'e' ]
'l' <string> [ <string> [ ... ] ] 'e'
The input is a series of commands. The command name plus arguments are
provided as 'l' <string> [<string> ...] 'e', where <string> = <size> colon
<data> . This may optionally be preceded by a set of key=value pairs
(command options) as 'o' <string> <string> [<string> <string> ...] 'e', where
strings come in pairs, key followed by value. For flag options that
don't take values, specify the second string as zero length; 0:.
The space between the ending 'e' of one group of strings and the beginning
'l' or 'o' of the next is reserved. Any characters other than whitespace
will cause an error.
format-version: 2
0:m:41:7706a422ccad41621c958affa999b1a1dd644e79
0:l:1:0
...
1:e:38:misuse: key 'test@test' already exists
1:l:1:2
...
2:w:39:skipping file '\' with unsupported name
2:m:144: path ""
old_type "directory"
new_type "directory"
fs_type "directory"
birth [276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f]
status "known"
...
3:t:34:c:certificates;k:keys;r:revisions;
3:t:12:c=0;k=0;r=0;
3:t:13:c#0;k#0;r#64;
3:t:14:c#0;k#0;r#128;
3:t:6:c;k;r;
...
format-version,
which denotes the version of the stdio format used throughout the
session. The original format had no such version output, so our
numbering starts with "2" here.
Headers are separated from each other by single newline character '\n'
and the last is separated from the following output by a pair of newline
characters.
After a command has been issued, one or more packets are returned for it. A packet looks like:
<command number>:<stream>:<size>:<output>
<command number> is a decimal number specifying which command this output
is from. It is 0 for the first command, and increases by one each time.
<stream> is an identifier for which output stream this packet represents,
allowing multiple streams to be multiplexed over the channel. The following
streams are presently defined; more streams may be added later.
m: this stream represents the normal ("main") stdout automate output of
the command, formatted as described in the description for that command.
e: this stream represents any (unstructured) error message data.
Internally, this maps to calls to the E() print macros that would
normally be written by the command to the program's stderr stream, if the
automate sub-command had been called directly rather than via ”'stdio”'.
w: this stream represents any (unstructured) warning message data.
Internally, this maps to calls to the W() print macro that would
normally be written by the command to the program's stderr stream, if the
automate sub-command had been called directly rather than via ”'stdio”'.
p: this stream represents any (unstructured) progress message data.
Internally, this maps to calls to the P() print macro that would
normally be written by the command to the program's stderr stream, if the
automate sub-command had been called directly rather than via ”'stdio”'.
t: this stream represents ticker updates, which may be used
by a user interface to display the progress of a command.
The output for this channel can be described as follows:
<output> ::= <definition><payload><end>
<definition> ::= <shortname> ':' <longname> <eol>
<payload> ::= <total_count><advance>+
<end> ::= <shortname> <eol>
<total_count> ::= <shortname> '=' <count> <eol>
<advance> ::= <shortname> '#' <count> <eol>
<shortname> ::= "\w+"
<longname> ::= "[^;]+"
<count> ::= ['0'-'9']+
<eol> ::= ';'
The definition tells the implementor the short name and long name of any upcoming ticker event. The names and meanings are command-specific and are therefore explained in the sections for the particular commands which support ticker output.
The total_count might be 0 right at the start and can later be changed
to a different number if the command later on knows a more exact value. If
this is the case, this stanza is output again with this new value. A
constant total_count of 0 means that the command may continue to run
for a undefined amount of time until the end stanza appears.
The advance tells the implementor how much work has been done so far.
Finally, the end stanza is printed just before the ticker ends (i.e. the work has been done).
All counts output absolute, raw values; no modulation takes place. It
is usually the case that definition, total_count, advance and
end are output in separate stanzas. It is also possible that two or
more parallel tickers output their stanzas at the same time, in this
case it's ensured that the output does not get intermixed; first
all definitions are output, afterwards all total_counts, and so on.
Note: The ticker format used for stdio is fixed and cannot be selected explicitely via the global --ticker option. However, if you run an automate command outside of stdio you can set a different ticker type, f.e. count, dot or none.
l: this stream marks the termination of a command and all of
its streams and carries the return code of the command in the payload.
A return code "0" stands for success, "1" for an error which occurred within the stdio interface (f.e. syntax errors or missing privileges) before the command is run and finally "2" for any other command-specific error.
<size> is the number of bytes in the output.
<output> is a piece of the output of the command.
Trying to run the automate stdio or automate remote_stdio
sub-commands will exit the particular command with return code "1".
get_passphrase hook is set up locally.
automate commands to be run against a database that is
being used to serve netsync connections.
automate stdio. Note that the commands run with
automate remote_stdio may conform to a different interface_version,
because they are handled by a remote instance of monotone.
There will be some extra chatter on stderr unless --quiet is given.
get_remote_automate_permitted hook has to be
configured to include every command which should be executable over this
interface.
For both, the client and the server, keyboard interaction is disabled,
just as if --non-interactive is specified. Actions which require
operations on password-encrypted private keys will therefor fail unless the
get_passphrase hook is set up locally and / or remotely.
Remote options must be given as a single token, ie
--branch=foo or -bfoo. This is because the local and remote
monotones may not understand exactly the same options (so the local monotone
cannot know if an option given as --branch or -b should be
followed by an argument), and because the server sees this as an
automate remote_stdio connection (so it expects the options to already
be parsed).
automate command to be run against a database that is
being used to serve netsync connections, without having its input and output
encoded as by automate stdio.
The output will be whatever output the remote command generates.
Remote diagnostic messages are written to standard error, prefixed either
with mtn: remote error:, mtn: remote warning: or
mtn: remote message: to make them distinguishable from local
diagnostics. Tickers are not supported over this interface. If you need
remote ticker support, please use automate remote_stdio.
get_remote_automate_permitted hook has to be
configured to include every command which should be executable over this
interface.
Keyboard interaction is disabled on the server, just as if
--non-interactive would have been specified on server startup.
Actions which require operations on password-encrypted private keys will
therefor fail unless a get_passphrase hook is set up remotely.
Note: The linebreaks are not part of the actual format, but have been added for better readability.
0:p:62:doing anonymous pull; use -kKEYNAME if you need authentication
0:p:25:connecting to monotone.ca0:0:p:29:finding items to synchronize:
0:t:34:c:certificates;k:keys;r:revisions;
0:t:12:c=0;k=0;r=0;
0:t:13:c#0;k#0;r#64;
0:t:14:c#0;k#0;r#128;
[...]
0:t:6:c;k;r;
0:t:44:>:bytes in;<:bytes out;c:certs in;r:revs in;
0:t:16:>=0;<=0;c=0;r=0;
0:t:21:>#420;<#1344;c#0;r#0;
0:t:22:>#1165;<#1741;c#0;r#0;
[...]
0:t:24:>#20839;<#14882;c#0;r#1;
0:t:24:>#20839;<#14882;c#3;r#1;
0:t:24:>#20839;<#14882;c#4;r#2;
0:t:24:>#20839;<#14882;c#6;r#2;
0:t:24:>#20863;<#14930;c#8;r#2;
0:t:8:<;>;c;r;
0:p:36:successful exchange with monotone.ca
0:l:1:0
If these commands are run over stdio, the stdio ticker format is used (for a description of this format, check automate stdio).
The following ticker types are printed out during the refinement phase:
c: The number of certs found for an upcoming synchronization
k: The number of keys found for an upcoming synchronization
r: The number of revisions found for an upcoming synchronization
After refinement the actual synchronization between the two nodes start. The ticker stanzas in this phase are the following:
>: The number of incoming bytes
<: The number of outgoing bytes
c: The number of incoming certs (only pull and sync)
C: The number of outgoing certs (only push and sync)
r: The number of incoming revisions (only pull and sync)
R: The number of outgoing revisions (only push and sync)
hash [...] line instead of separate
public_hash [...] and private_hash [...] lines.
name "tbrownaw@gmail.com"
hash [475055ec71ad48f5dfaf875b0fea597b5cbbee64]
public_location "database" "keystore"
private_location "keystore"
format_version "1"
new_manifest [bfe2df785c07bebeb369e537116ab9bb7a4b5e19]
old_revision [429fea55e9e819a046843f618d90674486695745]
patch "ChangeLog"
from [7dc21d3a46c6ecd94685ab21e67b131b32002f12]
to [234513e3838d423b24d5d6c98f70ce995c8bab6e]
patch "std_hooks.lua"
from [0408707bb6b97eae7f8da61af7b35364dbd5a189]
to [d7bd0756c48ace573926197709e53eb24dae5f5f]
All stanzas are formatted by basic_io. Stanzas are separated by a blank line. Values will be escaped, '\' to '\\' and '"' to '\"'.
Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are:
'format_version'
used in case this format ever needs to change.
format: ('format_version', the string "1")
occurs: exactly once
'new_manifest'
represents the new manifest associated with the revision.
format: ('new_manifest', manifest id)
occurs: exactly one
'old_revision'
represents a parent revision.
format: ('old_revision', revision id)
occurs: either one or two times
'delete
represents a file or directory that was deleted.
format: ('delete', path)
occurs: zero or more times
'rename'
represents a file or directory that was renamed.
format: ('rename, old filename), ('to', new filename)
occurs: zero or more times
'add_dir'
represents a directory that was added.
format: ('add_dir, path)
occurs: zero or more times
'add_file'
represents a file that was added.
format: ('add_file', path), ('content', file id)
occurs: zero or more times
'patch'
represents a file that was modified.
format: ('patch', filename), ('from', file id), ('to', file id)
occurs: zero or more times
'clear'
represents an attr that was removed.
format: ('clear', filename), ('attr', attr name)
occurs: zero or more times
'set'
represents an attr whose value was changed.
format: ('set', filename), ('attr', attr name), ('value', attr value)
occurs: zero or more times
These stanzas will always occur in the order listed here; stanzas of
the same type will be sorted by the filename they refer to. The 'delete'
and following stanzas will be grouped under the corresponding 'old_revision'
one.
Options excl and depth work just like in mtn commit.
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
format_version "1"
dir ""
file ".htaccess"
content [e3915658cb464d05f21332e03d30dca5d94fe776]
file "AUTHORS"
content [80d8f3f75c9b517ec462233e155f7dfb93379f67]
file "ChangeLog"
content [fc74a48c7f73eedcbe1ea709755fbe819b29736c]
file "LICENSE"
content [dfac199a7539a404407098a2541b9482279f690d]
file "README"
content [440eec971e7bb61ccbb61634deb2729bb25931cd]
file "TODO"
content [e0ea26c666b37c5f98ccf80cb933d021ee55c593]
file "branch.psp"
content [b28ece354969314ce996f3030569215d685973d6]
file "common.py"
content [1fdb62e05fb2a9338d2c72ddc58de3ab2b3976fe]
file "config.py.example"
content [64cb5898e3a026b4782c343ca4386585e0c3c275]
file "error.psp"
content [7152c3ff110418aca5d23c374ea9fb92a0e98379]
file "fileinbranch.psp"
content [5d8536100fdf51d505b6f20bc9c16aa78d4e86a8]
file "headofbranch.psp"
content [981df124a0b5655a9f78c42504cfa8c6f02b267a]
file "help.psp"
content [a43d0588a69e622b2afc681678c2a5c3b3b1f342]
file "html.py"
content [18a8bffc8729d7bfd71d2e0cb35a1aed1854fa74]
file "index.psp"
content [c621827db187839e1a7c6e51d5f1a7f6e0aa560c]
file "monotone.py"
content [708b61436dce59f47bd07397ce96a1cfabe81970]
file "revision.psp"
content [a02b1c161006840ea8685e461fd07f0e9bb145a3]
file "rss_feed.gif"
content [027515fd4558abf317d54c437b83ec6bc76e3dd8]
file "tags.psp"
content [638140d6823eee5844de37d985773be75707fa25]
file "tarofbranch.psp"
content [be83f459a152ffd49d89d69555f870291bc85311]
file "test.py"
content [e65aace9237833ec775253cfde97f59a0af5bc3d]
attr "mtn:execute" "true"
file "utility.py"
content [fb51955563d64e628e0e67e4acca1a1abc4cd989]
file "viewmtn.css"
content [8d04b3fc352a860b0e3240dcb539c1193705398f]
file "viewmtn.py"
content [7cb5c6b1b1710bf2c0fa41e9631ae43b03424a35]
file "wrapper.py"
content [530290467a99ca65f87b74f653bf462b28c6cda9]
All stanzas are formatted by basic_io. Stanzas are separated by a blank line. Values will be escaped, '\' to '\\' and '"' to '\"'.
Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are:
'format_version'
used in case this format ever needs to change.
format: ('format_version', the string "1")
occurs: exactly once
'dir':
represents a directory. The path "" (the empty string) is used
to represent the root of the tree.
format: ('dir', pathname)
occurs: one or more times
'file':
represents a file.
format: ('file', pathname), ('content', file id)
occurs: zero or more times
In addition, 'dir' and 'file' stanzas may have attr information included. These are appended to the stanza below the basic dir/file information, with one line describing each attr. These lines take the form ('attr', attr name, attr value).
Stanzas are sorted by the path string.
attr "foo" "bar"
state "added"
attr "baz" "bat"
state "dropped"
attr "foobar" "foobat"
state "unchanged"
All stanzas are formatted by basic_io. Stanzas are separated by a blank line and ordered by attribute name. Values will be escaped, '\' to '\\' and '"' to '\"'.
Each attribute stanza also contains another entry which tells the status of attribute. This entry can have one of the following four values:
The status 'changed' can come up if an attribute foo has been dropped and added afterwards with another value, like
$ mtn attr drop file.txt foo ; mtn attr set file.txt foo baz
If an attribute has been dropped, the output will still return the previously set value of the dropped attribute for convenience (obviously this is no longer recorded in the current workspace).
The complete format:
'attr':
represents an attribute.
format: ('attr', key, value), ('state', [unchanged|changed|added|dropped])
occurs: zero or more times
If zero or more revisions are given, the command behaves as follows:
============================================================
--- guitone/res/i18n/guitone_de.ts 9857927823e1d6a0339b531c120dcaadd22d25e9
+++ guitone/res/i18n/guitone_de.ts 0b4715dc296b1955b0707923d45d79ca7769dd3f
@@ -1,6 +1,14 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE TS><TS version="1.1">
<context>
+ <name>AncestryGraph</name>
+ <message>
[...]
If you've downloaded a release, see INSTALL for installation
instructions. If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.
"make html" for docs, or read the .info file and / or man page.
If a revision id is given, the file's contents in that specific revision
are printed. If no revision is given, the workspace's revision is used.
If you've downloaded a release, see INSTALL for installation
instructions. If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.
"make html" for docs, or read the .info file and / or man page.
This command does not just take two file ids, because the revision ids
and paths are needed to check for manual merge and file encoding
attributes.
If you've downloaded a release, see INSTALL for installation
instructions. If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.
"make html" for docs, or read the .info file and / or man page.
net.venge.monotone
hash [...] line instead of separate
public_hash [...] and private_hash [...] lines.
hash [475055ec71ad48f5dfaf875b0fea597b5cbbee64]
given_name "tbrownaw@gmail.com"
local_name "tbrownaw@gmail.com"
public_location "database" "keystore"
private_location "keystore"
hash [3ac4afcd86af28413b0a23b7d22b9401e15027fc]
given_name "tomfa@debian.org"
local_name "tomfa@debian.org"
public_location "database"
hash [115fdc73d87a5e9901d018462b21a1f53eca33a1]
given_name "underwater@fishtank.net"
local_name "underwater@fishtank.net"
public_location "keystore"
private_location "keystore"
get_local_key_name hook.
The keys are ordered by hash value.
[rdata bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed]
H4sIAAAAAAAA/0XQS27DMAwE0L1PIfgArb4kte62NzACg5SoJEBsF7aRurev0UVzgJl5mLas
E+/jU9ftvsymd33Xzfo9Tjzfm267GSgGwVarz6Valx0KtFYwii9VqUFCqJQ5X7puedRx1ef9
r2rwHlSbi+BUSrF4xn1p0RInkmxTbmwREp/BL97LzfQfN56v+rlc+860dZnMED01jhILkURJ
Ul0KPpGN1ueUwDHyiXF66Ywx+2IGD+0Uqg8aCzikAEzZNRXPmJKlkhMxSHuNzrofx/uq2/J4
6njV/bZsu/zMPOlbOY4XJSD5KOrwXGdwpDGdfotZayQHKTAi5fRPqUWKcAMMIQfAjOK0nkfm
6tFacjYgBPV46X4BtlpiNYUBAAA=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
branch
njs@pobox.com
bmV0LnZlbmdlLm1vbm90b25l]
K90i1XHHmaMEMuwbPifFweLThJl0m7jigh2Qq6Z7TBwNJ6IMOjXWCizv73cacZ1CtzxFDVwQ
SlqhNWiPQWxdcMp+Uuo+V8IFMKmvxVSTuVDukLMuNAQqpGL5S+a+tEj68NMq+KLKuL8kAAPc
RoFD7GQlTS35S3RHWA4cnvqn+8U=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
date
njs@pobox.com
MjAwNi0wNC0wOFQxMTo1MDowMA==]
araz9A8x6AlK6m6UhwnhUhk7cdyxeE2nvzj2gwaDvkaBxOq4SN23/wnaPqUXx1Ddn8smzyRY
HN08xloYc0yNChp3wjbqx20REcsTg3XE4rN/sgCbqqw5hVT22a5ZhqkfkDeoeJvan0R0UBax
ngKYo9eLuABNlmFX2onca75JW1E=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
author
njs@pobox.com
bmpzQHBvYm94LmNvbQ==]
BLPOYhgLsAN+w7CwOsv9GfXnG3u7RNF1DTrWdn0AnYE1e+ptgTeMVWUI18H4OGL0B7wm08rv
Pxk/hvsb8fBn1Kf5HDDO2pbjJ0xVzI9+p+TR0y5jJNZlVSTj+nvtPgvK9NzsdooYWnwlWmJv
bOkAzQcZb8NMh8pbQkdHbR5uzMo=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
changelog
njs@pobox.com
MjAwNi0wNC0wOCAgTmF0aGFuaWVsIFNtaXRoICA8bmpzQHBvYm94LmNvbT4KCgkqIG5ldHh4
L3Jlc29sdmVfZ2V0aG9zdGJ5bmFtZS5jeHggKHJlc29sdmVfaG9zdG5hbWUpOiAjaWZkZWYg
b3V0CglXaW4zMi1pbmNvbXBhdGlibGUgZXJyb3IgcmVwb3J0aW5nIGNhbGwuCg==]
Ncl4L/oEPctzVQixTKA6FrLceeHnLiXfeyeFDNmtUFYg9BMUcjWkeyKmaWknLvOcHortxjto
K6pQ9E8S7zI+TpzFAhssg5a///rFL0+2GJU3t6pcHs6LC0Q4tbqzwKd/5+8GwT1gphbM1wm7
KuzKthwqD3pp49GbgTrp8iWMTr0=
[end]
[fdata 229c7f621b65f7e4970ae5aaec993812b9daa1d4]
H4sIAAAAAAAA/z2OO27DMBBEe51ioMaNrJzBpQAjTXKBBTW0CJPcgFw6yO1DCkG62Q/em83j
R9vlRez6naPKzh2CwkipXFBJbO8fn7f7HV4LQq4mMYoFzdMYSnMj1xXY/lnuoHt2kB2hQpst
PREPZhaxvvchskIKkdU6xsXWvQsk76MOUquGVolZmmmh0+xxvf7JZ5jCFXbU4KZ1muYkT+Kw
FOez5q6uLuh9+9eoQawhez3Fp+VtHJNkfMmDHfALzWYfcAgBAAA=
[end]
[fdelta 597049a62d0a2e6af7df0b19f4945ec7d6458727
229c7f621b65f7e4970ae5aaec993812b9daa1d4]
H4sIAAAAAAAA/0WOy0oEMRBF9/mKS2/c9LQg4t5lw+BGf6BIKtNhkpSkKop/b9II7m49OOfu
eHp5dnvEj/SHL0aQ75qFAgcQGmcm5RXKjP3t/eP1ekWUhlTVKGeyJNXNoXU/s27AP8sf7O8D
ZEdSSLd1JMaNKzeysY8ps4Iao4oNjM99eFdQDbMOSldDV8ZC3aSxlxpxufzJF5jANx6oyS2b
c0uhO+OwkpezZhCvK0bf8TVrMLZUo5zi0/I4j4UqPunGA+B+AfHvKEIPAQAA
[end]
content_mark [276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f]
The complete format:
'content_mark'
the hexadecimal id of the revision the content mark is attached to
file "foo"
The complete format:
'file'
the file name corresponding to "file name" (arg 2) in the target revision
domain "database"
entry "default-exclude-pattern" ""
entry "default-include-pattern" "net.venge.monotone*"
entry "default-server" "monotone.ca"
domain "known-servers"
entry "monotone.ca" "3e6f5225bc2fffacbc20c9de37ff2dae1e20892e"
entry "monotone.mtn-host.prjek.net" "a52f85615cb2445989f525bf17a603250381a751"
entry "venge.net" "70a0f283898a18815a83df37c902e5f1492e9aa2"
mtn automate set_db_variable database default-server off.net
mtn automate drop_db_variables known-servers
70a0f283898a18815a83df37c902e5f1492e9aa2
format_version "1"
new_manifest [0000000000000000000000000000000000000004]
old_revision []
add_dir ""
add_file "foo"
content [5bf1fd927dfb8679496a2e6cf00cbe50c1c87145]
4c2c1d846fa561601254200918fba1fd71e6795d
mtn automate cert 4c2c1d846fa561601254200918fba1fd71e6795d author tester@test.net
If no revs are given, they default to the first two heads that would
be chosen by the merge command for the current branch. If no
workspace is present, the branch may be given by the –branch
option.
resolved_user conflict resolution; use resolved_*_left
for single file conflicts. Add resolved_keep_left,
resolved_keep_right resolutions.
directory_loop_created changed to directory_loop.
This is intended to be used before a merge; an external tool can guide the user thru resolving each conflict in turn, then do the merge.
The same file format is output by the conflicts store command, which also allows specifying user conflict resolutions. The file syntax for the resolutions is given here, so an external tool can set them directly.
For more information on conflicts, Merge Conflicts.
Note that this cannot be used to show conflicts that would occur in an
update, since in that case one revision is the workspace.
left [532ab5011ea9e64aa212d4ea52363b1b8133d5ba]
right [b94a03a922c2c281a88d8988db64e76a32edb6a1]
ancestor [ead03530f5fefe50c9010157c42c0ebe18086559]
If there are no conflicts, the ancestor revision is not output, and no conflict stanzas are output.
Attribute changed in both branches, or dropped in one:
conflict attribute
node_type "file"
attr_name "attr1"
ancestor_name "foo"
ancestor_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
left_name "foo"
left_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
left_attr_value "valueX"
right_name "foo"
right_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
right_attr_value "valueZ"
conflict attribute
node_type "file"
attr_name "attr2"
ancestor_name "foo"
ancestor_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
left_name "foo"
left_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
left_attr_value "valueY"
right_name "foo"
right_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
right_attr_state "dropped"
Missing root directory:
conflict missing_root
left_type "pivoted root"
ancestor_name "foo"
right_type "deleted directory"
ancestor_name "foo"
Directory deleted and/or renamed:
conflict orphaned_directory
right_type "deleted directory"
ancestor_name ""
left_type "renamed directory"
ancestor_name ""
left_name "bar"
conflict orphaned_file
right_type "deleted directory"
ancestor_name "foo"
left_type "added file"
left_name "foo/baz"
left_file_id [f5122a7f896cb2dd7ecaa84be89c94ab09c15101]
conflict orphaned_file
right_type "deleted directory"
ancestor_name "foo"
left_type "renamed file"
ancestor_name "bar"
ancestor_file_id [ac4c6d06436632e017bb7d3ea241734e8899f8ce]
left_name "foo/baz"
left_file_id [ac4c6d06436632e017bb7d3ea241734e8899f8ce]
conflict multiple_names
left_type "renamed directory"
ancestor_name ""
left_name "aaa"
right_type "renamed directory"
ancestor_name ""
right_name "bbb"
conflict duplicate_name
left_type "renamed directory"
ancestor_name "foo"
left_name ""
right_type "renamed directory"
ancestor_name "bar"
right_name ""
conflict multiple_names
left_type "renamed directory"
ancestor_name "foo"
left_name "a/foo"
right_type "renamed directory"
ancestor_name "foo"
right_name "b/foo"
Directory loop created:
conflict directory_loop
left_type "renamed directory"
ancestor_name "foo"
left_name "bar/foo"
right_type "renamed directory"
ancestor_name "bar"
right_name "foo/bar"
File content changed (this may be resolvable by the internal line merger), file also renamed:
conflict content
node_type "file"
ancestor_name "bar"
ancestor_file_id [f0ef49fe92167fe2a086588019ffcff7ea561786]
left_name "bar"
left_file_id [08cd878106a93ce2ef036a32499c1432adb3ee0d]
right_name "bar"
right_file_id [0cf419dd93d38b2daaaf1f5e0f3ec647745b9690]
resolved_internal
conflict content
node_type "file"
ancestor_name "foo"
ancestor_file_id [50bf338804db2685a575124c8c8371d06b65c523]
left_name "bar"
left_file_id [f1bb6fff2ad16d67143d89fc374ede7abec5d437]
right_name "baz"
right_file_id [b966b2d35b99e456cb0c55e4573ef0b1b155b4a9]
resolved_internal is a conflict resolution. If the file
contents in the two revs can be successfully merged by the internal
line merger, resolved_internal is output.
File added and/or renamed:
conflict duplicate_name
left_type "added file"
left_name "bar"
left_file_id [ba4637112ee3e55a6106d647d6c4e04a6643f8eb]
right_type "added file"
right_name "bar"
right_file_id [fe6d523f607e2f2fc0f0defad3bda0351a95a337]
conflict duplicate_name
left_type "renamed file"
ancestor_name "foo"
ancestor_file_id [c6864a8456855c48afe83488a47501fe8b94bd57]
left_name "bar"
left_file_id [c6864a8456855c48afe83488a47501fe8b94bd57]
right_type "added file"
right_name "bar"
right_file_id [c809d71002ec57a2f1d10221f05993012a491436]
conflict duplicate_name
left_type "renamed file"
ancestor_name "foo"
ancestor_file_id [918f3642b57a5e2dd13ee874e3dc2518a53ab4b4]
left_name "abc"
left_file_id [918f3642b57a5e2dd13ee874e3dc2518a53ab4b4]
right_type "renamed file"
ancestor_name "bar"
ancestor_file_id [bdf46a521d5f1dd54c31dda15e99ff6b0c80394a]
right_name "abc"
right_file_id [bdf46a521d5f1dd54c31dda15e99ff6b0c80394a]
File renamed to different names:
conflict multiple_names
left_type "renamed file"
ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
left_name "bar"
left_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
right_type "renamed file"
ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
right_name "baz"
right_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
Invalid file name (_MTN in root directory):
conflict invalid_name
left_type "pivoted root"
ancestor_name "foo"
right_type "added directory"
right_name "foo/_MTN"
conflict invalid_name
left_type "pivoted root"
ancestor_name "foo"
right_type "renamed file"
ancestor_name "bad/_MTN"
ancestor_file_id [629d9e5d254241abf4b46f108fb53189e314e41d]
right_name "foo/_MTN"
right_file_id [629d9e5d254241abf4b46f108fb53189e314e41d]
Revisions that don't share a common ancestor:
left [161e426c3b0c3f98d0be225f69d6f893ce8e0442]
right [0e3260f51acd1e98c40666557eb6c0eefeae5f02]
ancestor []
conflict missing_root
conflict duplicate_name
left_type "added directory"
left_name ""
right_type "added directory"
right_name ""
All possible conflict resolutions:
resolved_drop_left
resolved_drop_right
resolved_keep_left
resolved_keep_right
resolved_internal
resolved_rename_left file
resolved_rename_right file
resolved_user_left file
resolved_user_right file
For single file conflicts, the resolved_*_left resolution name is used.
See Conflicts, for more information on conflict resolutions.
Then each conflict is listed in a basic_io stanza. Stanzas are separated by blank lines.
Each conflict stanza starts with a conflict line, and contains
up to eleven lines. The order of the lines is not important, and may
change in future revisions, except that the first line will always be
conflict.
When the conflicts involve files, the file ids are output, so the file
contents can be retrieved efficiently via automate get_file,
to aid in conflict resolution.
Only the resolved_internal conflict resolution is output by
this command; the other conflict resolutions are inserted in a
conflicts file by conflicts resolve_first or an external
tool, and read by merge.
/home/jim/juice
"foo" or
'foo' will not work, but "'foo'" or '"foo"' will.
Complex types are also supported, anything which can be evaluated as valid
Lua expression can be given as input, including nested tables and functions,
like f.e. {1,true,{['func'] = function(...) return ... end }}
function, thread, userdata and lightuserdata are not
serialized, but set to nil in the dump.
Please note that nil values in tables are not printed since Lua does not
distinguish between unset and not existing entries in a table like other
programming languages do.
[1] = "Output";
Two numeric return values:
[1] = 3;
[2] = 4.4;
A nested table:
[1] = {
["bar"] = {
[1] = 1;
[2] = 2;
[3] = 3;
};
};
A callback function:
[1] = nil --[[function]];
,v. Monotone parses them directly and inserts them into your
database. Note that this does not do any revision reconstruction, and
is only useful for debugging.
In normal use, pathname will be a CVS module, though it is possible to point it at a directory within a module as well. Whatever directory you point it at will become the root of monotone's version of the tree.
stdout in a format that can be piped directly to git
fast-import.
The --authors-file option may be used to map monotone author and committer names to different values in a manner similar to that documented in git-svn(1). Mappings are specified in the authors-file as:
loginname = Joe User <user@example.com>
The list of authors that might need to be mapped can be extracted from a monotone database with the following sql query:
$ mtn db execute 'select distinct value from revision_certs where name = "author"'
The list of committers that might need to be mapped can be extracted from a monotone database with the following sql query:
$ mtn db execute 'select distinct keypair from revision_certs' where name = "author"'
The --branches-file option may be used to map monotone branch names to different values. This may be required as monotone allows branch names that are not valid according to git. Branch mappings are specified in the branches-file as:
monotone-branch-name = git-branch-name
Revisions with no author cert will use <unknown> for both the author and the committer. These can be mapped to other values using the authors-file option.
The list of branches that might need to be mapped can be extracted from a monotone database with using the ls branches command:
$ mtn ls branches --ignore-suspend-certs
The --import-marks and --export-marks options are similar to those documented in git-fast-export(1) and git-fast-import(1). These may be used for incremental exports and may also be useful for repository verification. The marks-file is read on startup if --import-marks is specified and all marked revs are excluded from the export. The marks-file is written on completion if --export-marks is specified and will contain marks for all revs that were exported in addition to any marks that were read on startup. It is safe to use the same file for both --import-marks and --export-marks but different files may also be used.
The original monotone revision ids may be included in the exported git commit messages using the --log-revids option. These will appear as:
Monotone-Parent: ...
Monotone-Revision: ...
in the git commit messages and may be useful for repository
verification. Merge revisions with two parents will include two
Monotone-Parent lines.
The original monotone values for author, date,
branch and tag certificates may be included in the
exported git commit messages using the --log-certs
option. These will appear as:
Monotone-Author: ...
Monotone-Date: ...
Monotone-Branch: ...
Monotone-Tag: ...
in the git commit messages and may be useful for repository
verification or maintaining information that is otherwise not
maintained by git. In particular monotone may have several values for
each of these certs and git only represents a single author and
date value.
By default, the values of all changelog and comment certs on a revision are concatenated to form the git commit message for that revision. The --use-one-changelog option will prevent this behaviour and use the value from the first changelog cert encountered. WARNING: this will explicitly lose information in the exported data. Changelog certs have no implicit ordering, one will be selected arbitrarily to be used as the git commit message and all others will be excluded from the exported data. Additionally, all comment certs will be excluded from the exported data.
References to the original monotone branches and tags are exported as
refs/tags/<tag-name> and refs/heads/<branch-name>. In
addition, references to the original monotone revision ids, the root
revisions and the leaf revisions may be exported using
--refs=revs, --refs=roots and --refs=leaves
respectively. These references are exported as
refs/mtn/revs/<id>, refs/mtn/roots/<id> and
refs/mtn/leaves/<id> and may be useful for repository
verification. These additional references should probably not be
maintained after the exported repository has been verified as they
cause considerable clutter in tools like gitk.
Monotone's behavior can be customized and extended by writing hook functions, which are written in the Lua programming language. At certain points in time, when monotone is running, it will call a hook function to help it make a decision or perform some action. If you provide a hook function definition which suits your preferences, monotone will execute it. This way you can modify how monotone behaves.
You can put new definitions for any of these hook functions in a file $HOME/.monotone/monotonerc, or in your workspace in _MTN/monotonerc, both of which will be read every time monotone runs. Definitions in _MTN/monotonerc shadow (override) definitions made in your $HOME/.monotone/monotonerc. You can also tell monotone to interpret extra hook functions from any other file using the --rcfile=file option; hooks defined in files specified on the command-line will shadow hooks from the the automatic files. By specifying --rcfile=directory you can automatically load all the files contained into directory.
Monotone provides some default hooks, see Default hooks for their complete source. When writing new hooks, it may be helpful to reuse some code from the default ones. Since Lua is a lexically scoped language with closures, this can be achieved with the following code:
do
local old_hook = default_hook
function default_hook(arg)
if not old_hook(arg) then
-- do other stuff
end
end
end
Now the default hook is trapped in a variable local to this block, and can only be seen by the new hook. Since in Lua variables default to the global scope, the new hook is seen from inside monotone.
Monotone also makes available to hook writers a number of helper functions exposing functionality not available with standard Lua.
This section documents the existing hook functions and their default definitions.
Some hooks take arguments which are more complex than a simple string or number. Where multiple hooks take the same kind of argument, we generally try to make them take that kind of argument in the same format.
key_identity {
id = "key hash/fingerprint, in hex",
given_name = "name given when creating the key",
name = "local alias of the key"
}
There are a number of hooks that are called when noteworthy events occur, such as commits or new revisions arriving over the network. These hooks can be used to feed the events into external notification systems, such as generating email.
By default, these hooks are undefined, so no special external actions are taken.
note_commit (new_id, revision, certs)Note that since the certs table does not contain cryptographic
or trust information, and only contains one entry per cert name, it is
an incomplete source of information about the committed version. This
hook is only intended as an aid for integrating monotone with informal
commit-notification systems such as mailing lists or news services. It
should not perform any security-critical operations.
note_netsync_start (session_id, my_role, sync_type, remote_host, remote_key, includes, excludes)The other arguments are:
note_netsync_revision_received (new_id, revision, certs, session_id)note_netsync_start and
note_netsync_end. If you're not interested in that type of
tracking, you can ignore that variable entirely.
note_netsync_revision_sent (rev_id, revision, certs, session_id)note_netsync_cert_received (rev_id, key_identity, name, value, session_id)note_netsync_start and
note_netsync_end. If you're not interested in that type of
tracking, you can ignore that variable entirely.
note_netsync_cert_sent (rev_id, key_identity, name, value, session_id)note_netsync_pubkey_received (key_identity, session_id)note_netsync_start and
note_netsync_end. If you're not interested in that type of
tracking, you can ignore that variable entirely.
note_netsync_pubkey_sent (key_identity, session_id)note_netsync_end (session_id, status, bytes_in, bytes_out, certs_in, certs_out, revs_in, revs_out, keys_in, keys_out)status is a three digit integer that tells whether there was an error, and if so what kind of error it was:
In general, 2xx means there was no error, 4xx means there was a permissions
error, and 5xx means there was a protocol error. xx1 means some data may
have been transferred, xx2 means no data was transferred, and xx0 means all
data was transferred.
note_mtn_startup (...) function note_mtn_startup(...)
print("Beginning note_mtn_startup")
for i = 1,arg.n do
print(arg[i])
end
print("Ending note_mtn_startup")
end
These are hooks that can be used to provide smart, context-sensitive default values for a number of parameters the user might otherwise be prompted for.
get_branch_key (branchname)get_netsync_key(server, include, exclude)There is no default definition of this hook. The command-line option
--key=keyname overrides any value returned from this
hook function.
get_default_command_options(command)Note that there is no way to "override" these default options via a given command-line option once they've been set. This is especially true if you specify options with arguments in this hook such as --exclude=path - no subsequent command-line argument or --exclude option argument will be able to replace or remove the already excluded path.
Simple example which enables recursive directory scanning for mtn add by default:
function get_default_command_options(command)
local default_options = {}
if (command[1] == "add") then
table.insert(default_options, "--recursive")
end
return default_options
end
get_passphrase (key_identity)get_local_key_name (key_identity)get_author (branchname, key_identity)author certificates when you commit changes to
branchname with the keypair identity key_identity. Generally
this hook remains undefined, and monotone selects your signing key name
for the author certificate. You can use this hook to override that
choice, if you like.
This hook has no default definition, but a couple of possible definitions might be:
function get_author(branchname, key_identity)
-- Key pair identity ignored.
local user = os.getenv("USER")
local host = os.getenv("HOSTNAME")
if ((user == nil) or (host == nil)) then return nil end
return string.format("%s@%s", user, host)
end
function get_author(branchname, key_identity)
-- Branch name ignored.
if (key_identity.given_name == "joe@example.com") then
return "Joe Random <joe@example.com>"
end
return key_identity
end
edit_comment (commentary, user_log_message)changelog certificate, automatically generated when you commit
changes.
The contents of _MTN/log are read and passed as user_log_message. This allows you to document your changes as you proceed instead of waiting until you are ready to commit. Upon a successful commit, the contents of _MTN/log are erased setting the system up for another edit/commit cycle.
For the default definition of this hook, see Default hooks.
persist_phrase_ok ()true if you want monotone to remember the passphrase of
a private key for the duration of a single command, or false if
you want monotone to prompt you for a passphrase for each certificate
it generates. Since monotone often generates several certificates in
quick succession, unless you are very concerned about security you
probably want this hook to return true.
The default definition of this hook is:
function persist_phrase_ok()
return true
end
use_inodeprints ()true if you want monotone to automatically enable
Inodeprints support in all workspaces. Only affects working
copies created after you modify the hook.
The default definition of this hook is:
function use_inodeprints()
return false
end
ignore_file (filename)true if filename should be ignored while adding,
dropping, or moving files. Otherwise returns false. This is
most important when performing recursive actions on directories, which
may affect multiple files simultaneously.
The default definition of this hook recognises a number of common file
types and extensions for temporary and generated file types that users
typically don't want to track. If the file .mtn-ignore exists,
this hook will read a list of regular expressions from the file, one per
line, and ignore all files matching one of these expressions. For the
default definition of this hook, see Default hooks.
ignore_branch (branchname)true if branchname should be ignored while listing
branches. Otherwise returns false. This hook has no default
definition, therefore the default behavior is to list all branches.
get_date_format_spec ()strftime format specification, which mtn
log and similar commands will use to format dates, unless instructed
otherwise. The default definition returns `"%d %b %Y, %I:%M:%S %p"', which produces output like this: `22 May 2009, 09:06:14 AM'.
These hooks are used when running a netsync server, via mtn serve. They are evaluated by the server for each new connection, based on the certificate used for authentication by the client. Note that a long-running server will need to be restarted in order to reload the hook definitions if the montonerc file is changed.
get_netsync_read_permitted (branch, key_identity)true if a peer authenticated as key key_identity
should be allowed to read from your database certs, revisions,
manifests, and files associated with branch; otherwise false.
The default definition of this hook reads a file read-permissions in
the configuration directory. This file looks like
pattern "net.example.project.{private,security}*"
allow "joe@example.net"
allow "f3f62f86eba204a3ce15174083a53349201993d6"
comment "everyone can read these branches"
pattern "net.example.{public,project}*"
allow "*"
This example allows everyone access to branches net.example.project and
net.example.public and their sub-branches, except for the branches in
net.example.project.security and net.example.project.private,
which are only readable by Joe and Jim.
The file is divided into stanzas of one pattern line followed by any
number of allow and deny lines, and possibly a continue
line. Anything from the unquoted word comment until the next unquoted
word is ignored. A stanza is processed if the argument to
pattern is a glob that matches branch. Any keys with a hash or
local_name that matches an
allow line are given access, and any keys which match a deny line
are denied access. If there is a continue "true" line, then if the key
is not granted or denied access in this stanza the next matching stanza will be
processed. If there is not a continue "true" line, then any key which
has not been given access will be denied access even if it doesn't match any
deny lines. Thus, deny lines are redundant unless there is also a
continue "true" line.
If a client connects anonymously, this hook will be called with a
key_identity of nil.
get_netsync_write_permitted (key_identity)true if a peer authenticated as key key_identity should
be allowed to write into your database certs, revisions, manifests, and
files; otherwise false. The default definition of this hook reads a file
write-permissions in the configuration directory which contains a list
of key hashes or local key names, one per line, which are allowed write access.
The special value
* means to allow access to anyone whose public key we already have.
If a client connects anonymously, it will be unconditionally denied
write access; this hook will not be called with a key_identity
of nil.
Note also that, unlike the equivalent read permission hook, the write
permission hook does not take a branch name as an argument. There
is presently no way to selectively grant write access to different
branches via netsync, for a number of reasons. Contributions in the
database from different authors can be selectively trusted using the
Trust Evaluation Hooks instead.
get_remote_automate_permitted(key_identity, command, options)automate stdio.
When a monotone client initiates a netsync connection, these hooks are called to attempt to parse the host argument provided on the command line. If the hooks fail or return nil, monotone will interpret the host argument as a network name (possibly with a port number) and open a TCP socket.
get_netsync_connect_command (uri, args)uri["scheme"], such as "ssh" or "file"
uri["user"], the name of a remote user
uri["host"], the name or address of a remote host
uri["port"], a network port number
uri["path"], a filesystem path
uri["query"], for additional parameters
uri["fragment"], to describe a sub-location within the remote resource
The args argument is a table containing between 0 and 3 components:
args["include"], the branch pattern to include
args["exclude"], the branch pattern to exclude
args["debug"], whether to run the connection in debug mode
The default definition of this hook follows:
function get_netsync_connect_command(uri, args)
local argv = nil
if uri["scheme"] == "ssh"
and uri["host"]
and uri["path"] then
argv = { "ssh" }
if uri["user"] then
table.insert(argv, "-l")
table.insert(argv, uri["user"])
end
if uri["port"] then
table.insert(argv, "-p")
table.insert(argv, uri["port"])
end
table.insert(argv, uri["host"])
end
if uri["scheme"] == "file" and uri["path"] then
argv = { }
end
if argv then
table.insert(argv, get_mtn_command(uri["host"]))
if args["debug"] then
table.insert(argv, "--debug")
else
table.insert(argv, "--quiet")
end
table.insert(argv, "--db")
table.insert(argv, uri["path"])
table.insert(argv, "serve")
table.insert(argv, "--stdio")
table.insert(argv, "--no-transport-auth")
if args["include"] then
table.insert(argv, args["include"])
end
if args["exclude"] then
table.insert(argv, "--exclude")
table.insert(argv, args["exclude"])
end
end
return argv
end
use_transport_auth (uri)true. The form of
the uri argument is a table, identical to the table provided as
an argument to get_netsync_connect_command.
Note that the return value of this hook must "match" the semantics of
the command returned by get_netsync_connect_command. In
particular, if this hook returns false, the serve
command line arguments passed to the remote end of the connection
should include the --no-transport-auth option. A mismatch
between this hook's return value and the command line returned by
get_netsync_connect_command will cause a communication failure,
as the local and remote monotone processes will have mismatched
authentication assumptions.
function use_transport_auth(uri)
if uri["scheme"] == "ssh"
or uri["scheme"] == "file" then
return false
else
return true
end
end
get_mtn_command(host) function get_mtn_command(host)
return "mtn"
end
Monotone makes heavy use of certs to provide descriptive information about revisions. In many projects, not all developers should have the same privileges, or be trusted for the same purposes (indeed, some signers might be automated robots, with very specific purposes).
These hooks allow the user to configure which signers will be trusted to make which kinds of assertions using certs. Monotone uses these certs when selecting available revisions for commands such as update.
Each user, or even each workspace, can have their own implementation of these hooks, and thus a different filtered view of valid revisions, according to their own preferences and purposes.
get_revision_cert_trust (signers, id, name, val)The default definition of this hook simply returns true, which
corresponds to a form of trust where every key which is defined in
your database is trusted. This is a weak trust setting; you
should change it to something stronger. A possible example of a
stronger trust function (along with a utility function for computing
the intersection of tables) is the following:
function intersection(a,b)
local s={}
local t={}
for k,v in pairs(a) do s[v.name] = 1 end
for k,v in pairs(b) do if s[v] ~= nil then table.insert(t,v) end end
return t
end
function get_revision_cert_trust(signers, id, name, val)
local trusted_signers = { "bob@happyplace.example.com",
"friend@trustedplace.example.com",
"myself@home.example.com" }
local t = intersection(signers, trusted_signers)
if t == nil then return false end
if (name ~= "branch" and table.getn(t) >= 1)
or (name == "branch" and table.getn(t) >= 2)
then
return true
else
return false
end
end
In this example, any revision certificate is trusted if it is signed
by at least one of three “trusted” keys, unless it is an
branch certificate, in which case it must be signed by
two or more trusted keys. This is one way of requiring that
the revision has been approved by an extra “reviewer” who used the
approve command.
accept_testresult_change (old_results, new_results)true if you consider an update from the
version carrying the old_results to the version carrying the
new_results to be acceptable.
The default definition of this hook follows:
function accept_testresult_change(old_results, new_results)
for test,res in pairs(old_results)
do
if res == true and new_results[test] ~= true
then
return false
end
end
return true
end
This definition accepts only those updates which preserve the set of
true test results from update source to target. If no test
results exist, this hook has no affect; but once a true test
result is present, future updates will require it. If you want a more
lenient behavior you must redefine this hook.
Differences between files can be shown in a number of ways, varying according to user preference and file type. These hooks allow customisation of the way file differences are shown.
get_encloser_pattern (file_path)^[[:alnum:]$_], which is correct for many programming
languages; a few text authoring packages, like Texinfo, have special
regular expressions that match their particular syntax. If you have a
better regular expression for some language, you can add it to this
hook; and if you send it to the monotone developers, we will likely
make it the default for that language. See Regexps, for the
regular expression syntax.
external_diff (file_path, old_data, new_data, is_binary, diff_args, old_rev, new_rev)If an extra arguments are given via --diff-args, the string will be passed in as diff_args. Otherwise diff_args will be nil.
The default implementation of this hook calls the program diff,
and if --diff-args were not passed, takes default arguments
from the Lua variable external_diff_default_args. You can
override this variable in your configuration file, without overriding
the whole hook.
Monotone often needs to merge together the work of multiple distributed developers, and uses these hooks to help this process when the merge does not automatically succeed. Often these hooks will be used to invoke an external interactive merge tool.
The Default hooks include helper functions used by the hooks below to invoke a number of external merge tools known to monotone, and you can override or extend these hooks if you have a preferred tool, or if you have a tool specific to certain file types.
merge3 (ancestor_path, left_path, right_path, merged_path, ancestor_text, left_text, right_text)Returns a string, which should be the merger of the given texts. The
default definition of this hook delegates the actual merge to the
result of get_preferred_merge3_command. The default definition
of get_preferred_merge3_command checks to see if the
MTN_MERGE environment variable, or the Lua variable
merger are set to the name of a merge tool that it recognizes,
and if not, then simply searches for whatever is installed on the
local system. For details, see the code in Default hooks.
get_preferred_merge3_command(tbl)Monotone's selectors are a powerful mechanism used to refer to revisions with symbolic names or groupings. Thanks to the hooks described in this section, it is possible to use various forms of shorthand in selection strings; these hooks are designed to recognise shorthand patterns and expand them to their full form.
For more detail on the use of selectors, see Selectors.
expand_selector (str)a: for authors
or d: for dates. This hook is called once for each element of a
combined selector string (between / separators) prior to
evaluation of the selector. For the default definition of this hook, see
Default hooks.
expand_date (str)yesterday or
6 months ago and converting them into well formed date
expressions. For the default definition of this hook, see Default hooks.
Some files in a project are special; they may require different handling (such as binary or structured files that should always be manually merged – see Merging), or they may represent executable scripts or programs.
Monotone allows each file (or directory) in a repository to carry arbitrary File Attributes. Persistent attributes are stored in each revision's manifest. The hooks in this section allow files to be automatically recognised as having certain attributes at the time they're added, and for custom triggers to be invoked on each file according to its attributes when the workspace is changed.
attr_functions [attribute] (filename, value)attr_functions, at table
entry attribute, is a function taking a file name filename
and an attribute value value. The function should “apply” the
attribute to the file, possibly in a platform-specific way. When
called to set an attribute the value this hook receives will be a
string representing the value of the attribute. When called to clear
an attribute the value this hook receives will be nil.
Hook functions from this table are called for each existing attribute, after any command which modifies the workspace. These functions are also called during creation and modification of a workspace by the update, merge_into_workspace, pluck, clone and checkout commands to set or clear attributes as they change.
This facility can be used to extend monotone's understanding of files with platform-specific attributes, such as permission bits, access control lists, or special file types.
By default, there is only one entry in this table, for the mtn:execute
attribute. Its definition is:
attr_functions["mtn:execute"] =
function(filename, value)
if (value == "true") then
set_executable(filename)
else
clear_executable(filename)
end
end
attr_init_functions [attribute] (filename)attr_init_functions, at
table entry attribute, is a function taking a file (or
directory) name filename. Each function defines the attributes
that should be set on the file named filename. This table of
hook functions is called once for each file during an add.
By default, there are only two entries in this table, for the
mtn:execute and mtn:manual_merge attributes. Their
definition is:
attr_init_functions["mtn:execute"] =
function(filename)
if (is_executable(filename)) then
return "true"
else
return nil
end
end
attr_init_functions["mtn:manual_merge"] =
function(filename)
if (binary_file(filename)) then
return "true" -- binary files must be merged manually
else
return nil
end
end
The binary_file function is also defined as a Lua hook. See
Default hooks.
If there is a policy decision to make, Monotone defines certain hooks to allow a client to validate or reject certain behaviors.
validate_commit_message (message, revision_text, branchname)true,
"". If it finds fault, then it can return false, reason where
reason is the reason the message was rejected. By default, this hook
rejects empty log messages.
Monotone allows the execution of arbitrary Lua hooks and functions through a special generalized "meta hook". See automate lua for more information.
hook_wrapper (func_name, ...)This section documents the additional Lua functions made available to hook writers.
alias_command(original, alias)existonpath(possible_command)existonpath("xxdiff") returns 0 if the
program xxdiff is available.
On Windows, this function automatically appends “.exe” to the
program name. In the previous example, existonpath would search
for “xxdiff.exe”.
get_confdir()get_ostype()guess_binary_file_contents(filespec) 0x00 thru 0x06
0x0E thru 0x1a
0x1c thru 0x1f
include(scriptfile)includedir(scriptpath)includedirpattern(scriptpath, pattern)is_executable(filespec)kill(pid [, signal])make_executable(filespec)match(glob, string)mkstemp(template)Important notice:
To create a temporary file, you must use the temp_file()
function, unless you need to run monotone with the --nostd
option. temp_file() builds on mkstemp() and creates a
file in the standard TMP/TEMP directories.
For the definition of temp_file(), see Default hooks.
mtn_automate( ... )mtn_automate Lua function calls the Monotone
automate command passed in its arguments. The result of the
call is a pair consisting of a boolean return code, indicating whether
the call was successful or not, and a string being the stdout
output from the automate command. This function is not for use
in ordinary Lua hooks, but rather for Lua based commands as defined by
the Lua function register_command.
Note that keyboard interaction is disabled, just as if --non-interactive
is specified. Actions which require operations on password-encrypted private
keys will therefor fail unless the get_passphrase hook is set up locally.
parse_basic_io(data)For example, given this as input:
thingy "foo" "bar"
thingy "baz"
spork
frob "oops"
The output table will be:
{
1 = { name = "thingy", values = { 1 = "foo", 2 = "bar" } },
2 = { name = "thingy", values = { 1 = "baz" } },
3 = { name = "spork", values = { } },
4 = { name = "frob", values = { 1 = "oops" } }
}
regex.search(regexp, string)register_command(name, params, abstract, description, function)server_request_sync(what, address, include, exclude)When called by a monotone instance which is not running the serve
command, this function has no effect.
sleep(seconds)spawn(executable [, args ...])Important notice:
To spawn a process and wait for its completion, use the execute()
function, unless you need to run monotone with the --nostd
option. execute() builds on spawn() and wait()
in a standardized way.
spawn_pipe(executable [, args ...])spawn_redirected(infile, outfile, errfile, executable [, args ...])wait(pid)This chapter describes some “special” issues which are not directly related to monotone's use, but which are occasionally of interest to people researching monotone or trying to learn the specifics of how it works. Most users can ignore these sections.
Monotone initially dealt with only ASCII characters, in file path names, certificate names, key names, and packets. Some conservative extensions are provided to permit internationalized use. These extensions can be summarized as follows:
The remainder of this section is a precise specification of monotone's internationalization behavior.
get_charset_conv which takes a filename
and returns a table of two strings: the first represents the
"internal" (database) charset, the second represents the "external"
(file system) charset.
0x2D,
0x30..0x39, 0x41..0x5A, and 0x61..0x7A.
{ACE-prefix}{LDH-sanitized(punycode(nameprep(UTF-8-string)))}
It is important to understand that IDNA encoding does not preserve the input string: it both prohibits a wide variety of possible strings and normalizes non-equal strings to supposedly "equivalent" forms.
By default, monotone does not decode IDNA when printing to the
console (IDNA names are ASCII, which is a subset of UTF-8, so this
normal form conversion can still apply, albeit oddly). this behavior
is to protect users against security problems associated with
malicious use of "similar-looking" characters. If the hook
display_decoded_idna returns true, IDNA names are decoded for
display.
0x5C '\' path separator to 0x2F '/'. This extra
processing is performed by boost::filesystem.
0x2F (ASCII / ), and
without a leading or trailing 0x2F.
0x2F and any ASCII "control codes"
(0x00..0x1F and 0x7F).
UI messages are displayed via calls to gettext().
Host names are read on the command-line and subject to normal form
conversion. Host names are then split at 0x2E (ASCII '.'), each
component is subject to IDNA encoding, and the components are
rejoined.
After processing, host names are stored internally as ASCII. The
invariant is that a host name inside monotone contains only sequences
of LDH separated by 0x2E.
Read on the command line and subject to normal form conversion and IDNA encoding as a single component. The invariant is that a cert name inside monotone is a single LDH ASCII string.
Cert values may be either text or binary, depending on the return
value of the hook cert_is_binary. If binary, the cert value is
never printed to the screen (the literal string "<binary>" is
displayed, instead), and is never subjected to line ending or
character conversion. If text, the cert value is subject to normal
form conversion, as well as having all UTF-8 codes corresponding to
ASCII control codes (0x0..0x1F and 0x7F) prohibited in
the normal form, except 0x0A (ASCII LF).
Read on the command line and subject to normal form conversion and IDNA encoding as a single component. The invariant is that a var domain inside monotone is a single LDH ASCII string.
Var names and values are assumed to be text, and subject to normal form conversion.
Read on the command line and subject to normal form conversion and
IDNA encoding as an email address (split and joined at '.' and '@'
characters). The invariant is that a key name inside monotone contains
only LDH, 0x2E (ASCII '.') and 0x40 (ASCII '@')
characters.
Packets are 7-bit ASCII. The characters permitted in packets are the union of these character sets:
Some proponents of a competing, proprietary version control system have suggested, in a usenix paper, that the use of a cryptographic hash function such as sha1 as an identifier for a version is unacceptably unsafe. This section addresses the argument presented in that paper and describes monotone's additional precautions.
To summarize our position:
The paper displays a fundamental lack of understanding about what a cryptographic hash function is, and how it differs from a normal hash function. Furthermore it confuses accidental collision with attack scenarios, and mixes up its analysis of the risk involved in each. We will try to untangle these issues here.
A cryptographic hash function such as sha1 is more than just a uniform spread of inputs to an output range. Rather, it must be designed to withstand attempts at:
Collision is the problem the paper is concerned with. Formally, an n-bit cryptographic hash should cost 2^n work units to collide against a given value, and sqrt(2^n) tries to find a random pair of colliding values. This latter probability is sometimes called the hash's “birthday paradox probability”.
One way of measuring these bounds is by measuring how single-bit changes in the input affect bits in the hash output. The sha1 hash has a strong avalanche property, which means that flipping any one bit in the input will cause on average half the 160 bits in the output code to change. The fanciful val1 hash presented in the paper does not have such a property — flipping its first bit when all the rest are zero causes no change to any of the 160 output bits — and is completely unsuited for use as a cryptographic hash, regardless of the general shape of its probability distribution.
The paper also suggests that birthday paradox probability cannot be used to measure the chance of accidental sha1 collision on “real inputs”, because birthday paradox probability assumes a uniformly random sample and “real inputs” are not uniformly random. The paper is wrong: the inputs to sha1 are not what is being measured (and in any case can be arbitrarily long); the collision probability being measured is of output space. On output space, the hash is designed to produce uniformly random spread, even given nearly identical inputs. In other words, it is a primary design criterion of such a hash that a birthday paradox probability is a valid approximation of its collision probability.
The paper's characterization of risk when hashing “non-random inputs” is similarly deceptive. It presents a fanciful case of a program which is storing every possible 2kb block in a file system addressed by sha1 (the program is trying to find a sha1 collision). While this scenario will very likely encounter a collision somewhere in the course of storing all such blocks, the paper neglects to mention that we only expect it to collide after storing about 2^80 of the 2^16384 possible such blocks (not to mention the requirements for compute time to search, or disk space to store 2^80 2kb blocks).
Noting that monotone can only store 2^41 bytes in a database, and thus probably some lower number (say 2^32 or so) active rows, we consider such birthday paradox probability well out of practical sight. Perhaps it will be a serious concern when multi-yottabyte hard disks are common.
Setting aside accidental collisions, then, the paper's underlying theme of vulnerability rests on the assertion that someone will break sha1. Breaking a cryptographic hash usually means finding a way to collide it trivially. While we note that sha1 has in fact resisted attempts at breaking for 8 years already, we cannot say that it will last forever. Someone might break it. We can say, however, that finding a way to trivially collide it only changes the resistance to active attack, rather than the behavior of the hash on benign inputs.
Therefore the vulnerability is not that the hash might suddenly cease to address benign blocks well, but merely that additional security precautions might become a requirement to ensure that blocks are benign, rather than malicious. The paper fails to make this distinction, suggesting that a hash becomes “unusable” when it is broken. This is plainly not true, as a number of systems continue to get useful low collision hashing behavior — just not good security behavior — out of “broken” cryptographic hashes such as MD4.
Perhaps our arguments above are unconvincing, or perhaps you are the sort of person who thinks that practice never lines up with theory. Fair enough. Below we present practical procedures you can follow to compensate for the supposed threats presented in the paper.
A successful collision attack on sha1, as mentioned, does not disrupt the probability features of sha1 on benign blocks. So if, at any time, you believe sha1 is “broken”, it does not mean that you cannot use it for your work with monotone. It means, rather, that you cannot base your trust on sha1 values anymore. You must trust who you communicate with.
The way around this is reasonably simple: if you do not trust sha1 to prevent malicious blocks from slipping into your communications, you can always augment it by enclosing your communications in more security, such as tunnels or additional signatures on your email posts. If you choose to do this, you will still have the benefit of self-identifying blocks, you will simply cease to trust such blocks unless they come with additional authentication information.
If in the future sha1 (or, indeed, rsa) becomes accepted as broken we will naturally upgrade monotone to a newer hash or public key scheme, and provide migration commands to recalculate existing databases based on the new algorithm.
Similarly, if you do not trust our vigilance in keeping up to date
with cryptography literature, you can modify monotone to use any
stronger hash you like, at the cost of isolating your own
communications to a group using the modified version. Monotone is free
software, and runs atop botan, so it is both legal and
relatively simple to change it to use some other algorithm.
As described in Historical records, monotone revisions contain the sha1 hashes of their predecessors, which in turn contain the sha1 hashes of their predecessors, and so on until the beginning of history. This means that it is mathematically impossible to modify the history of a revision, without some way to defeat sha1. This is generally a good thing; having immutable history is the point of a version control system, after all, and it turns out to be very important to building a distributed version control system like monotone.
It does have one unfortunate consequence, though. It means that in the rare occasion where one needs to change a historical revision, it will change the sha1 of that revision, which will change the text of its children, which will change their sha1s, and so on; basically the entire history graph will diverge from that point (invalidating all certs in the process).
In practice there are two situations where this might be necessary:
Obviously, we hope neither of these things will happen, and we've taken lots of precautions against the first recurring; but it is better to be prepared.
If either of these events occur, we will provide migration commands and explain how to use them for the situation in question; this much is necessarily somewhat unpredictable. In the past we've used the (now defunct) db rebuild command, and more recently the db rosterify command, for such changes as monotone developed. These commands were used to recreate revisions with new formats. Because the revision id's changed, all the existing certs that you trust also must be reissued, signed with your key.2
While such commands can reconstruct the ancestry graph in your database, there are practical problems which arise when working in a distributed work group. For example, suppose our group consists of the fictional developers Jim and Beth, and they need to rebuild their ancestry graph. Jim performs a rebuild, and sends Beth an email telling her that he has done so, but the email gets caught by Beth's spam filter, she doesn't see it, and she blithely syncs her database with Jim's. This creates a problem: Jim and Beth have combined the pre-rebuild and post-rebuild databases. Their databases now contain two complete, parallel (but possibly overlapping) copies of their project's ancestry. The “bad” old revisions that they were trying to get rid of are still there, mixed up with the “good” new revisions.
To prevent such messy situations, monotone keeps a table of branch epochs in each database. An epoch is just a large bit string associated with a branch. Initially each branch's epoch is zero. Most monotone commands ignore epochs; they are relevant in only two circumstances:
Thus, when a user rebuilds their ancestry graph, they select a new epoch and thus effectively disassociate with the group of colleagues they had previously been communicating with. Other members of that group can then decide whether to follow the rebuild user into a new group — by pulling the newly rebuilt ancestry — or to remain behind in the old group.
In our example, if Jim and Beth have epochs, Jim's rebuild creates a new epoch for their branch, in his database. This causes monotone to reject netsync operations between Jim and Beth; it doesn't matter if Beth loses Jim's email. When she tries to synchronize with him, she receives an error message indicating that the epoch does not match. She must then discuss the matter with Jim and settle on a new course of action — probably pulling Jim's database into a fresh database on Beth's end – before future synchronizations will succeed.
The previous section described the theory and rationale behind rebuilds and epochs. Here we discuss the practical consequences of that discussion.
If you decide you must rebuild your ancestry graph — generally by announcement of a bug from the monotone developers — the first thing to do is get everyone to sync their changes with the central server; if people have unshared changes when the database is rebuilt, they will have trouble sharing them afterwards.
Next, the project should pick a designated person to take down the netsync server, rebuild their database, and put the server back up with the rebuilt ancestry in it. Everybody else should then pull this history into a fresh database, check out again from this database, and continue working as normal.
In complicated situations, where people have private branches, or ancestries cross organizational boundaries, matters are more complex. The basic approach is to do a local rebuild, then after carefully examining the new revision IDs to convince yourself that the rebuilt graph is the same as the upstream subgraph, use the special db epoch commands to force your local epochs to match the upstream ones. (You may also want to do some fiddling with certs, to avoid getting duplicate copies of all of them; if this situation ever arises in real life we'll figure out how exactly that should work.) Be very careful when doing this; you're explicitly telling monotone to let you shoot yourself in the foot, and it will let you.
Fortunately, this process should be extremely rare; with luck, it will never happen at all. But this way we're prepared.
Monotone makes use of the Mark-Merge (also known as *-merge) algorithm. The emails reproduced below document the algorithm. Further information can be found at revctrl.org.
From: Nathaniel Smith <njs <at> pobox.com>
Subject: [cdv-devel] more merging stuff (bit long...)
Newsgroups: gmane.comp.version-control.codeville.devel, gmane.comp.version-control.monotone.devel
Date: 2005-08-06 09:08:09 GMT
I set myself a toy problem a few days ago: is there a really, truly,
right way to merge two heads of an arbitrary DAG, when the object
being merged is as simple as possible: a single scalar value?
I assume that I'm given a graph, and each node in the graph has a
value, and no other annotation; I can add annotations, but they have
to be derived from the values and topology. Oh, and I assume that no
revision has more than 2 parents; probably things can be generalized
to the case of indegree 3 or higher, but it seems like a reasonable
restriction...
So, anyway, here's what I came up with. Perhaps you all can tell me
if it makes sense.
User model
----------
Since the goal was to be "really, truly, right", I had to figure out
what exactly that meant... basically, what I'm calling a "user model"
-- a formal definition of how the user thinks about merging, to give
an operational definition of "should conflict" and "should clean
merge". My rules are these:
1) whenever a user explicitly sets the value, they express a claim
that their setting is superior to the old setting
2) whenever a user chooses to commit a new revision, they implicitly
affirm the validity of the decisions that led to that revision's
parents
Corollary of (1) and (2): whenever a user explicitly sets the
value, they express that they consider their new setting to be
superior to _all_ old settings
3) A "conflict" should occur if, and only if, the settings on each
side of the merge express parallel claims.
This in itself