Below is the file 'monotone.texi' from this revision. You can also download the file.
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename monotone.info
@settitle monotone documentation
@setchapternewpage odd
@finalout
@c %**end of header
@syncodeindex fn cp
@include version.texi
@dircategory Programming
@direntry
* monotone: (monotone). Monotone version control system
@end direntry
@titlepage
@title Monotone
@subtitle A distributed version control system
@author Graydon Hoare and others
@ifnotinfo
@page
@vskip 0pt plus 1filll
@end ifnotinfo
This manual is for the ``monotone'' distributed version control system.
This edition documents version @value{VERSION}.
Copyright @copyright{} 2003, 2004 Graydon Hoare @*
Copyright @copyright{} 2004, 2005, 2006 Nathaniel Smith @*
Copyright @copyright{} 2005, 2008 Derek Scherger @*
Copyright @copyright{} 2005, 2006 Daniel Carosone @*
Copyright @copyright{} 2006 Jeronimo Pellegrini @*
Copyright @copyright{} 2006 Alex Queiroz @*
Copyright @copyright{} 2006, 2007 William Uther @*
Copyright @copyright{} 2006, 2007, 2008 Thomas Keller @*
Copyright @copyright{} 2007, 2008 Stephen Leake @*
This manual is made available under the GNU GPL version 2.0 or
greater. See the accompanying file COPYING for details.
@end titlepage
@ifnottex
@node Top, Concepts, (dir), (dir)
@top Top
Monotone is a distributed version control tool. It can help automate
many tedious and error-prone tasks in group software development.
@itemize
@item
Store multiple versions of files you are working on efficiently.
@item
Transmit changes to files between you and your colleagues.
@item
Merge changes you make with those your colleagues make.
@item
Make notes about your opinion of the quality of versions of files.
@item
Make decisions about using or ignoring versions, depending on the notes
you receive from others.
@end itemize
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.
@end ifnottex
@menu
* Concepts:: Taxonomy of monotone
* Tutorial:: A detailed example of using monotone
* Advanced Uses:: Going beyond the basics
* CVS Phrasebook:: Transitional guide for CVS users
* Command Reference:: Details of each monotone command
* Hook Reference:: Functions which extend monotone
* Special Topics:: Extra explanations and details
* Default hooks:: The standard hook definitions
* General Index:: Index of concepts and functions
@end menu
@ifnottex
Complete table of contents
@end ifnottex
@contents
@node Concepts, Tutorial, Top, Top
@chapter Concepts
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.
@menu
* Versions of files:: Tracking changes to single files
* Versions of trees:: Tracking changes to collections of files
* Historical records:: Tracking the history of changes
* Certificates:: Tracking extended information
* Storage and workflow:: Saving, sending, and receiving changes
* Forks and merges:: Managing divergence of code
* Branches:: Intentional divergence and automatic merging
@end menu
@page
@node Versions of files, Versions of trees, Concepts, Concepts
@section Versions of files
Suppose you wish to modify a file @file{file.txt} on your
computer. You begin with one @i{version} of the file, load it into
an editor, make some changes, and save the file again. Doing so
produces a new @i{version} of the file. We will say that the older
version of the file was a @dfn{parent}, and the new version is a
@dfn{child}, and that you have performed an @dfn{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.
@ifinfo
@smallexample
@group
+----------------+
| |
| parent version |
| of file.txt |
| |
+----------------+
|
|
\|/
V
+----------------+
| |
| child version |
| of file.txt |
| |
+----------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/parent-child}
@end ifnotinfo
We may want to identify the parent and the child precisely, for sake
of reference. To do so, we will compute a @i{cryptographic hash
function}, called @sc{sha1}, of each version. The details of this
function are beyond the scope of this document; in summary, the @sc{sha1}
function takes a version of a file and produces a short string of 20
bytes, which we will use to uniquely identify the version@footnote{We
say @sc{sha1} values are ``unique'' here, when in fact there is a
small probability of two different versions having the same @sc{sha1}
value. This probability is very small, so we discount it.}. 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.
@ifinfo
@smallexample
@group
+---------------------------------------------------+
| parent version |
| of file.txt |
| |
| SHA1 = 65f1bde1f38262034e7c3457301e8f736ba6381b |
+---------------------------------------------------+
|
|
\|/
V
+---------------------------------------------------+
| child version |
| of file.txt |
| |
| SHA1 = a91566316d208dc405795904f8d67ae3a0e765cb |
+---------------------------------------------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/parent-child-names-hashes}
@end ifnotinfo
When dealing with versions of files, we will dispense with writing out
``file names'', and identify versions @i{purely} by their @sc{sha1}
value, which we will also refer to as their @dfn{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.
@ifinfo
@smallexample
@group
+---------------------------------------------------+
| parent version |
| SHA1 = 65f1bde1f38262034e7c3457301e8f736ba6381b |
+---------------------------------------------------+
|
|
\|/
V
+---------------------------------------------------+
| child version |
| SHA1 = a91566316d208dc405795904f8d67ae3a0e765cb |
+---------------------------------------------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/parent-child-hashes}
@end ifnotinfo
Version control systems, such as monotone, are principally concerned
with the storage and management of @i{multiple} versions of some files.
One way to store multiple versions of a file is, literally, to save a
separate @i{complete} copy of the file, every time you make a
change. When necessary, monotone will save complete copies of your
files, compressed with the @code{zlib} compression format.
@ifinfo
@smallexample
@group
+--------------+ +--------------+ +--------------+
| | | | | |
| Hello | | Hello, | | Why, Hello |
| | | world! | | there world, | . . .
| | | | | how do you |
| | | | | do? |
| | | | | |
+--------------+ +--------------+ +--------------+
\______ ______/ \______ ______/ \______ ______/
\/ \/ \/
1st version 2nd version 3rd version
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/three-versions}
@end ifnotinfo
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 @i{complete} copies of each
version of a file, we store a compact description of only the
@i{changes} which are made between versions. Such a description of
changes is called a @dfn{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 @code{xdelta}
format. The details of this format are beyond the scope of this
document.
@ifinfo
@smallexample
@group
difference
between versions
_____/\____
+--------------+ / \ +--------------+
| | | |
| Hello | +[, world!] | Hello, |
| | | world! |
| | | |
| | | |
| | | |
+--------------+ +--------------+
\______ ______/ \______ ______/
\/ \/
1st version 2nd version
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/difference-between-versions}
@end ifnotinfo
@page
@node Versions of trees, Historical records, Versions of files, Concepts
@section Versions of trees
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 @i{trees} in a file system,
we say that you want to capture a @i{version of your tree}. Doing
so will permit you to undo changes to multiple files at once, or send
your friend a @i{set} of changes to many files at once.
To make a snapshot of a tree, we begin by writing a special file called
a @dfn{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.
@ifinfo
@smallexample
@group
+------------------------------------------------------+
| |
| format_version "1" |
| |
| dir "" |
| |
| dir "fs" |
| |
| file "fs/readdir.c" |
| content [f2e5719b975e319c2371c98ed2c7231313fac9b5] |
| |
| file "fs/read_write.c" |
| content [81f0c9a0df254bc8d51bb785713a9f6d0b020b22] |
| |
| file "fs/pipe.c" |
| content [943851e7da46014cb07473b90d55dd5145f24de0] |
| |
| file "fs/inode.c" |
| content [8ddcfcc568f33db6205316d072825d2e5c123275] |
| |
+------------------------------------------------------+
\_________________________ ___________________________/
\/
an example
manifest file
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/manifest}
@end ifnotinfo
Now we note that a manifest is itself a file. Therefore a manifest can
serve as input to the @sc{sha1} function, and thus every manifest has
an ID of its own. By calculating the @sc{sha1} value of a manifest, we
capture the @i{state of our tree} in a single @dfn{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 @i{snapshots} of a tree of files, though
lacking the actual contents of the files themselves.
@ifinfo
@smallexample
@group
+--------------------------+
| int readdir(...) @{ |
| ... |
| @} |
+--------------------------+
\____________ ____________/
\/
SHA1
||
+--------------------------------||--------------------+
| . . . || |
| || |
| file "fs/readdir.c" \/ |
| content [f2e5719b975e319c2371c98ed2c7231313fac9b5] |
| |
| . . .
+------------------------------------------------------+
\_________________________ ___________________________/
\/
SHA1
||
||
\/
manifest ID:
a2eeaa28574141a7d48fa1cc2802070150b93ec4
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/file-id-manifest-id}
@end ifnotinfo
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.
@page
@node Historical records, Certificates, Versions of trees, Concepts
@section Historical records
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 @dfn{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
@dfn{revision} each time you make changes. Like manifests, revisions
are ordinary text files which can be passed through the @sc{sha1}
function and thus assigned a @dfn{revision ID}.
@ifinfo
@smallexample
@group
+-----------------------------------------------------------+
| |
| format_version "1" |
| |
| new_manifest [83bc0a52da351cac950ac1c12d85be494fc21199] |
| |
| old_revision [75c9ffcab50c46e77e642751314b34a16fba36ff] |
| |
| add_file "include/foo.h" |
| content [8ca6a9862bdeddfdb4b12248c075fa9570f45f6d] |
| |
| patch "include/bar.h" |
| from [d624672a03e42d2172e56c4d54924af10ff8518d] |
| to [2f58cfc4791aa1695b76c31c9cd1139b3d79ee1b] |
| |
+-----------------------------------------------------------+
\____________________________ _____________________________/
\/
SHA1
||
\/
revision ID:
1c83997e7ab40c0df47554c81b7d4e7ee691eb0d
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/revision}
@end ifnotinfo
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 @i{other revision IDs}. This fact -- that revisions include
the IDs of other revisions -- causes the set of revisions to join
together into a historical @i{chain of events}, somewhat like a ``linked
list''. Each revision in the chain has a unique ID, which includes
@i{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.
@ifinfo
@smallexample
@group
+-----------------------------------------------------------+
| |
| format_version "1" |
| |
| new_manifest [dbd022dc423fd7f473e0fa79842cd9901cc2dd69] <-- manifest id
| |
| old_revision: [] |
| |
| ... |
| |
+-----------------------------------------------------------+
\____________________________________ _____________________/
\/
SHA1
||
+------------------------------------||---------------------+
| || |
| format_version "1" || |
| || |
| new_manifest [8a05c60422770bbf49a3||2c2367ddaa066538ca] <-- manifest id
| \/ |
| old_revision [f45add3bfb21cb459d99b6a9c0111df75f6d9f85] |
| |
| ... |
| |
+-----------------------------------------------------------+
\____________________________________ _____________________/
\/
SHA1
||
+------------------------------------||---------------------+
| || |
| format_version "1" || |
| || |
| new_manifest [2027b4ab2febf98bd9a0||c000a69a8227cdaaf7] <-- manifest id
| \/ |
| old_revision [1c83997e7ab40c0df47554c81b7d4e7ee691eb0d] |
| |
| ... |
| |
+-----------------------------------------------------------+
\____________________________ _____________________________/
\/
SHA1
||
\/
revision ID:
1c83997e7ab40c0df47554c81b7d4e7ee691eb0d
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/revision-chaining}
@end ifnotinfo
@page
@node Certificates, Storage and workflow, Historical records, Concepts
@section Certificates
Often, you will wish to make a @i{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:
@itemize
@item
an @i{ID}, indicating which revision you are making a statement about
@item
a @i{name} indicating the type of statement you are making, such as
``changelog'', ``date'' or ``testresult''
@item
a @i{value} indicating the remaining detail of the statement, such as
``fixed a bug'', ``March 9th'' or ``1''
@end itemize
For example, if you want to say that a particular revision was
composed on April 4, 2003, you might make a statement like this:
@ifinfo
@smallexample
@group
+------------------------------------------------------+
| revision ID |
| a2eeaa28574141a7d48fa1cc2802070150b93ec4 |
+--------------------------+---------------------------+
| statement name | statement value |
| "date" | "2003-04-04T07:39:51" |
+--------------------------+---------------------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/statement}
@end ifnotinfo
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:
@itemize
@item
a @i{key} which identifies the person making a statement
@item
a @i{signature} --- just a large number with particular properties ---
certifying the fact that the person made the statement
@end itemize
When these 2 items accompany a statement, we call the total bundle of
5 items a @dfn{certificate}, or @i{cert}. A cert makes a statement in
a secure fashion. The security of the signature in a cert is derived
from the @sc{rsa} cryptography system, the details of which are beyond
the scope of this document.
@ifinfo
@smallexample
@group
+------------------------------------------------------+
| revision ID |
| a2eeaa28574141a7d48fa1cc2802070150b93ec4 |
+--------------------------+---------------------------+
| cert name | cert value |
| "date" | "2003-04-04T07:39:51" |
+--------------------------+---------------------------+
| signed by key | signature |
| "jrh@@example.com" | "a02380def....0983fe90" |
+--------------------------+---------------------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/cert}
@end ifnotinfo
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 @sc{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 @dfn{public keys}. Giving someone your public key
does not give them the power to @i{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.
@page
@node Storage and workflow, Forks and merges, Certificates, Concepts
@section Storage and workflow
Monotone moves information in and out of four different types of
storage:
@itemize
@item
a @i{keystore} in your home directory
@item
a @i{workspace} in the local file system
@item
a @i{local database} in the local file system
@item
a @i{remote database} elsewhere on the internet
@end itemize
The @dfn{keystore} is a directory @file{.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 @emph{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.
@ifinfo
@smallexample
@group
pull, push, sync
(untrusted network exchanges)
_________/\________
/ \
+-------------+ +------------+ +-------------+
| | | | | |
| remote db | <==> | local db | <==> | workspace |
| | | | | |
+-------------+ +------------+ +-------------+
\________ _______/
\/
commit, update
(certified local exchanges)
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/general-workflow}
@end ifnotinfo
A @dfn{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 @file{_MTN} exists in the root of
any workspace. Monotone keeps some special files in the @file{_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 @file{_MTN} directory.
Aside from the special @file{_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 @dfn{check out} a
workspace from a database, or construct one from scratch and
@dfn{add} it into a database. As you work, you will occasionally
@dfn{commit} changes you have made in a workspace to a database,
and @dfn{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.
@ifinfo
@smallexample
@group
----------------- check out, workspace
( ) or update +----------------
----------------- ----------> |
| | | src/func.c
| local | <---------- | src/func.h
| database | add, | src/main.c
| | or commit | Makefile
\_________________/ | _MTN/
|
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/local-workflow}
@end ifnotinfo
A @dfn{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 @dfn{netsync}.
It supports three modes of exchange: pushing, pulling, and
synchronizing. A @dfn{pull} operation copies data from a remote
database to your local database. A @dfn{push} operation copies data
from your local database to a remote database. A @dfn{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.
@ifinfo
@smallexample
@group
----------------- -----------------
( ) ( )
----------------- --- pull ---> -----------------
| | | |
| remote | <--- sync ---> | local |
| database | | database |
| | <--- push --- | |
\_________________/ \_________________/
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/network-workflow}
@end ifnotinfo
In general, work flow with monotone involves 3 distinct stages:
@itemize
@item
When you @i{commit} changes from your workspace to your database,
your database stores the changes but does not communicate with the
network. Your commits happen immediately, without consulting any other
party, and do not require network connectivity.
@item
When you are ready to @i{exchange} work with someone else, you can
push, pull, or sync with other databases on the network. When you talk
to other servers on the network, your database may change, but your
workspace will not. In fact, you do not need a workspace at all
when exchanging work.
@item
When you @i{update} your workspace, some (but not all) of the
changes which your database received from the network are applied to
your workspace. The network is not consulted during updates.
@end itemize
The last stage of workflow is worth clarifying: monotone does
@emph{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 @emph{some} criteria; receiving changes
from a remote server is a @emph{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 @emph{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.
@page
@node Forks and merges, Branches, Storage and workflow, Concepts
@section Forks and merges
So far we have been talking about revisions as though each logically
follows exactly one revision before it, in a simple sequence of
revisions.
@ifinfo
@smallexample
@group
+-----------------------+
| parent revision |
+-----------------------+
|
|
+-----------------------+
| child revision |
+-----------------------+
|
|
+-----------------------+
| grandchild revision |
+-----------------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/linear-history}
@end ifnotinfo
This is a rosy picture, but sometimes it does not work out this
way. Sometimes when you make new revisions, other people are
@i{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 @dfn{fork}, and will
refer to the two children of a fork as the @i{left child} and @i{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.
@ifinfo
@smallexample
@group
+-----------------+
| parent revision |
+-----------------+
| |
+--------+ +---------+
| |
+-------------+ +--------------+
| left child | | right child |
+-------------+ +--------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/fork}
@end ifnotinfo
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 @dfn{merge} the fork, producing a common
grandchild revision which contains both changesets.
@ifinfo
@smallexample
@group
+-----------------+
| parent revision |
+-----------------+
| |
+--------+ +---------+
| |
+-------------+ +--------------+
| left child | | right child |
+-------------+ +--------------+
| |
+--------+ +---------+
| |
+-----------------+
| merged revision |
+-----------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/merge}
@end ifnotinfo
@page
@node Branches, , Forks and merges, Concepts
@section Branches
Sometimes, people intentionally produce forks which are @emph{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 @dfn{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 @command{mtn list branches}.
Branches are indicated with certs. The cert name @code{branch} is
reserved for use by monotone, for the purpose of identifying the
revisions which are members of a branch. A @code{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 @code{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 @code{branch}
and value @code{wobbler-stable}; all revisions in the unstable branch
would get a cert with name @code{branch} and value
@code{wobbler-unstable}. When a @code{wobbler-stable} revision forks,
the children of the fork will be merged. When a
@code{wobbler-unstable} revision forks, the children of the fork will
be merged. However, the @code{wobbler-stable} and
@code{wobbler-unstable} branches will not be merged together, despite
having a common ancestor.
@ifinfo
@smallexample
@group
+--------------------------+
| common ancestor revision |
+--------------------------+
| |
+---------+ +---------+
| |
+-----------------+ +-------------------+
| stable revision | | unstable revision |
+-----------------+ +-------------------+
| | | |
+-------+ +-------+ +-------+ +-------+
| | | |
+-------------+ +--------------+ +---------------+ +----------------+
| left stable | | right stable | | left unstable | | right unstable |
| child | | child | | child | | child |
+-------------+ +--------------+ +---------------+ +----------------+
| | | |
+-------+ +--------+ +-------+ +--------+
| | | |
+----------------+ +------------------+
| merged stable | | merged unstable |
| revision | | revision |
+----------------+ +------------------+
\_____________ _______________/ \_______________ _________________/
\/ \/
stable branch unstable branch
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/two-branches,,10cm}
@end ifnotinfo
For each branch, the set of revisions with @emph{no children} is
called the @dfn{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.
@ifinfo
@smallexample
@group
+-----------------+
| parent revision |
+-----------------+
| |
+--------+ |
| |
+-------------+ |
| left child | |
+-------------+ |
| |
*************|****************|************
* | | *
* +-----------------+ +-------------+ *
* | left grandchild | | right child | * the heads of the branch
* +-----------------+ +-------------+ * (before the merge)
* | | *
*************|****************|************
| |
+--------+ +---+
| |
+-----------------+
| merged revision |
+-----------------+
@end group
@end smallexample
@end ifinfo
@ifnotinfo
@image{figures/branch-heads}
@end ifnotinfo
When there is only one revision in the heads of a branch, we say that
@i{the heads are merged}, or more generally that @i{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.
@subsection Branch Names
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 @emph{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 @code{net.venge.monotone}, because
@code{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 @code{venge.net} will start up a
different program named @code{monotone}. If you work for Yoyodyne,
Inc. (owners of yoyodyne.com), then all your branch names should look
like @code{com.yoyodyne.@emph{something}}.
What the @code{@emph{something}} part looks like is up to you, but
usually the first part is the project name (the @code{monotone} in
@code{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 @code{net.venge.monotone.win32}.
(For more information, see @ref{Naming Conventions}.)
@page
@node Tutorial, Advanced Uses, Concepts, Top
@chapter Tutorial
This chapter illustrates the basic uses of monotone by means of an
example, fictional software project.
@section Issues
Before we walk through the tutorial, there are two minor issues to
address: standard options and revision selectors.
@subsection Standard Options
Before operating monotone, two important command-line options should
be explained.
@itemize
@item
Most commands operate on a @i{database}, which is selected with
the @option{--db} option.
@item
Many commands operate on a subset of the database, called a
@i{branch}, which is selected with the @option{--branch} option.
@end itemize
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.
@subsection Revision Selectors
Many commands require you to supply 40-character @sc{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 @ref{Selectors}.
We are now ready to explore our fictional project.
@page
@section The 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.
@itemize
@item
Jim lives in Japan, and owns JuiceBot Inc. You will know when we're talking
about Jim, because everything he does involves the letter ``j''.
@item
Abe lives in Australia and writes code related to apple juice. You will
know when we're talking about Abe, because everything he does involves
the letter ``a''.
@item
Beth lives in Brazil and writes code related to banana juice. You will
know when we're talking about Beth, because everything she does involves
the letter ``b''.
@end itemize
In our example the programmers work privately on laptops, and are
usually @emph{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.
@menu
* Creating a Database::
* Generating Keys::
* Starting a New Project::
* Adding Files::
* Committing Work::
* Basic Network Service::
* Synchronising Databases::
* Making Changes::
* Dealing with a Fork::
* Branching and Merging::
* Network Service Revisited::
@end menu
@page
@node Creating a Database, Generating Keys, Tutorial, Tutorial
@section Creating a Database
The first step Jim, Abe and Beth each need to perform is to create a
new database. This is done with the @command{mtn db init} command,
providing a @option{--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
@option{--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 @code{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:
@smallexample
@group
$ mtn db init --db=~/jim.mtn
@end group
@end smallexample
Abe issues the command:
@smallexample
@group
$ mtn db init --db=~/abe.mtn
@end group
@end smallexample
And Beth issues the command:
@smallexample
@group
$ mtn db init --db=~/beth.mtn
@end group
@end smallexample
@page
@node Generating Keys, Starting a New Project, Creating a Database, Tutorial
@section Generating Keys
Now Jim, Abe and Beth must each generate an @sc{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:
@smallexample
@group
$ mtn genkey jim@@juicebot.co.jp
mtn: generating key-pair 'jim@@juicebot.co.jp'
enter passphrase for key ID [jim@@juicebot.co.jp] : @i{<Jim enters his passphrase>}
confirm passphrase for key ID [jim@@juicebot.co.jp]: @i{<Jim confirms his passphrase>}
mtn: storing key-pair 'jim@@juicebot.co.jp' in /home/jim/.monotone/keys
@end group
@end smallexample
Abe does something similar:
@smallexample
@group
$ mtn genkey abe@@juicebot.co.jp
mtn: generating key-pair 'abe@@juicebot.co.jp'
enter passphrase for key ID [abe@@juicebot.co.jp] : @i{<Abe enters his passphrase>}
confirm passphrase for key ID [abe@@juicebot.co.jp]: @i{<Abe confirms his passphrase>}
mtn: storing key-pair 'abe@@juicebot.co.jp' in /home/abe/.monotone/keys
@end group
@end smallexample
as does Beth:
@smallexample
@group
$ mtn genkey beth@@juicebot.co.jp
mtn: generating key-pair 'beth@@juicebot.co.jp'
enter passphrase for key ID [beth@@juicebot.co.jp] : @i{<Beth enters her passphrase>}
confirm passphrase for key ID [beth@@juicebot.co.jp]: @i{<Beth confirms her passphrase>}
mtn: storing key-pair 'beth@@juicebot.co.jp' in /home/beth/.monotone/keys
@end group
@end smallexample
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:
@smallexample
@group
$ mtn list keys
[public keys]
9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c jim@@juicebot.co.jp (*)
(*) - only in /home/jim/.monotone/keys/
[private keys]
771ace046c27770a99e5fddfa99c9247260b5401 jim@@juicebot.co.jp
@end group
@end smallexample
The hexadecimal string printed out before each key name is a
@emph{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 name or the same fingerprint.
This output shows one private and one public key stored under the name
@code{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 @code{mtn} (and, more importantly, it simplifies the
tutorial text to skip the passphrase prompts) so he decides to use
@emph{ssh-agent} to store his key. He does this by using the
@code{ssh_agent_export} command to export his key into a format that
ssh-agent can understand and adding it with @code{ssh-add}.
@smallexample
@group
$ mtn ssh_agent_export ~/.ssh/id_monotone
enter passphrase for key ID [user@@example.com]:
enter new passphrase for key ID [user@@example.com]:
confirm passphrase for key ID [user@@example.com]:
$ chmod 600 ~/.ssh/id_monotone
@end group
@end smallexample
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.
@smallexample
@group
$ 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
@end group
@end smallexample
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 @file{monotonerc} file. He does
this by writing a @emph{hook function} which returns the passphrase:
@smallexample
@group
$ mkdir ~/.monotone
$ cat >>~/.monotone/monotonerc
function get_passphrase(keypair_id)
return "jimsekret"
end
^D
@end group
@end smallexample
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
@code{get_passphrase} function appears in the configuration file.
Abe and Beth do the same, with their secret passphrases.
@page
@node Starting a New Project, Adding Files, Generating Keys, Tutorial
@section Starting a New Project
Before he can begin work on the project, Jim needs to create a
@i{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 @command{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 @command{mtn setup}
command to create a new workspace.
This command creates the named directory (if it doesn't already exist),
and creates the @file{_MTN} directory within it. The @file{_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 @option{--db}, @option{--branch} or @option{--key}
options to the @command{setup} command will be cached in a file called
@file{_MTN/options}, so you don't have to keep passing them to monotone
all the time.
He chooses @code{jp.co.juicebot.jb7} as a branch name. (See
@ref{Naming Conventions} for more information about appropriate branch
names.) Jim then creates his workspace:
@smallexample
@group
/home/jim$ mtn --db=jim.mtn --branch=jp.co.juicebot.jb7 setup juice
/home/jim$ cd juice
/home/jim/juice$
@end group
@end smallexample
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.
@page
@node Adding Files, Committing Work, Starting a New Project, Tutorial
@section Adding Files
Next Jim decides to add some files to the project. He writes up
a file containing the prototypes for the JuiceBot 7:
@smallexample
@group
$ 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
@end group
@end smallexample
Then adds a couple skeleton source files which he wants Abe and Beth
to fill in:
@smallexample
@group
$ 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
@end group
@end smallexample
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.
@smallexample
@group
$ 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
@end group
@end smallexample
This command produces a record of Jim's intentions in a special file
called @file{_MTN/revision}, stored in the workspace. The file is plain
text:
@smallexample
@group
$ 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]
@end group
@end smallexample
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:
@smallexample
@group
$ mtn status
Current branch: jp.co.juicebot.jb7
Changes against parent :
added include/jb.h
added src/apple.c
added src/banana.c
@end group
@end smallexample
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 @emph{and} a GNU
``unified diff'' of the patches involved in the changeset:
@smallexample
@group
$ 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. */
+@}
@end group
@end smallexample
@page
@node Committing Work, Basic Network Service, Adding Files, Tutorial
@section Committing Work
Satisfied with the work he's done, Jim wants to save his changes. He
then commits his workspace, which causes monotone to process the
@file{_MTN/revision} file and record the file contents, manifest, and
revision into the database. Since he provided a branch name when he
ran @command{setup}, monotone will use this as the default branch name
when he commits.
@smallexample
@group
$ mtn commit --message="initial checkin of project"
mtn: beginning commit on branch 'jp.co.juicebot.jb7'
mtn: committed revision 2e24d49a48adf9acf3a1b6391a080008cbef9c21
@end group
@end smallexample
When monotone committed Jim's revision, it updated @file{_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 @command{checkout}
command, if he wishes to return to this revision:
@smallexample
@group
$ mtn automate get_base_revision_id
2e24d49a48adf9acf3a1b6391a080008cbef9c21
@end group
@end smallexample
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.
@smallexample
@group
$ mtn ls certs 2e24d49a48adf9acf3a1b6391a080008cbef9c21
-----------------------------------------------------------------
Key : jim@@juicebot.co.jp
Sig : ok
Name : branch
Value : jp.co.juicebot.jb7
-----------------------------------------------------------------
Key : jim@@juicebot.co.jp
Sig : ok
Name : date
Value : 2004-10-26T02:53:08
-----------------------------------------------------------------
Key : jim@@juicebot.co.jp
Sig : ok
Name : author
Value : jim@@juicebot.co.jp
-----------------------------------------------------------------
Key : jim@@juicebot.co.jp
Sig : ok
Name : changelog
Value : initial checkin of project
@end group
@end smallexample
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 @code{jim@@juicebot.co.jp}. The
second indicates whether this cert is ``ok'', meaning whether the
@sc{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
@code{jim@@juicebot.co.jp}, the revision
@code{2e24d49a48adf9acf3a1b6391a080008cbef9c21} is a member of the
branch @code{jp.co.juicebot.jb7}, written by
@code{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 @i{true} or @i{false} in any global sense. Each cert indicates
that @i{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:
@smallexample
@group
$ mtn heads
branch 'jp.co.juicebot.jb7' is currently merged:
2e24d49a48adf9acf3a1b6391a080008cbef9c21 jim@@juicebot.co.jp 2004-10-26T02:53:08
@end group
@end smallexample
The output of this command tells us that there is only one current
``head'' revision in the branch @code{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.
@page
@node Basic Network Service, Synchronising Databases, Committing Work, Tutorial
@section Basic Network Service
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:
@smallexample
@group
$ mtn --db=~/abe.mtn pubkey abe@@juicebot.co.jp >~/abe.pubkey
@end group
@end smallexample
His public key is just a plain block of ASCII text:
@smallexample
@group
$ cat ~/abe.pubkey
[pubkey abe@@juicebot.co.jp]
MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCbaVff9SF78FiB/1nUdmjbU/TtPyQqe/fW
CDg7hSg1yY/hWgClXE9FI0bHtjPMIx1kBOig09AkCT7tBXM9z6iGWxTBhSR7D/qsJQGPorOD
DO7xovIHthMbZZ9FnvyB/BCyiibdWgGT0Gtq94OKdvCRNuT59e5v9L4pBkvajb+IzQIBEQ==
[end]
@end group
@end smallexample
Beth also exports her public key:
@smallexample
@group
$ mtn --db=~/beth.mtn pubkey beth@@juicebot.co.jp >~/beth.pubkey
@end group
@end smallexample
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:
@smallexample
@group
$ cat ~/abe.pubkey ~/beth.pubkey | mtn --db=~/jim.mtn read
mtn: read 2 packets
@end group
@end smallexample
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 @file{~/.monotone} directory:
@smallexample
@group
$ 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
@end group
@end smallexample
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 @command{serve} command:
@smallexample
@group
$ mtn --db=jim.mtn serve
@end group
@end smallexample
This command starts monotone listening on all network interfaces of
his laptop on the default port 4691, serving everything in his database.
@page
@node Synchronising Databases, Making Changes, Basic Network Service, Tutorial
@section Synchronising Databases
With Jim's server preparations done, now Abe is ready to fetch Jim's
code. To do this he issues the monotone @command{sync} command:
@smallexample
@group
$ 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
@end group
@end smallexample
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 @command{sync} command again with Jim, and work will flow
both ways. The first time you @command{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 @emph{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.
@page
@node Making Changes, Dealing with a Fork, Synchronising Databases, Tutorial
@section Making Changes
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
@code{jp.co.juicebot.jb7} branch into a workspace, so he can edit
it:
@smallexample
@group
$ mtn --db=abe.mtn --branch=jp.co.juicebot.jb7 checkout .
@end group
@end smallexample
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 @file{.} at the end, monotone would have created that
directory and unpacked the files into it.) Abe then opens up one of the
files, @file{src/apple.c}, and edits it:
@smallexample
@group
$ vi src/apple.c
@i{<Abe writes some apple-juice dispensing code>}
@end group
@end smallexample
The file @file{src/apple.c} has now been @emph{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:
@smallexample
@group
$ 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);
@}
@end group
@end smallexample
Satisfied with his day's work, Abe decides to commit.
@smallexample
@group
$ mtn commit
mtn: beginning commit on branch 'jp.co.juicebot.jb7'
@end group
@end smallexample
Abe neglected to provide a @option{--message} option specifying the
change log on the command line and the file @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 @command{vi} --- with an explanation of the changes being
committed and the opportunity to enter a log message.
@smallexample
@group
polling implementation of src/apple.c
MTN:
MTN: ----------------------------------------------------------------------
MTN: Enter Log. Lines beginning with `MTN:' are removed automatically
MTN:
MTN: format_version "1"
MTN:
MTN: new_manifest [b33cb337dccf21d6673f462d677a6010b60699d1]
MTN:
MTN: old_revision [2e24d49a48adf9acf3a1b6391a080008cbef9c21]
MTN:
MTN: patch "src/apple.c"
MTN: from [2650ffc660dd00a08b659b883b65a060cac7e560]
MTN: to [e2c418703c863eabe70f9bde988765406f885fd0]
MTN:
MTN: ----------------------------------------------------------------------
MTN:
@end group
@end smallexample
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:
@smallexample
@group
mtn: committed revision 70decb4b31a8227a629c0e364495286c5c75f979
@end group
@end smallexample
Abe then sends his new revision back to Jim:
@smallexample
@group
$ 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
@end group
@end smallexample
Beth does a similar sequence. First she syncs her database with
Jim's:
@smallexample
@group
$ 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
@end group
@end smallexample
She checks out a copy of the tree from her database:
@smallexample
@group
$ mtn --db=beth.mtn --branch=jp.co.juicebot.jb7 checkout .
@end group
@end smallexample
She edits the file @file{src/banana.c}:
@smallexample
@group
$ vi src/banana.c
@i{<Beth writes some banana-juice dispensing code>}
@end group
@end smallexample
and logs her changes in @file{_MTN/log} right away so she does not
forget what she has done like Abe.
@smallexample
@group
$ vi _MTN/log
* src/banana.c: Added polling implementation
@end group
@end smallexample
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:
@smallexample
@group
$ mtn commit
mtn: beginning commit on branch 'jp.co.juicebot.jb7'
mtn: committed revision 80ef9c9d251d39074d37e72abf4897e0bbae1cfb
@end group
@end smallexample
And she syncs with Jim again:
@smallexample
@group
$ 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
@end group
@end smallexample
@page
@node Dealing with a Fork, Branching and Merging, Making Changes, Tutorial
@section Dealing with a Fork
Careful readers will note that, in the previous section, the JuiceBot
company's work was perfectly serialized:
@enumerate
@item Jim did some work
@item Abe synced with Jim
@item Abe did some work
@item Abe synced with Jim
@item Beth synced with Jim
@item Beth did some work
@item Beth synced with Jim
@end enumerate
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:
@enumerate
@item Jim made revision 2e24d...
@item Abe changed revision 2e24d... into revision 70dec...
@item Beth derived revision 70dec... into revision 80ef9...
@end enumerate
This is a simple, but sadly unrealistic, ordering of events. In real
companies or work groups, people often work in parallel,
@emph{diverging} from commonly known revisions and @emph{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 @dfn{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 @command{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:
@smallexample
@group
$ vi src/banana.c
@i{<Beth changes her banana-juice dispenser to use interrupts>}
@end group
@end smallexample
Beth finishes and examines her changes:
@smallexample
@group
$ 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);
@}
@end group
@end smallexample
She commits her work:
@smallexample
@group
$ mtn commit --message="interrupt implementation of src/banana.c"
mtn: beginning commit on branch 'jp.co.juicebot.jb7'
mtn: committed revision 8b41b5399a564494993063287a737d26ede3dee4
@end group
@end smallexample
And she syncs with Jim:
@smallexample
@group
$ mtn sync
@end group
@end smallexample
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.
@smallexample
@group
$ vi apple.c
@i{<Abe changes his apple-juice dispenser to use interrupts>}
@end group
@end smallexample
Thus when Abe commits, he unknowingly creates a fork:
@smallexample
@group
$ mtn commit --message="interrupt implementation of src/apple.c"
@end group
@end smallexample
Abe does not see the fork yet; Abe has not actually seen @emph{any} of
Beth's work yet, because he has not synchronized with Jim. Since
he has new work to contribute, however, he now syncs:
@smallexample
@group
$ mtn sync
@end group
@end smallexample
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:
@smallexample
@group
$ 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
@end group
@end smallexample
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:
@smallexample
@group
$ 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
@end group
@end smallexample
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.
After merging, the branch has a single head again, and Jim updates
his workspace.
@smallexample
@group
$ 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
@end group
@end smallexample
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 @emph{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
@emph{required} to update, and risk the above problems, before you can
commit. Monotone, however, was designed with this problem in mind, and
thus @emph{always} allows you to commit before merging. A good rule of
thumb is to only use @command{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).
@page
@node Branching and Merging, Network Service Revisited, Dealing with a Fork, Tutorial
@section Branching and Merging
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 @emph{not} integrate them
with other people's --- or at least not right away. One way to do this
would be to simply never run @command{mtn merge}; but it would
quickly become confusing to try and keep track of which changes were in
which revisions. This is where @emph{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
@code{jp.co.juicebot.jb7}, she will use branch
@code{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
@option{--branch} to commit:
@smallexample
@group
$ 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
@end group
@end smallexample
That's all there is to it --- there is now a
@code{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 @command{propagate}
command:
@smallexample
@group
$ 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
@end group
@end smallexample
The @command{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:
@smallexample
@group
$ 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
@end group
@end smallexample
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 @command{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 @command{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:
@smallexample
@group
$ 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
@end group
@end smallexample
@page
@node Network Service Revisited, , Branching and Merging, Tutorial
@section Network Service Revisited
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.
@itemize
@item
First, Jim is finding that he has to spend more of his time
travelling, demonstrating the new juicebot features to customers; thus
his laptop is spending more time disconnected from the network, or
connected at dynamic addresses where it's not convenient for Abe and
Beth to find him and sync.
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.
@item
Second, because Jim has been using the one database file both for his
own local work, and for serving to the others in the team, he
occasionally finds that the monotone serve process (busy syncing with
Abe or Beth) has a lock on the database, while he's trying to do local
work like updates or commits.
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.
@end itemize
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 @command{serve} command and provide access for the other to
@command{sync} with. Beth also has the idea to create a second database
for the @command{serve} process, and to @command{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 @command{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, @code{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:
@smallexample
@group
$ mtn --db=server.mtn db init
$ mtn genkey monotone-server@@www.juicebot.co.jp
mtn: generating key-pair 'monotone-server@@www.juicebot.co.jp'
enter passphrase for key ID [monotone-server@@www.juicebot.co.jp] : @i{<Jim enters a new passphrase>}
confirm passphrase for key ID [monotone-server@@www.juicebot.co.jp]: @i{<Jim confirms the passphrase>}
mtn: storing key-pair 'monotone-server@@www.juicebot.co.jp' in /home/jim/.monotone/keys
$ cat abe.pubkey beth.pubkey jim.pubkey | mtn --db=server.mtn read
mtn: read 3 packets
@end group
@end smallexample
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
@code{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 @file{~/.monotone/read-permissions} on the server, above
the broader permissions given to team-members. See the @ref{Hook
Reference} for @code{get_netsync_read_permitted} for more details; the
resulting file looks like this:
@smallexample
@group
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"
@end group
@end smallexample
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 @code{get_passphrase} hook in the server's
@file{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 @option{--bind=@var{address}:@var{port}} argument like so:
@smallexample
@group
$ mtn --db=server.mtn --bind=www.juicebot.co.jp serve
@end group
@end smallexample
This will start monotone listening on the default port (4691), but only
on the IP address associated with @code{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
@option{--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 @option{--bind=:1234}.
When he's satisfied the server is set up correctly, Jim does an initial
@command{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
@ref{Vars}. These vars can be seen as follows:
@smallexample
@group
$ 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
@end group
@end smallexample
The team members can reset their local database vars accordingly:
@smallexample
@group
$ mtn set database default-server www.juicebot.co.jp
@end group
@end smallexample
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:
@itemize
@item
The team members can still sync with each other if needed.
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.
@item
The team members continue to discover multiple heads and changes that
need merging, as before. Each team member can merge the heads, and will
produce the same revision id if they merge to the same result.
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
@command{sync}, they develop the habit of doing a @command{pull} from
the server first. If new revisions were received from the server, they
first @command{merge} their new revisions with the head(s) from the
server, and finally @command{sync} to publish their merged changes as
one. If the last @command{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 @command{merge} and @command{sync} would probably
be polite.
@item
Jim knows he doesn't have to keep a special backup of the new server's
contents; if the server should fail, all the contents of its database
can be found amongst the other team members (especially because no
commits are done on the server itself).
He does, however, take a copy of the server's private key, so he can
restore that if necessary.
@item
In fact, Jim realises that he can now commit a copy of the web site's
current contents into monotone on a new branch,
@code{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 @command{update} in there when he wants to bring the public web
site up to date. Later, he'll think about using monotone's @ref{Quality
Assurance} mechanisms and Event Notification @ref{Hooks}, so that the
web server can update itself automatically when appropriate new
revisions are received.
@item
Jim also knows that even if someone should break into the shared hosting
server and tamper with the database, they won't be able to inject
malicious code into the project, because all revisions are signed by the
team members, and he has set his @ref{Trust Evaluation Hooks} so he
doesn't trust the server key for signing revisions.
In monotone, the important trust consideration is on the @emph{signed
content}, rather than on the @emph{replication path} by which that
content arrived in your database.
@end itemize
@node Advanced Uses, CVS Phrasebook, Tutorial, Top
@chapter Advanced Uses
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.
@menu
* Other Transports:: Using netsync over SSH, or other transports.
* Selectors:: Selecting revisions by certificate.
* Restrictions:: Limit workspace changes to specified files.
* Scripting:: Running monotone from other programs.
* Inodeprints:: Trading off safety for speed in your workspace.
* Merge Conflicts:: The various conflict types and how to resolve them.
* Workspace Collisions:: Workspace files that collide with new versioned files.
* Quality Assurance:: Integrating testing and review with development.
* Vars:: Simple per-database configuration information.
* Reserved Files:: File names with special meanings.
* Reserved Certs:: Certificate names with special meanings.
* Naming Conventions:: Choosing appropriate names for keys and branches.
* File Attributes:: Marking files as executable, or other attributes.
* Merging:: Merging with external tools, handling binary files.
* Migrating and Dumping:: Changing the underlying storage system.
* Importing from CVS:: Building a monotone database from a CVS repository.
* Using packets:: Transferring data ``by hand''.
@end menu
@page
@node Other Transports, Selectors, Advanced Uses, Advanced Uses
@section Other Transports
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 @code{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 @dfn{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:
@enumerate
@item SSH URIs, of the form
@code{ssh://[@var{user}@@]@var{hostname}[:@var{port}]/@var{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
@code{ssh://@var{host-part}/~/@var{relative/path.mtn}} or
@code{ssh://@var{host-part}/~@var{user}/@var{relative/path.mtn}}.)
@item File URIs, of the form
@code{file:@var{/path/to/db.mtn}}, to synchronize between local databases.
@end enumerate
@code{ssh:} and @code{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 @command{ssh} program must be in your
command execution path, either @var{$PATH} on Unix-like systems or
@var{%PATH%} on Windows systems. Monotone will execute @command{ssh}
as a subprocess, running @command{mtn serve} on the other end of the
SSH connection. You will need @command{mtn} to be in the command
execution path of the remote shell environment.
In the case of File URIs, @command{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 @command{pull}. Also note
that monotone's default transport authentication is @emph{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 @code{get_netsync_connect_command} and
@code{use_transport_auth}. For details on these hooks, see
@ref{Netsync Transport Hooks}.
@page
@node Selectors, Restrictions, Other Transports, Advanced Uses
@section Selectors
Revisions can be specified on the monotone command line, precisely, by
entering the entire 40-character hexadecimal @sc{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.
@heading Simple examples
Some selector examples are helpful in clarifying the idea:
@table @code
@item a432
Revision IDs beginning with the string @code{a432}
@item graydon@@pobox.com/2004-04
Revisions written by @code{graydon@@pobox.com} in April 2004.
@item "jrh@@example.org/2 weeks ago"
Revisions written by @code{jrh@@example.org} 2 weeks ago.
@item graydon/net.venge.monotone.win32/yesterday
Revisions in the @code{net.venge.monotone.win32} branch, written by
@code{graydon}, yesterday.
@end table
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.
@heading Selectors in detail
A selector is a combination of a selector type, which is a single
ASCII character, followed by a @code{:} character and a selector
string. All selectors strings except for selector type @code{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:
@table @asis
@item Generic cert selector
Uses selector type @code{c}. The selector string has the syntax
@var{name} or @var{name}@code{=}@var{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, @code{c:tag} matches all revisions that have a tag, and
@code{c:tag=monotone-0.25} will match the revision tagged
@code{monotone-0.25}. (See also the @code{t} selector below.)
@item Author selection
Uses selector type @code{a}. For example, @code{a:graydon} matches
@code{author} certs where the cert value contains @code{graydon}.
@item Branch selection
Uses selector type @code{b}. For example, @code{b:net.venge.monotone} matches
@code{branch} certs where the cert value is @code{net.venge.monotone}.
Values to match for can have shell wildcards. If you give a bare @code{b:}
monotone will require you to be in a workspace, and will use the branch
value recorded in your _MTN/options file.
@item Heads selection
Uses selector type @code{h}. For example, @code{h:net.venge.monotone} matches
@code{branch} certs where the cert value is @code{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
@code{h:} monotone will require you to be in a workspace, and use the branch
recorded in your _MTN/options file.
@item Date selection
Uses selector type @code{d}. For example, @code{d:2004-04} matches
@code{date} certs where the cert value begins with
@code{2004-04}. This selector also accepts expanded date syntax (see below).
@item "Earlier or equal than" selection
Uses selector type @code{e}. For example, @code{e:2004-04-25} matches
@code{date} certs where the cert value is less or equal than
@code{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)
@item "Later than" selection
Uses selector type @code{l}. For example, @code{l:2004-04-25} matches
@code{date} certs where the cert value is strictly greater than
@code{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)
@item Identifier selection
Uses selector type @code{i}. For example, @code{i:0f3a} matches
revision IDs which begin with @code{0f3a}.
@item Parent selection
Uses selector type @code{p}. For example, @code{p:0f3a} matches the
revision IDs which are the parent of the revision ID which begins with
@code{0f3a}. If you give a bare @code{p:}, monotone will require you to be in
a workspace, and query the parent of the base workspace revision.
@item Tag selection
Uses selector type @code{t}. For example, @code{t:monotone-0.11} matches
@code{tag} certs where the cert value begins with @code{monotone-0.11}.
Values to match for can have shell wildcards.
@end table
Further selector types may be added in the future.
@heading Composite selectors
Selectors may be combined with the @code{/} character. The combination
acts as database intersection (or logical @code{and}). For example,
the selector @code{a:graydon/d:2004-04} can be used to select a
revision which has an @code{author} cert beginning with @code{graydon}
@emph{as well as} a @code{date} cert beginning with @code{2004-04}. The
@code{/} character can be escaped using the @code{\} character if necessary.
@heading Selector expansion
Before selectors are passed to the database, they are expanded using a
Lua hook: @code{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 @code{jrh@@example.org} is an author
selector, due to its syntactic form, so modifies it to read
@code{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 @ref{Hook Reference}.
@heading Expanding dates
All date-related selectors (@code{d}, @code{e}, @code{l}) support an
English-like syntax similar to CVS. This syntax is expanded to the
numeric format by a Lua hook: @code{expand_date}.
The allowed date formats are:
@table @asis
@item now
Expands to the current date and time.
@item today
Expands to today's date. @code{e} and @code{l} selectors assume time 00:00:00
@item yesterday
Expands to yesterday's date. @code{e} and @code{l} selectors assume
time 00:00:00
@item <number> @{minute|hour@} <ago>
Expands to today date and time, minus the specified @code{number} of
minutes|hours.
@item <number> @{day|week|month|year@} <ago>
Expands to today date, minus the specified @code{number} of
days|weeks|months|years. @code{e} and @code{l} selectors assume time
00:00:00
@item <year>-<month>[-day[Thour:minute:second]]
Expands to the supplied year/month. The day and time component are
optional. If missing, @code{e} and @code{l} selectors assume the first
day of month and time 00:00:00.
The time component, if supplied, must be complete to the second.
@end table
For the complete source code of the hook, see @ref{Hook Reference}.
@heading Typeless selection
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
@code{graydon/net.venge.monotone.win32/yesterday} would pass through
the selector @code{graydon} as an unknown selector; so long as there
are no branches or tags beginning with the string @code{graydon} this
is just as effective as specifying @code{a:graydon}.
@page
@node Restrictions, Scripting, Selectors, Advanced Uses
@section Restrictions
Several monotone commands accept optional @var{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
@var{pathname...} arguments:
@itemize
@item @command{status}
@item @command{diff}
@item @command{revert}
@item @command{commit}
@item @command{list known}
@item @command{list unknown}
@item @command{list ignored}
@item @command{list missing}
@item @command{list changed}
@end itemize
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
@command{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
@option{--depth=@var{n} } option, where @var{n} specifies the maximum
number of directories to descend. For example, @var{n}=0 disables
recursion, @var{n}=1 means descend at most one directory, and so on.
The @command{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.
@heading Subdirectory restrictions
The restrictions facility also allows commands to operate from within a
subdirectory of the workspace. By default, the @i{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.
@heading Finding a workspace
Monotone only stores a single @file{_MTN} directory at the root of a
workspace. Because of this, a search is done to find the @file{_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
@file{_MTN} directory is found or the filesystem root is reached. Upon
finding an @file{_MTN} directory, the @file{_MTN/options} file is read for
default options. The @option{--root} option may be used to stop the
search early, before reaching the root of the physical filesystem.
Many monotone commands don't require a workspace and will simply
proceed with no default options if no @file{_MTN} directory is found.
However, some monotone commands do require a workspace and will fail
if no @file{_MTN} directory can be found.
The @command{checkout}, @command{clone} and @command{setup} commands
create a @i{new workspace} and initialize a new @file{_MTN/options}
file based on their current option settings.
@page
@node Scripting, Inodeprints, Restrictions, Advanced Uses
@section Scripting
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
@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 @ref{Automation}.
@node Inodeprints, Merge Conflicts, Scripting, Advanced Uses
@section Inodeprints
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 @command{status},
@command{diff}, @command{update}, @command{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 @sc{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 @emph{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 @command{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 @file{_MTN/inodeprints}. You can at any time delete or truncate
the @file{_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 @code{use_inodeprints} hook to return
@code{true}; this will automatically enable inodeprints mode in any new
workspaces you create. See @ref{Hook Reference} for details.
@page
@node Merge Conflicts, Workspace Collisions, Inodeprints, Advanced Uses
@section Merge Conflicts
Several different types of conflicts may be encountered when merging
two revisions using the database merge commands @command{merge},
@command{explicit_merge}, @command{propagate} and
@command{merge_into_dir} or when using the workspace merge commands
@command{update}, @command{pluck} and @command{merge_into_workspace}.
The @command{show_conflicts} and @command{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.
@subsection Conflict Types
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.
@subheading File Content Conflict
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 use with your
favorite merge tool. See the @code{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.
@subheading Duplicate Name Conflict
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 @emph{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:
@itemize
@item
Two people both realize a new file should be added, and commit it. In
this case, the files have the right name and the right contents, but
monotone reports a conflict because they were added separately.
@item
Two people each decide to add new files with different content, and
accidently pick the same name.
@end itemize
These conflicts are reported when someone tries to merge the two
revisions containing the new files.
@subsubheading Same file
For the first case, the conflict is resolved by @command{drop}ing one
file. The contents should be manually merged first, 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
@command{automate get_file_of}; the revision id is shown in the merge
error message. The process can be confusing; here's a detailed
example.
Suppose Beth and Abe each commit a new file @file{checkout.sh}. When
Beth attempts to merge the two heads, she gets a message like:
@smallexample
@group
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
@end group
@end smallexample
The file labeled @code{right} is the file in Be