4.4 Network

mtn serve [--bind=[address][:port]]

mtn pull [--[no-]set-default] [--[no-]dry-run] [uri]

mtn push [--[no-]set-default] [--[no-]dry-run] [--keys-to-push=key] [uri]

mtn sync [--[no-]set-default] [--[no-]dry-run] [--keys-to-push=key] [uri]

mtn pull [--[no-]set-default] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

mtn push [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

mtn sync [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

See the online help for more options. See --update.

These commands operate the “netsync” protocol built into monotone. This is a custom protocol for rapidly synchronizing two monotone databases using a hash tree index. The protocol is “peer to peer”, but requires one peer to listen for incoming connections (the server) and the other peer (the client) to connect to the server. When run with --stdio, the server listens for a single connection then terminates. When run with --bind, or with neither option, the server listens for TCP connections and serves them continuously, until it is shut down.

The network address given to serve as an argument to --bind should be a host name to listen on, optionally followed by a colon and a port number. The default port number is 4691. If no --bind option is given, the server listens on port 4691 of every network interface.

If serve is run with --stdio, a single netsync session is served over the stdin and stdout file descriptors. If --no-transport-auth is provided along with --stdio, transport authentication and access control mechanisms are disabled. Only use --no-transport-auth if you are certain that the transport channel in use already provides sufficient authentication and authorization facilities.

If --dry-run is given, the connection is made, but no data is transferred. Instead, a summary of what would be transferred is output; the number of revisions, certs and keys that would be sent and received. For sent revisions, the branch names are also output.

The uri-or-address arguments given to push, pull, and sync can be of two possible forms.

If the argument is an URI, the Lua hook get_netsync_connect_command may transform it into a connection command, which is later executed as the transport channel for netsync. The URI itself consists of a connection scheme, an optional user (only used for ssh-related transports), a host with an optional port (which both might be optional as well, f.e. for the file scheme), a path and a query part, which denotes one or more branches and optionally also exclude patterns for the exchange:

<scheme>://[[<user>@]<host>[:<port>]][/<path>][?[-]<pattern>[;[-]<pattern>]...]

Branches matching a pattern are excluded if the pattern is preceded by ’-’, included otherwise.

The syntax for patterns is very simple. * matches 0 or more arbitrary characters. ? matches exactly 1 arbitrary character (you need to escape that as %3F in a URI). {,} matches alternatives; {foo,bar,baz} matches “foo”, or “bar”, or “baz”. These can be combined arbitrarily. A backslash (\) escapes these special characters, to match exactly that character; this might be useful in case someone, for some odd reason, decides to put a “*” into their branch name.

Valid examples of URIs monotone accepts are:

mtn://my.server:4690?my.branch
mtn://my.server/project?my.other.branch*;-my.other.branch.test
mtn://my.server/project?one.branch;-one.branch.test;another.branch;-another.branch.test
mtn://my.server/project?{one.branch,another.branch};-{one.branch.test,another.branch.test}
file:///path/to/database.mtn?my.branch
ssh://joe@my.server/~/db.mtn?joes.branch

file: and ssh: are not supported on Windows native, but they are supported on Windows Cygwin.

If the server has a multi-host setup, the path component of the URI might be used to distinguish between different databases (please ask the provider of the server for details).

For backward compatibility, if the argument is a simple hostname (with no scheme, but with optional port number), monotone will default to the mtn: URI scheme, i.e. use a TCP socket to the specified host and port. The glob parameters then indicate a set of branches to exchange. Multiple glob and --exclude options can be specified. Important notice: This call syntax is deprecated and subject to removal in future versions of monotone!

For both syntaxes, every branch which matches a glob or branch pattern exactly, and does not match an exclude-glob or exclude pattern, will be indexed and made available for synchronization.

For example, perhaps Bob and Alice wish to synchronize their net.venge.monotone.win32 and net.venge.monotone.i18n branches. Supposing Alice’s computer has hostname alice.someisp.com, then Alice might run:

$ mtn --bind=alice.someisp.com serve

And Bob might run

$ mtn sync "mtn://alice.someisp.com?net.venge.monotone*"

When the operation completes, all branches matching net.venge.monotone* will be synchronized between Alice and Bob’s databases.

The pull, push, and sync commands only require you pass uri the first time you use one of them; monotone will store this in the database and in the future default to the same URI. For instance, if Bob wants to sync with Alice again, he can simply run:

$ mtn sync

Of course, he can still sync with other people and other branches by passing an URI, address or address plus globs on the command line; this will not affect his default affinity for Alice. If you ever do want to change your defaults, simply pass the --set-default option when connecting to the server and branch pattern that you want to make the new default.

The serve command doesn’t care about workspaces, so even if you stand in one, you will have to give it the database to serve, the server key to use and the key directory explicitly.

In the server, different permissions can be applied to each branch; see get_netsync_read_permitted and get_netsync_write_permitted.

If --pid-file is specified, serve will create the specified file and record the process identifier of the server in the file. This file can then be read to identify specific monotone server processes.

mtn clone uri [--branch=branchname] [--revision=rev] [directory]

mtn clone address[:port] branchname [directory] deprecated

clone is a helper command that performs the roles of a number of other commands all at once. First, it constructs a new database. If no database is given, the configured default database is created or re-used (see get_default_database_alias for more details; ~/.monotone/default.mtn by default). Then it populates this database by pulling any data which match the branch pattern in the uri argument from the remote database.

The branch pattern must specify a single branch; clone uses that to determine which branch to checkout.

Finally, clone copies the files out of the newly created database into a local directory, just as checkout would. If no directory is given, the branchname is used as directory. If --revision is given (see Selectors), that revision must be on the specified branch, and is checked out; otherwise the head of the branch is checked out.

Important notice: The address[:port] branchname call syntax is deprecated and subject to removal in future versions of monotone!