Next: , Previous: , Up: Command Reference   [Contents][Index]


4.11 Automation

This section contains subcommands of the mtn automate command, used for scripting monotone. All give output on stdout; they may also give useful chatter on stderr, including warnings and error messages.

When run under mtn automate stdio, there are five output streams available; main, error, warning, progress, and ticker. When run under mtn automate, the main stream goes to stdout, and the error, warning, progress, and ticker streams all go to stderr.

Many commands produce output in a format called basic_io; for more information, see Formats.

Revision arguments to automate commands must be hex ids, not selectors.

mtn automate ancestors rev...
Arguments:

One or more revision IDs.

Added in:

0.2

Purpose:

Prints the ancestors of one or more revisions.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one ancestor of the given revisions. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

The output does not include the specified revisions, except if one of them is an ancestor of another.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate ancestry_difference new [old...]
Arguments:

A “new” revision ID new, followed by zero or more “old” revision IDs old....

Added in:

0.1

Purpose:

Prints all ancestors of the new revision, that are not also ancestors of one of the old revisions. For purposes of this command, “ancestor” is an inclusive term; each revision is an ancestor of itself. For example, if new is an ancestor of any of old..., new will not be printed; but if new is not an ancestor of any of the “old” revisions, then it will be. Similarly, none of old... will be printed.

The reason for the names new and old is that if new is a newer revision than old..., then this command tells you which all revisions that are newer than old..., and are also ancestors of new.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

A list of revision IDs, in hexadecimal, each followed by a newline. Revisions are printed in topologically sorted order.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate branches
Arguments:

None.

Added in:

2.2

Purpose:

Prints all branch certs present in the revision graph, that are not excluded by the Lua hook ignore_branch.

Sample output:
net.venge.monotone
net.venge.monotone.win32
Output format:

Zero or more lines, each the name of a branch. The lines are printed in alphabetically sorted order.

Error conditions:

None.

mtn automate cert revision name value
Arguments:

revision is an existing revision, name is the certificate name and value its value.

Added in:

4.1

Purpose:

automate variant of mtn cert.

Sample usage:
mtn automate cert 4c2c1d846fa561601254200918fba1fd71e6795d author tester@test.net
Output format:

No output.

Error conditions:

If the revision is invalid prints an error message to stderr and exits with status 1.

mtn automate certs id
Arguments:

A revision ID id, for which any certificates will be printed.

Changes:
  • 11.0 – Keys are now listed by hash instead of name.
  • 1.0 – Added.
Purpose:

Prints all certificates associated with the given revision ID. Each certificate is contained in a basic IO stanza. For each certificate, the following values are provided:

'key'
      the hex-encoded hash of the key used to sign this certificate.
'signature'
      a string indicating the status of the signature. Possible
      values of this string are:
            'ok'        : the signature is correct
            'bad'       : the signature is invalid
            'unknown'   : signature was made with an unknown key
'name'
      the name of this certificate
'value'
      the value of this certificate
'trust'
      is this certificate trusted by the defined trust metric?
      Possible values of this string are:
            'trusted'   : this certificate is trusted
            'untrusted' : this certificate is not trusted
Sample output:
      key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
     name "author"
    value "emile@alumni.reed.edu"
    trust "trusted"

      key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
     name "branch"
    value "net.venge.monotone"
    trust "trusted"

      key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
     name "changelog"
    value "propagate from branch 'net.venge.monotone.annotate' (head 76a886ef7c8ae12a4bba5fc2bd252557bf863aff)
            to branch 'net.venge.monotone' (head 2490479a4e4e99243fead6d627d78291fde592f0)
"
    trust "trusted"

      key [5cd3b3a7ad2e8645e8887af193ee522dc59112e4]
signature "ok"
     name "date"
    value "2005-05-20T20:19:25"
    trust "trusted"
Output format:

All stanzas are formatted by basic_io. Stanzas are separated by a blank line. Values will be escaped, ’\’ to ’\\’ and ’"’ to ’\"’.

Error conditions:

If a certificate is signed with an unknown public key, a warning message is printed to stderr. If the revision specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate checkout [--[no-]move-conflicting-paths] [--revision=id] [--branch=branchname] directory
Arguments:

Options and arguments are the same as mtn checkout.

Changes:

13.0 – initial

Purpose:

Create a new workspace containing the given revision; see mtn checkout.

Sample output:

None.

Output format:

None.

Error conditions:

see mtn checkout.

mtn automate children rev
Arguments:

One revision ID, rev.

Added in:

0.2

Purpose:

Prints the immediate children of a revision. This is like a non-recursive version of mtn automate descendents.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one child of the given revision. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

If the given revision rev does not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate common_ancestors rev...
Arguments:

One or more revision IDs.

Added in:

2.1

Purpose:

Prints all revisions which are ancestors of all of the revisions given as arguments.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one common ancestor of all the given revisions. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

The output will include one of the argument revisions only if that revision is an ancestor of all other revisions given as arguments.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate content_diff [--revision=id1 [--revision=id2]] [--reverse] [file...]
Arguments:

See the online help for more options.

One or more file arguments restrict the diff output to these files, otherwise all changed files in the given revision(s) and/or current workspace are considered.

If zero or more revisions are given, the command behaves as follows:

  • no revision: the diff is done from the parent (base) revision of this workspace to the workspace revision.
  • one revision: the diff is done from the given revision id1 to the workspace revision. If --reverse is given, the order is reversed.
  • two revisions: the diff is done from id1 to id2; no workspace is needed in this case.
Changes:
  • 9.0 – added --with-header option
  • 4.0 – initial
Purpose:

Prints the content changes between two revisions or a revision and the current workspace. This command differs from mtn diff in that it only outputs content changes and keeps quiet on renames or drops by default, as the header of mtn diff is omitted unless --with-header is given and is omitted regardless if there are no changes.

Sample output:
============================================================
--- guitone/res/i18n/guitone_de.ts      9857927823e1d6a0339b531c120dcaadd22d25e9
+++ guitone/res/i18n/guitone_de.ts      0b4715dc296b1955b0707923d45d79ca7769dd3f
@@ -1,6 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE TS><TS version="1.1">
 <context>
+    <name>AncestryGraph</name>
+    <message>
[...]
Output format:

The GNU unified diff format. If there have been no content changes, the output is empty.

Error conditions:

If more than two revisions are given or a workspace is required, but not found, prints to stderr and exits with status 1. If one or more file restrictions can’t be applied, the command prints to stderr and exits as well.

mtn automate descendents rev...
Arguments:

One or more revision IDs.

Added in:

0.1

Purpose:

Prints the descendants of one or more revisions.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one descendant of the given revisions. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

The output does not include rev..., unless one of them is a descendent of another.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate drop_attribute path [key]
Arguments:

A path and an attribute key (optional).

Added in:

5.0

Purpose:

Automate variant of mtn attr drop.

Removes an attribute from the current workspace revision for the specified path. If no attribute key is given, all attributes of this path are removed. Note that this change is not committed.

Output format:

This command does not print out anything if successful.

Error conditions:

If the path specified is unknown in the new workspace revision or the attribute key is not found for this path, prints an error message to stderr and exits with status 1.

mtn automate drop_db_variables domain [name]
Arguments:

The domain and name specify the database variable which should be dropped. If name is ommitted, all database variables in the domain are dropped.

Added in:

7.0

Purpose:

Drops one or more database variables; see Vars.

Sample usage:
mtn automate drop_db_variables known-servers
Output format:

No output.

Error conditions:

If the specific variable or any variables in the given domain are not found, prints to stderr and exits with status 1.

mtn automate drop_public_key keyid
Arguments:

keyid identifies the key to drop, by name or hash.

Changes:
  • 13.0 – initial
Purpose:

Drop a public key from the database (not the private key from the keystore). Signatures made with the key can no longer be verified.

This command should be used with caution as changes are irreversible without a backup of the key(s) that were dropped. You may wish to use the k: selector to check if the key is used in a signature.

Note that public keys that are used to sign a revision may be restored to the database by a future sync.

Keys in the keystore are not dropped because that is very dangerous on a server. The only way to drop private keys on a server is via the command mtn dropkey.

Sample output:

None.

Output format:

None on the main stream; progress message on the progress stream.

Error conditions:

If the key does not exist, an error message is printed on the error stream.

mtn automate erase_ancestors [rev...]
Arguments:

One or more revision IDs.

Added in:

0.1

Purpose:

Prints all arguments, except those that are an ancestor of some other argument.

One way to think about this is that it prints the minimal elements of the given set, under the ordering imposed by the “child of” relation. Another way to think of it is if the arguments formed a branch, then we would print the heads of that branch. If there are no arguments, prints nothing.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one of the given revisions. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate erase_descendants [rev...]
Arguments:

One or more revision IDs.

Added in:

13.1

Purpose:

Prints all arguments, except those that are a descendant of some other argument.

One way to think about this is that it prints the minimal elements of the given set, under the ordering imposed by the “parent of” relation. Another way to think of it is if the arguments formed a branch, then we would print the roots of that branch. If there are no arguments, prints nothing.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one of the given revisions. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate file_merge left-rid left-path right-rid right-path
Arguments:

left-rid, left-fid, right-rid, right-fid specify two files to merge, by revision and file path.

Added in:

9.0

Purpose:

Prints the result of the internal line merge on the contents of the specified files.

This command does not just take two file ids, because the revision ids and paths are needed to check for manual merge and file encoding attributes.

Sample output:
If you've downloaded a release, see INSTALL for installation
instructions.  If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.

"make html" for docs, or read the .info file and / or man page.
Output format:

The file merge results are output without modification.

Error conditions:

If either revision id is unknown or invalid, or if either path does not exist, or if the internal line merger fails, prints an error message to stderr and exits with status 1.

mtn automate generate_key name passphrase
Aguments

name is the name to associate with the new key, and passphrase is the passphrase that will be used to encrypt the private half.

Changes:
  • 13.0 – renamed from genkey to generate_key
  • 10.0 – The separate hashes for the private half of a key really didn’t make much sense; have one hash [...] line instead of separate public_hash [...] and private_hash [...] lines.
  • 3.1 – initial
Purpose:

Generate a key with the given name and passphrase.

Sample output:
            name "tbrownaw@gmail.com"
            hash [475055ec71ad48f5dfaf875b0fea597b5cbbee64]
 public_location "database" "keystore"
private_location "keystore"

Output format:

A basic_io stanza. The public_location and private_location items may have multiple values as shown above for public_location, one value for each place that the key is stored.

Error conditions:

Error conditions: If the passphrase is empty or the key already exists, prints an error message to stderr and exits with status 1.

mtn automate get_attributes [--revision=id] path
Arguments:

The argument path determines which path’s attributes should be printed.

Changes:
  • 13.1 – add the possibility to specify a revision for the operation
  • 11.0 – removed the format_version stanza
  • 5.0 – renamed from attributes to get_attributes
  • 3.0 – initial
Purpose:

Prints all attributes of the given file in the given revision (default current workspace revision), and the attribute states.

Sample output:
 attr "foo" "bar"
state "added"

 attr "baz" "bat"
state "dropped"

 attr "foobar" "foobat"
state "unchanged"
Output format:

There is one basic_io stanza for each attribute of the given file.

All stanzas are formatted by basic_io. Stanzas are separated by a blank line and ordered by attribute name. Values will be escaped, ’\’ to ’\\’ and ’"’ to ’\"’.

Each attribute stanza also contains another entry which tells the status of attribute. This entry can have one of the following four values:

  • added: the attribute has just been added to the file
  • dropped: the attribute has just been dropped from the file
  • unchanged: the attribute has not been changed since the last revision
  • changed: the attribute has been changed since the last revision

The status ’changed’ can come up if an attribute foo has been dropped and added afterwards with another value, like

$ mtn attr drop file.txt foo ; mtn attr set file.txt foo baz

If an attribute has been dropped, the output will still return the previously set value of the dropped attribute for convenience (obviously this is no longer recorded in the current workspace).

If attributes from a specific revision are queried, then all the file’s attribute states are set to unchanged.

The complete format:

'attr':
      represents an attribute.
      format: ('attr', key, value), ('state', [unchanged|changed|added|dropped])
      occurs: zero or more times
Error conditions:

If the path specified is unknown in the workspace, prints an error message to stderr and exits with status 1.

mtn automate get_base_revision_id
Arguments:

None.

Added in:

2.0

Purpose:

Prints the base revision id of the current workspace. This is the “old_revision” value stored in _MTN/revision.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
Output format:

One line containing the base revision ID of the current workspace.

Error conditions:

If no workspace is found, prints an error message to stderr, and exits with status 1.

mtn automate get_content_changed rev file
Arguments:

The rev specifies a revision ID, from which content change calculations will be based. and file specifies the file for which to calculate revisions in which it was last changed.

Added in:

4.0

Purpose:

Returns a list of revision IDs in which the content was most recently changed, relative to the revision ID specified as rev. This equates to a content mark following the *-merge algorithm.

Sample output:
  content_mark [276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f]
Output format:

Zero or more basic_io stanzas, each specifying a revision ID in which a content mark is set:

  • No content mark is returned if file is a directory.
  • One content mark is returned if file is a file and has recently been changed exclusively in one revision (be it by a commit or merge).
  • Multiple content marks are returned if file is a file and has recently been part of a clean merge case. A clean merge happens when the same change to file is made on both sides of the particular merge, together with other unrelated changes, which make the resulting revisions not collapse into one revision.
Error conditions:

If rev or file is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_corresponding_path source_id file target_id
Arguments:

The source_id specifies a revision ID in which file is extant. and file specifies the file whose name in target_id is to be determined; target_id specifies a revision ID.

Added in:

4.0

Purpose:

Given a the file name file in the source revision source_id, a filename will if possible be returned naming the file in the target revision target_id. This allows the same file to be matched between revisions, accounting for renames and other changes.

Sample output:
file "foo"
Output format:

Zero or one basic_io lines. Zero lines will be output if the file does not exist within the target revision; this is not considered an error. If the file does exist in the target revision, a single line is output.

Error conditions:

If the revision IDs source_id or target_id are unknown or invalid prints an error message to stderr and exits with status 1. If the file path file does not exist in the revision source_id or is invalid, prints an error message to stderr and exits with status 1. Note that file not existing in the revision target_id is not an error.

mtn automate get_current_revision [--exclude excl] [--depth=depth] [path...]
Arguments:

One or more path arguments restrict the revision to these paths, otherwise all changes in workspace are taken into account.

See online help for more options.

Added in:

7.0

Purpose:

Prints change information for the current workspace, optionally restricted by one or more paths.

Sample output:

See mtn automate get_revision

Output format:

See mtn automate get_revision

Error conditions:

If the command is executed outside of a workspace, or the restriction is invalid, prints an error message to stderr and exits with status 1.

mtn automate get_current_revision_id
Arguments:

None.

Added in:

2.0

Purpose:

Prints the revision id of the current workspace. This is the id of the revision that would be committed by an unrestricted commit in the workspace.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
Output format:

One line containing the current revision id ID of the current workspace.

Error conditions:

If no workspace is found, prints an error message to stderr, and exits with status 1.

mtn automate get_db_variables [domain]
Arguments:

The optional domain restricts the output to variables only within this domain.

Changes:
  • 7.0 – converted output to basic_io, renamed to ’get_db_variables’
  • 4.1 – added as ’db_get’
Purpose:

Outputs database variable domains, names and values. For more information about variables, see Vars.

Sample output:
domain "database"
 entry "default-exclude-pattern" ""
 entry "default-include-pattern" "net.venge.monotone*"
 entry "default-server" "mtn://code.monotone.ca/monotone"

domain "known-servers"
 entry "mtn://code.monotone.ca/monotone" "2c88403f0ed546df96ccec57ab3072aa73a05e71"
Output format:

basic_io-formatted stanzas. Each stanza starts with a ’domain’, followed by one or more ’entry’ lines. Each ’entry’ contains the name and the value of the respective database variable.

Error conditions:

If the domain is unknown or no variables where found, prints an error message to stderr and exits with status 1.

mtn automate get_extended_manifest_of revid
Arguments:

The revid specifies the revision for which the extended manifest should be printed.

Changes:

13.0 – initial

Purpose:

Prints the contents of the extended manifest associated with the given revision.

Sample output:
      dir ""
    birth [0cd607d6dda3a2df18f777112947f3c70811581e]
path_mark [0cd607d6dda3a2df18f777112947f3c70811581e]

         dir "dir"
dormant_attr "dirprop"
       birth [0cd607d6dda3a2df18f777112947f3c70811581e]
   path_mark [0cd607d6dda3a2df18f777112947f3c70811581e]
   attr_mark "dirprop" [a7a71d7cc0d526165e7362b8a87393d8609f40c2]

        file "file"
     content [d3395867d05cc4c27f013d6e6f48d644e96d8241]
        size "8"
        attr "fileprop" "value"
       birth [0cd607d6dda3a2df18f777112947f3c70811581e]
   path_mark [0cd607d6dda3a2df18f777112947f3c70811581e]
content_mark [a7a71d7cc0d526165e7362b8a87393d8609f40c2]
   attr_mark "fileprop" [a7a71d7cc0d526165e7362b8a87393d8609f40c2]
Output format:

There is one basic_io stanza for each file or directory in the extended manifest.

The ’dir’ and ’file’ lines are the first in every stanza and specify its type as follows:

'dir':
      Represents a directory.  The path "" (the empty string) is used
      to represent the root of the tree.
      format: ('dir', pathname)
      occurs: one or more times
'file':
      Represents a file.
      format: ('file', pathname)
      occurs: zero or more times

In addition, both ’dir’ and ’file’ stanzas include more information on the particular node:

'birth':
      The revision id in which the node was added ("born").
      format: ('birth', revision id)
      occurs: once per node
'path_mark':
      The revision id in which the node was last renamed.
      format: ('path_mark', revision id)
      occurs: once per node
'content':
      The id of the file node, i.e. the hash of its contents.
      format: ('content', file id)
      occurs: once per file node
'content_mark':
      The revision id in which the node's content was changed at last.
      format: ('content_mark', revision id)
      occurs: once per file node
'size':
      The recorded file size, in bytes.
      format: ('size', size in bytes)
      occurs: once per file node

Finally, attributes are also part of the format:

'attr':
      The name and the value of a specific attribute.
      format: ('attr', attribute name, attribute value)
      occurs: zero or more times per node
'dormant_attr':
      The name of a previously deleted attribute.
      format: ('dormant_attr', attribute name)
      occurs: zero or more times per node
'attr_mark':
      The revision id in which a particular attribute's value was
      changed at last.
      format: ('attr_mark', attribute name, revision id)
      occurs: zero or more times per node

All stanzas are sorted by the path string.

Error conditions:

If the revision ID specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_file id
Arguments:

The id argument specifies the file hash of the file to be output.

Added in:

1.0

Purpose:

Prints the contents of the specified file.

Sample output:
If you've downloaded a release, see INSTALL for installation
instructions.  If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.

"make html" for docs, or read the .info file and / or man page.
Output format:

The file contents are output without modification.

Error conditions:

If the file id specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_file_of filename [--revision=id]
Arguments:

The filename argument specifies the filename of the file to be output.

If a revision id is given, the file’s contents in that specific revision are printed. If no revision is given, the workspace base revision is used.

Added in:

4.0

Purpose:

Prints the contents of the specified file.

Sample output:
If you've downloaded a release, see INSTALL for installation
instructions.  If you've checked this out, the generated files are not
included, and you must use "autoreconf --install" to create them.

"make html" for docs, or read the .info file and / or man page.
Output format:

The file contents are output without modification.

Error conditions:

If the filename specified is unknown in the given revision or invalid, or if the given revision is unknown, prints an error message to stderr and exits with status 1.

mtn automate get_file_size id
Arguments:

The id argument specifies the file hash of the file for which the size should be printed.

Changes:

13.0 – initial

Purpose:

Prints the recorded file size of the specified file.

If you need to know the file sizes of multiple files of the same revision, its usually faster to use the mtn automate get_extended_manifest_of command.

Sample output:
1241
Output format:

The size of the file in bytes followed by a linefeed character (’\n’).

Error conditions:

If the file id specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_manifest_of [revid]
Arguments:

Specifying the optional revid argument outputs the manifest for the revision with the specified ID. Otherwise, outputs the manifest for the current workspace.

Added in:

2.0

Purpose:

Prints the contents of the manifest associated with the given revision.

Sample output:
format_version "1"

dir ""

   file ".htaccess"
content [e3915658cb464d05f21332e03d30dca5d94fe776]

   file "AUTHORS"
content [80d8f3f75c9b517ec462233e155f7dfb93379f67]

   file "ChangeLog"
content [fc74a48c7f73eedcbe1ea709755fbe819b29736c]
Output format:

There is one basic_io stanza for each file or directory in the manifest.

'format_version'
      used in case this format ever needs to change.
      format: ('format_version', the string "1")
      occurs: exactly once
'dir':
      represents a directory.  The path "" (the empty string) is used
      to represent the root of the tree.
      format: ('dir', pathname)
      occurs: one or more times
'file':
      represents a file.
      format: ('file', pathname), ('content', file id)
      occurs: zero or more times

In addition, ’dir’ and ’file’ stanzas may have attr information included. These are appended to the stanza below the basic dir/file information, with one line describing each attr. These lines take the form (’attr’, attr name, attr value).

Stanzas are sorted by the path string.

Error conditions:

If the revision ID specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_option option
Arguments:

The option argument specifies the option name of the option to be output.

Added in:

3.1

Purpose:

Prints an option from _MTN/option of the current workspace.

Sample output:
net.venge.monotone
Output format:

The option value is written out without modification.

Error conditions:

If the option is unknown, prints an error message to stderr and exits with status 1.

mtn automate get_public_key keyid
Arguments:

keyid identifies the key to display, by name or hash.

Added in:

13.0

Purpose:

Same as mtn pubkey; print the key in packet format, suitable for reading by mtn automate put_public_key.

Sample output:
[pubkey foo@bar.com]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQs4OEcqULwepphO5Rsb/aSLpiEryGtEkQRNQPNFxvcu1rwVnNKRxep1KCDrwV3se9f4hUQ8zz73NQggS82guSI/YuyXZDZHrw+v3YgAMV/mKGnAjgYnyRNUL1xCywV7fnqTduBBqkDEVSCqphWlii/gFB/PVo4sbJ4Hk7O6ujWwIDAQAB
[end]
Output format:

See example.

Error conditions:

If the key does not exist, an error message is printed on the error stream.

mtn automate get_revision id
Arguments:

The argument id specifies the revision id for which the changeset information should be printed.

Changes:
  • 7.0 – id is now mandatory
  • 1.0 – initial
Purpose:

Prints change information for the specified revision id.

Sample output:
format_version "1"

new_manifest [bfe2df785c07bebeb369e537116ab9bb7a4b5e19]

old_revision [429fea55e9e819a046843f618d90674486695745]

patch "ChangeLog"
 from [7dc21d3a46c6ecd94685ab21e67b131b32002f12]
   to [234513e3838d423b24d5d6c98f70ce995c8bab6e]

patch "std_hooks.lua"
 from [0408707bb6b97eae7f8da61af7b35364dbd5a189]
   to [d7bd0756c48ace573926197709e53eb24dae5f5f]
Output format:

There are several changes that are described; each of these is described by a different basic_io stanza. The first string pair of each stanza indicates the type of change represented.

'format_version'
      used in case this format ever needs to change.
      format: ('format_version', the string "1")
      occurs: exactly once
'new_manifest'
      represents the new manifest associated with the revision.
      format: ('new_manifest', manifest id)
      occurs: exactly one
'old_revision'
      represents a parent revision.
      format: ('old_revision', revision id)
      occurs: either one or two times
'delete
      represents a file or directory that was deleted.
      format: ('delete', path)
      occurs: zero or more times
'rename'
      represents a file or directory that was renamed.
      format: ('rename, old filename), ('to', new filename)
      occurs: zero or more times
'add_dir'
      represents a directory that was added.
      format: ('add_dir, path)
      occurs: zero or more times
'add_file'
      represents a file that was added.
      format: ('add_file', path), ('content', file id)
      occurs: zero or more times
'patch'
      represents a file that was modified.
      format: ('patch', filename), ('from', file id), ('to', file id)
      occurs: zero or more times
'clear'
      represents an attr that was removed.
      format: ('clear', filename), ('attr', attr name)
      occurs: zero or more times
'set'
      represents an attr whose value was changed.
      format: ('set', filename), ('attr', attr name), ('value', attr value)
      occurs: zero or more times

These stanzas will always occur in the order listed here; stanzas of the same type will be sorted by the filename they refer to. The ’delete’ and following stanzas will be grouped under the corresponding ’old_revision’ one.

Error conditions:

If the revision specified is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate get_workspace_root
Arguments:

None.

Added in:

8.0

Purpose:

Print the path of the workspace root for the current directory.

Sample output:
/home/jim/juice
Output format:

A path.

Error conditions:

If the current directory isn’t part of a workspace, prints an error to stderr and exits with status 1.

mtn automate graph
Arguments:

None.

Added in:

0.2

Purpose:

Prints out the complete ancestry graph of this database.

Sample output:
0c05e8ec9c6af4224672c7cc4c9ef05ae8bdb794
27ebcae50e1814e35274cb89b5031a423c29f95a 5830984dec5c41d994bcadfeab4bf1bf67747b89
4e284617c80bec7da03925062a84f715c1b042bd 27ebcae50e1814e35274cb89b5031a423c29f95a 657c756d24fb65213d59f4ae07e117d830dcc95b
Output format:

Zero or more lines, each giving ancestry information for one revision. Each line begins with a revision ID. Following this are zero or more space-prefixed revision IDs. Each revision ID after the first is a parent (in the sense of mtn automate parents) of the first. For instance, in the above sample output, 0c05e8ec9c6af4224672c7cc4c9ef05ae8bdb794 is a root node, 27ebcae50e1814e35274cb89b5031a423c29f95a has one parent, and 4e284617c80bec7da03925062a84f715c1b042bd has two parents, i.e., is a merge node.

The output as a whole is alphabetically sorted by line; additionally, the parents within each line are alphabetically sorted.

Error conditions:

None.

mtn automate heads [branch]
Arguments:

One branch name. If none is given, the workspace branch is used.

Added in:

0.0

Purpose:

Prints the heads of branch branch.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one head of the given branch. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

If the given branch does not exist, an error message is printed.

mtn automate identify path
Arguments:

A file path.

Added in:

4.3

Purpose:

Prints the file ID (aka hash) of the given file.

Sample output:
6265ab1312fbe38bdc3aafa92441139cb2b779b0
Output format:

A single line with the file’s ID, in hexadecimal, followed by a newline.

Error conditions:

If the file does not exist, is a special file or not readable, prints an error message to stderr and exits with status 1. A single file path only consisting of "-" is disallowed since it collides with the UNIX stdin marker.

mtn automate interface_version
Arguments:

None.

Added in:

0.0

Purpose:

Prints version of the automation interface. Major number increments whenever a backwards incompatible change is made to any automate command; minor number increments whenever any change is made (but is reset when major number increments).

Sample output:
1.2
Output format:

A decimal number, followed by “.” (full stop/period), followed by a decimal number, followed by a newline. The first decimal number is the major version, the second is the minor version.

Error conditions:

None.

mtn automate inventory [options...] [files...]
Arguments:

One or more file paths (optional). If present, only show an inventory for the given files or directories (and their sub-directories); otherwise, show an inventory for the current workspace.

--depth=n

Maximum number of directories to descend.

--exclude=exclude-glob

File or directory to exclude.

--[no-]corresponding-renames

If restricted to a renamed path, do not output the corresponding old / new paths for this restriction.

--[no-]ignored

Don’t output ignored files or directories.

--[no-]unchanged

Don’t output files that are known but not changed in any way.

--[no-]unknown

Don’t output unknown directories.

Changes:
  • 8.0 – added the output of the birth key
  • 7.0 – added options --no-ignored, --no-unknown, --no-unchanged and --no-corresponding-renames
  • 6.0 – converted to basic_io format (restriction support, various fixes)
  • 1.0 – initial, line-based format
Purpose:

Prints information on every file found in the workspace or its associated base and revision manifests.

Sample output:

All basic status cases:

    path "added"
new_type "file"
 fs_type "file"
  status "added" "known"
 changes "content"

    path "attributes_altered"
old_type "file"
new_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "known"
 changes "attrs"

    path "dropped"
old_type "file"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "dropped"

   path "ignored~"
fs_type "file"
 status "ignored"

    path "missing"
old_type "file"
new_type "file"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "missing"

    path "original"
old_type "file"
new_path "renamed"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

    path "patched"
old_type "file"
new_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "known"
 changes "content"

    path "patched_and_attributes_altered"
old_type "file"
new_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "known"
 changes "content" "attrs"

    path "renamed"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "known"

    path "unchanged"
old_type "file"
new_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "known"

   path "unknown"
fs_type "file"
 status "unknown"

Two files swapped in both the revision manifest and the workspace:

    path "original"
old_type "file"
new_path "unchanged"
new_type "file"
old_path "unchanged"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"

    path "unchanged"
old_type "file"
new_path "original"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"

Recorded in the revision manifest that two files were swapped, but they were not actually swapped in the workspace. Thus they both appear as patched:

    path "original"
old_type "file"
new_path "unchanged"
new_type "file"
old_path "unchanged"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"
 changes "content"

    path "unchanged"
old_type "file"
new_path "original"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"
 changes "content"

Rename (in the manifest and the workspace) foo to bar; add (in the manifest and the workspace) new file foo:

    path "foo"
old_type "file"
new_path "bar"
new_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "added" "known"

    path "bar"
new_type "file"
old_path "foo"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "known"

Rotated files foo -> bar -> baz -> foo (in the manifest and the workspace):

    path "foo"
old_type "file"
new_path "bar"
new_type "file"
old_path "baz"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"

    path "bar"
old_type "file"
new_path "baz"
new_type "file"
old_path "foo"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"

    path "baz"
old_type "file"
new_path "foo"
new_type "file"
old_path "bar"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"

Recorded in the revison manifest the rotation of files foo -> bar -> baz -> foo, but the actual files in the workspace were not moved, so monotone interprets all files as having been patched:

    path "foo"
old_type "file"
new_path "bar"
new_type "file"
old_path "baz"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"
 changes "content"

    path "bar"
old_type "file"
new_path "baz"
new_type "file"
old_path "foo"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"
 changes "content"

    path "baz"
old_type "file"
new_path "foo"
new_type "file"
old_path "bar"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "rename_target" "known"
 changes "content"

Dropped from the manifest but not removed in the workspace and thus unknown:

    path "dropped"
old_type "file"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "dropped" "unknown"

Added in the manifest but not in the workspace, and thus missing:

    path "added"
new_type "file"
 fs_type "none"
  status "added" "missing"

Recorded a rename in the manifest, but not moved in the workspace, and thus unknown source and missing target:

    path "original"
old_type "file"
new_path "renamed"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source" "unknown"

    path "renamed"
new_type "file"
old_path "original"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "missing"

Moved in the workspace but no rename recorded in the manifest, and thus missing source and unknown target:

    path "original"
old_type "file"
new_type "file"
 fs_type "none"
  status "missing"

   path "renamed"
fs_type "file"
 status "unknown"

Renamed in the manifest and the workspace and patched:

    path "original"
old_type "file"
new_path "renamed"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

    path "renamed"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "known"
 changes "content"

Renamed and restricted to original or renamed:

    path "original"
old_type "file"
new_path "renamed"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

    path "renamed"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "known"
 changes "content"

Renamed and restricted to original with the --no-corresponding-renames option:

    path "original"
old_type "file"
new_path "renamed"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

Renamed and restricted to renamed with the --no-corresponding-renames option:

    path "renamed"
new_type "file"
old_path "original"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "known"
 changes "content"

File is missing, an unversioned directory is in the way:

    path "missing_file"
old_type "file"
new_type "file"
 fs_type "directory"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "invalid"
 changes "content"

Directory is missing, an unversioned file is in the way:

    path "missing_directory"
old_type "directory"
new_type "directory"
 fs_type "file"
  status "invalid"

Directory source renamed to target, target is missing, an unversioned file is in the way:

    path "source"
old_type "directory"
new_path "target"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

    path "source/a"
old_type "file"
new_path "target/a"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_source"

    path "target"
new_type "directory"
old_path "source"
 fs_type "file"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "invalid"

    path "target/a"
new_type "file"
old_path "source/a"
 fs_type "none"
   birth [cb271687054afd3c2b873c8994f206f08fb240d3]
  status "rename_target" "missing"
Output format:

Each path is printed in one basic_io stanza. Stanzas are separated by a blank line. Each stanza starts with a path line, and contains up to seven lines.

path

The file or directory path, relative to the workspace root. The file either exists in the workspace, or is listed in the base or revision manifest. path is always output.

old_type

The type of the node in the base manifest. “type” is either file or directory. old_type is output for all old nodes (i.e. unchanged or dropped paths and rename sources).

new_type

The type of the node in the revision manifest. “type” is either file or directory. new_type is output for all new nodes (i.e. unchanged or added paths and rename targets).

fs_type

The type of the node in the workspace (also called the filesystem). “type” is either file, directory or none (if the path does not exist in the file system). fs_type is always output.

old_path

The old path for the node, if it has been renamed in the revision manifest. old_path is only output for rename targets.

new_path

The new path for the node, if it has been renamed in the revision manifest. new_path is only output for rename sources.

birth

The identify of the revision that the node was first added in. birth is only output if it exists in a committed revision.

status

status is always output. Its value is one or more of:

rename_source

path is part of a rename and denotes the old name of a renamed node.

rename_target

path is part of a rename and denotes the new name of a renamed node.

added

path has been added in the revision manifest, but not existent in the base manifest.

dropped

path has been deleted in the revision manifest and the workspace.

missing

path has been deleted in the workspace, but still exists in the revision manifest.

A file will also be labeled missing if it is in a directory that is ignored due to a regular expression in .mtn-ignore, but is also in the revision manifest. A warning is issued in this case.

ignored

path is ignored by monotone.

known

path exists in the workspace, and in the revision manifest.

unknown

path exists in the workspace, but not in the revision manifest, i.e. is unversioned.

invalid

path is versioned and exists in the workspace and revision manifest, but with incompatible types (a versioned missing file is replaced by an unversioned directory and vice versa).

changes
content

The contents of a file have been changed.

attrs

The attributes of a path (file or directory) have been changed.

Error conditions:

When executed from outside of a workspace directory, prints an error message to stderr, and exits with status 1.

mtn automate keys
Arguments:

None.

Changes:
  • 11.0 – Instead of having a "name" item, there are "given_name" and "local_name" items.
  • 10.0 – The separate hashes for the private half of a key really didn’t make much sense; have one hash [...] line instead of separate public_hash [...] and private_hash [...] lines.
  • 1.1 – initial
Purpose:

Print all keys in basic_io format.

Sample output:
            hash [475055ec71ad48f5dfaf875b0fea597b5cbbee64]
      given_name "tbrownaw@gmail.com"
      local_name "tbrownaw@gmail.com"
 public_location "database" "keystore"
private_location "keystore"

           hash [3ac4afcd86af28413b0a23b7d22b9401e15027fc]
      given_name "tomfa@debian.org"
      local_name "tomfa@debian.org"
public_location "database"

            hash [115fdc73d87a5e9901d018462b21a1f53eca33a1]
      given_name "underwater@fishtank.net"
      local_name "underwater@fishtank.net"
 public_location "keystore"
private_location "keystore"

Output format:

For each key, a basic_io stanza is printed. The public_location and private_location items may have multiple values as shown above for public_location, one value for each place that the key is stored. If the private key does not exist, then the private_hash and private_location items will be absent. given_name is the name provided when the key was created, and local_name is the name returned by the get_local_key_name hook.

The keys are ordered by hash value.

Error conditions:

None.

mtn automate leaves
Arguments:

None.

Added in:

0.1

Purpose:

Prints the leaves of the revision graph, i.e. all revision that have no children.

This is similar, but not identical to the functionality of mtn automate heads, which prints every revision in a branch, that has no descendants in that branch. If every revision in the database was in the same branch, then they would be identical. Generally, every leaf is the head of some branch, but not every branch head is a leaf.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each a leaf of the revision graph. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

None.

mtn automate log [options] [pathname...]
Arguments:

[–depth=n] [–exclude=path...] [–last=n] [–next=n] [–from=id...] [–clear-from] [–to=id...] [–clear-to] [–[no-]merges] [pathname...]

Same as mtn log, but without the output control options; see mtn log.

Added in:

12.2

Purpose:

Print the selected revisions on stdout, in topological order. The user can then use other automate commands to retrieve additional information about each revision.

Sample output:
233afb8c4832bf33d5f5734225164de5f5a6278c
4a368a6b217c40b2ff3b12bb7cfa00987e0f191c
233afb8c4832bf33d5f5734225164de5f5a6278c
Output format:

One revision per line.

Error conditions:

See mtn log.

mtn automate lua function_name [function_args...]
Arguments:

A valid Lua function name and zero or more function arguments. Note that string arguments need to be wrapped in another pair of quotes, i.e. "foo" or 'foo' will not work, but "'foo'" or '"foo"' will.

A function arguments can be any valid Lua expression, including nested tables and functions, like f.e. {1,true,{['func'] = function(...) return ... end }}

Added in:

9.0

Purpose:

Call Lua functions, like monotone hooks, in the monotone context, f.e. to retrieve user defaults like keys, passwords, ignorable files and more.

Output format:

A string dump of the return value of the function, in Lua code. The Lua types function, thread, userdata and lightuserdata are not serialized, but set to nil in the dump.

Please note that nil values in tables are not printed since Lua does not distinguish between unset and not existing entries in a table like other programming languages do.

Sample output:

A single string return value:

[1] = "Output";

Two numeric return values:

[1] = 3;
[2] = 4.4;

A nested table:

[1] = {
    ["bar"] = {
        [1] = 1;
        [2] = 2;
        [3] = 3;
    };
};

A callback function:

[1] = nil --[[function]];
Error conditions:

This command prints an error message and exists with status 1 if the function does not exist, one or more function arguments could not be evaluated or the function could not be called for another reason.

mtn automate packet_for_fdata id
Arguments:

The id specifies the file for which to output an fdata packet.

Added in:

2.0

Purpose:

Prints the file data in packet format

Sample output:
[fdata 229c7f621b65f7e4970ae5aaec993812b9daa1d4]
H4sIAAAAAAAA/z2OO27DMBBEe51ioMaNrJzBpQAjTXKBBTW0CJPcgFw6yO1DCkG62Q/em83j
R9vlRez6naPKzh2CwkipXFBJbO8fn7f7HV4LQq4mMYoFzdMYSnMj1xXY/lnuoHt2kB2hQpst
PREPZhaxvvchskIKkdU6xsXWvQsk76MOUquGVolZmmmh0+xxvf7JZ5jCFXbU4KZ1muYkT+Kw
FOez5q6uLuh9+9eoQawhez3Fp+VtHJNkfMmDHfALzWYfcAgBAAA=
[end]
Output format:

File data in mtn read compatible packet format.

Error conditions:

If id is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate packet_for_fdelta from-id to-id
Arguments:

from-id specifies the file to use as the base of the delta, and to-id specifies the file to use as the target of the delta.

Added in:

2.0

Purpose:

Prints the file delta in packet format.

Sample output:
[fdelta 597049a62d0a2e6af7df0b19f4945ec7d6458727
        229c7f621b65f7e4970ae5aaec993812b9daa1d4]
H4sIAAAAAAAA/0WOy0oEMRBF9/mKS2/c9LQg4t5lw+BGf6BIKtNhkpSkKop/b9II7m49OOfu
eHp5dnvEj/SHL0aQ75qFAgcQGmcm5RXKjP3t/eP1ekWUhlTVKGeyJNXNoXU/s27AP8sf7O8D
ZEdSSLd1JMaNKzeysY8ps4Iao4oNjM99eFdQDbMOSldDV8ZC3aSxlxpxufzJF5jANx6oyS2b
c0uhO+OwkpezZhCvK0bf8TVrMLZUo5zi0/I4j4UqPunGA+B+AfHvKEIPAQAA
[end]
Output format:

File delta data in mtn read compatible packet format.

Error conditions:

If from-id or to-id is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate packet_for_rdata id
Arguments:

The id specifies the revision to output an rdata packet for.

Added in:

2.0

Purpose:

Prints the revision data in packet format

Sample output:
[rdata bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed]
H4sIAAAAAAAA/0XQS27DMAwE0L1PIfgArb4kte62NzACg5SoJEBsF7aRurev0UVzgJl5mLas
E+/jU9ftvsymd33Xzfo9Tjzfm267GSgGwVarz6Valx0KtFYwii9VqUFCqJQ5X7puedRx1ef9
r2rwHlSbi+BUSrF4xn1p0RInkmxTbmwREp/BL97LzfQfN56v+rlc+860dZnMED01jhILkURJ
Ul0KPpGN1ueUwDHyiXF66Ywx+2IGD+0Uqg8aCzikAEzZNRXPmJKlkhMxSHuNzrofx/uq2/J4
6njV/bZsu/zMPOlbOY4XJSD5KOrwXGdwpDGdfotZayQHKTAi5fRPqUWKcAMMIQfAjOK0nkfm
6tFacjYgBPV46X4BtlpiNYUBAAA=
[end]
Output format:

Revision data in mtn read compatible packet format.

Error conditions:

If id is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate packets_for_certs id
Arguments:

The id specifies the revision for which to output cert packets.

Added in:

2.0

Purpose:

Prints the certs associated with a revision in packet format

Sample output:
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
       branch
       njs@pobox.com
       bmV0LnZlbmdlLm1vbm90b25l]
K90i1XHHmaMEMuwbPifFweLThJl0m7jigh2Qq6Z7TBwNJ6IMOjXWCizv73cacZ1CtzxFDVwQ
SlqhNWiPQWxdcMp+Uuo+V8IFMKmvxVSTuVDukLMuNAQqpGL5S+a+tEj68NMq+KLKuL8kAAPc
RoFD7GQlTS35S3RHWA4cnvqn+8U=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
       date
       njs@pobox.com
       MjAwNi0wNC0wOFQxMTo1MDowMA==]
araz9A8x6AlK6m6UhwnhUhk7cdyxeE2nvzj2gwaDvkaBxOq4SN23/wnaPqUXx1Ddn8smzyRY
HN08xloYc0yNChp3wjbqx20REcsTg3XE4rN/sgCbqqw5hVT22a5ZhqkfkDeoeJvan0R0UBax
ngKYo9eLuABNlmFX2onca75JW1E=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
       author
       njs@pobox.com
       bmpzQHBvYm94LmNvbQ==]
BLPOYhgLsAN+w7CwOsv9GfXnG3u7RNF1DTrWdn0AnYE1e+ptgTeMVWUI18H4OGL0B7wm08rv
Pxk/hvsb8fBn1Kf5HDDO2pbjJ0xVzI9+p+TR0y5jJNZlVSTj+nvtPgvK9NzsdooYWnwlWmJv
bOkAzQcZb8NMh8pbQkdHbR5uzMo=
[end]
[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed
       changelog
       njs@pobox.com
       MjAwNi0wNC0wOCAgTmF0aGFuaWVsIFNtaXRoICA8bmpzQHBvYm94LmNvbT4KCgkqIG5ldHh4
L3Jlc29sdmVfZ2V0aG9zdGJ5bmFtZS5jeHggKHJlc29sdmVfaG9zdG5hbWUpOiAjaWZkZWYg
b3V0CglXaW4zMi1pbmNvbXBhdGlibGUgZXJyb3IgcmVwb3J0aW5nIGNhbGwuCg==]
Ncl4L/oEPctzVQixTKA6FrLceeHnLiXfeyeFDNmtUFYg9BMUcjWkeyKmaWknLvOcHortxjto
K6pQ9E8S7zI+TpzFAhssg5a///rFL0+2GJU3t6pcHs6LC0Q4tbqzwKd/5+8GwT1gphbM1wm7
KuzKthwqD3pp49GbgTrp8iWMTr0=
[end]
Output format:

Cert data in mtn read compatible packet format.

Error conditions:

If id is unknown or invalid prints an error message to stderr and exits with status 1.

mtn automate parents rev
Arguments:

One revision ID.

Added in:

0.2

Purpose:

Prints the immediate parents of a revision. This is like a non-recursive version of mtn automate ancestors.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one parent of the given revision. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

If the given revision rev does not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate pull [--[no-]set-default] [--dry-run] [uri]
mtn automate push [--[no-]set-default] [--dry-run] [--keys-to-push=key] [uri]
mtn automate sync [--[no-]set-default] [--dry-run] [--keys-to-push=key] [uri]
mtn automate pull [--[no-]set-default] [address] [glob [...] [--exclude=exclude-glob]]] deprecated
mtn automate push [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated
mtn automate sync [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated
Arguments:

The automate versions of pull, push and sync have the same set of arguments and options as the non-automate versions. See Network for a full explanation.

Changes:
  • 13.0 – add sent/received revision, cert, and key output; add –dry-run.
  • 12.0 – added
Purpose:

Pushes, pulls or syncs (push & pull) revisions, certificates and keys of the given database to, from or with the given netsync server.

Sample output:

The following is example main channel data, non-dry-run:

receive_cert "test"
       value "value"
         key [05c26b6cb109ca39bc48bbbdce83564c97796155]
    revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

receive_revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

 receive_cert "branch"
        value "foo"
          key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
     revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

 receive_cert "changelog"
        value "R1
"
          key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
     revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

 receive_cert "date"
        value "2010-09-01T12:00:00"
          key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
     revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

 receive_cert "author"
        value "tester@test.net"
          key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
     revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

receive_key [111808abc306fd7423b564f2a8ef5c09745b87d2]

send_cert "test"
    value "value"
      key [05c26b6cb109ca39bc48bbbdce83564c97796155]
 revision [114f6aa58c7707bf83516d4080ca6268c36640ad]

send_revision [2a46f4b909071fae756b4911a247ce3ff1c3c4ce]

send_cert "branch"
    value "foo2"
      key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
 revision [2a46f4b909071fae756b4911a247ce3ff1c3c4ce]

send_cert "changelog"
    value "R2
"
      key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
 revision [2a46f4b909071fae756b4911a247ce3ff1c3c4ce]

send_cert "date"
    value "2010-09-01T12:00:00"
      key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
 revision [2a46f4b909071fae756b4911a247ce3ff1c3c4ce]

send_cert "author"
    value "tester@test.net"
      key [46ec58576f9e4f34a9eede521422aa5fd299dc50]
 revision [2a46f4b909071fae756b4911a247ce3ff1c3c4ce]

send_key [05c26b6cb109ca39bc48bbbdce83564c97796155]

The following is example dry-run main channel data:

        estimate
receive_revision "0"
    receive_cert "0"
     receive_key "0"
   send_revision "1"
       send_cert "5"
        send_key "0"
     send_branch "foo2" "1"

The following shows the progress and ticker data for a pull which transferred two revisions and eight certs.

Note: The linebreaks are not part of the actual format, but have been added for better readability.

0:p:62:doing anonymous pull; use -kKEYNAME if you need authentication
0:p:46:connecting to mtn://code.monotone.ca/monotone0:0:p:29:finding items to synchronize:
0:t:34:c:certificates;k:keys;r:revisions;
0:t:12:c=0;k=0;r=0;
0:t:13:c#0;k#0;r#64;
0:t:14:c#0;k#0;r#128;
[...]
0:t:6:c;k;r;
0:t:44:>:bytes in;<:bytes out;c:certs in;r:revs in;
0:t:16:>=0;<=0;c=0;r=0;
0:t:21:>#420;<#1344;c#0;r#0;
0:t:22:>#1165;<#1741;c#0;r#0;
[...]
0:t:24:>#20839;<#14882;c#0;r#1;
0:t:24:>#20839;<#14882;c#3;r#1;
0:t:24:>#20839;<#14882;c#4;r#2;
0:t:24:>#20839;<#14882;c#6;r#2;
0:t:24:>#20863;<#14930;c#8;r#2;
0:t:8:<;>;c;r;
0:p:36:successful exchange with mtn://code.monotone.ca/monotone
0:l:1:0
Output format:

Output consists of sent and received revisions, certs, and keys in the main stdio channel, progress messages, and ticker data for bytes, revisions, certs and keys.

For non-dry-run, all stanzas are optional; they are only output if the data they describe is transferred.

A partial order is imposed, that the parser can use in deciding how to store the data. First all certs associated with revisions that are not transferred in this sync are output, then revisions with associated certs, then keys. All received data is output before all sent data.

For each cert not associated with a transmitted revision, there is a stanza giving the cert name, value, key, and revision.

For each revision, there is a stanza containing the revision id, followed by a stanza containing the cert name, value, key, and revision id for each cert associated with the revision.

For each key, there is one stanza containing one line giving the key id.

If run outside of automate stdio, the progress and ticker output of these commands is equal to the normal netsync command progress and ticker output.

If these commands are run over stdio, the stdio ticker format is used (for a description of this format, see mtn automate stdio).

The following ticker types are printed out during the refinement phase:

  • c: The number of certs found for an upcoming synchronization
  • k: The number of keys found for an upcoming synchronization
  • r: The number of revisions found for an upcoming synchronization

After refinement the actual synchronization between the two nodes start. The ticker stanzas in this phase are the following:

  • >: The number of incoming bytes
  • <: The number of outgoing bytes
  • c: The number of incoming certs (only pull and sync)
  • C: The number of outgoing certs (only push and sync)
  • r: The number of incoming revisions (only pull and sync)
  • R: The number of outgoing revisions (only push and sync)

For dry-run, one stanza is output, with optional lines giving the revision, cert, and key counts for send and receive. Under some circumstances, the number of keys that would be received is only an estimate; in that case, the symbol estimate is output. For send, the branch names of sent revisions are also output. Note that in the branch list, revisions that have multiple branch certs are listed twice, so the sum of the revision counts in the branch list may be greater than the number of revisions transferred.

Error conditions:

If a netsync error occurs, the command outputs an error and exits with status 1.

mtn automate put_file [base-id] contents
Arguments:

The optional base-id specifies a file-id on which the contents are based. This is used for delta encoding. contents are the contents of the new file.

If base-id is not given, the file is a new file, and no delta is stored.

Added in:

4.1

Purpose:

Preparation of a workspace-less commit. See mtn automate put_revision.

Sample output:
70a0f283898a18815a83df37c902e5f1492e9aa2
Output format:

The sha1 sum of the contents, hex encoded.

Error conditions:

If the optional base id is unknown prints an error message to stderr and exits with status 1.

mtn automate put_public_key key-packet-data
Arguments:

A data packet, key-packet-data, as produced by mtn automate get_public_key.

Changes:

13.0 – initial

Purpose:

Store public keys into the database.

Note that this duplicates part of mtn automate read_packets; the intent is to deprecate automate read_packets, and only keep facilities for key packets.

Output format:

No output.

Error conditions:

An error will be produced if the argument is not a valid key packet.

mtn automate put_revision revision-data
Arguments:

revision-data is the new revision.

Added in:

4.1

Purpose:

Workspace-less commit.

Note that the new_manifest entry is ignored – put_revision will ignore whatever you put here and calculate the correct manifest id itself. (However, for now, you must put 40 hex digits here – it’s just that which particular digits you put are entirely irrelevant. All zeros is a good choice.) Monotone will also canonicalize your whitespace automatically. You do not need to worry about getting just the right amount of indentation in front of each line. However, everything else about your revision must be valid.

Sample argument:
format_version "1"

new_manifest [0000000000000000000000000000000000000004]

old_revision []

add_dir ""

add_file "foo"
content [5bf1fd927dfb8679496a2e6cf00cbe50c1c87145]
Sample output:
4c2c1d846fa561601254200918fba1fd71e6795d
Output format:

The new revision id, hex encoded.

Error conditions:

If the changeset is invalid prints an error message to stderr and exits with status 1. May abort on invalid formats. If the revision is already present in the database, prints a message to stderr noting this fact, but otherwise works as normal.

mtn automate read_packets packet-data
Arguments:

A data packet, packet-data, as produced by mtn pubkey.

Added in:

9.0

Purpose:

Store public keys (and incidentally anything else that can be represented as a packet) into the database.

Output format:

No output.

Error conditions:

An error will be produced if the argument is not a valid packet.

mtn automate remote [--remote-stdio-host=host] [--[no-]set-default] command args-and-opts
Arguments

A command and its arguments, to execute on the remote server specified by the --remote-stdio-host option (defaults to server stored in the database). If options are to be passed to the command, they must be preceded by -- to prevent them from being interpreted as local options.

Remote options must be given as a single token, ie --branch=foo or -bfoo. This is because the local and remote monotones may not understand exactly the same options (so the local monotone cannot know if an option given as --branch or -b should be followed by an argument), and because the server sees this as an automate remote_stdio connection (so it expects the options to already be parsed).

Added in

12.0

Purpose

Permit a single automate command to be run against a database that is being used to serve netsync connections, without having its input and output encoded as by automate stdio.

Input/Output Format

This command does not accept input.

The output will be whatever output the remote command generates.

Remote diagnostic messages are written to standard error, prefixed either with mtn: remote error:, mtn: remote warning: or mtn: remote message: to make them distinguishable from local diagnostics. Tickers are not supported over this interface. If you need remote ticker support, see mtn automate remote_stdio.

Error Conditions

If the remote command returns a nonzero error code, will exit with code 1 and print "received remote error code N" to standard error, with "N" being the remote error code.

Notes

If no database is specified, a :memory: database is used.

On the server side the get_remote_automate_permitted hook has to be configured to include every command which should be executable over this interface.

Keyboard interaction is disabled on the server, just as if --non-interactive would have been specified on server startup. Actions which require operations on password-encrypted private keys will therefor fail unless a get_passphrase hook is set up remotely.

mtn automate remote_stdio [hostname]
Arguments

hostname is the host (and optionally port) of the monotone server process to connect to. If not given, the default server is used.

Added in

12.0

Purpose

Permit automate commands to be run against a database that is being used to serve netsync connections.

Input/Output format

This command takes input and produces output in exactly the same format as automate stdio. Note that the commands run with automate remote_stdio may conform to a different interface_version, because they are handled by a remote instance of monotone.

There will be some extra chatter on stderr unless --quiet is given.

Error Conditions

If left idle for too long or there are network problems, the connection to the server may be dropped. This will not be detected while monotone is waiting for input. Instead, when a complete command has been entered and monotone tries to send it to the remote server it will print a message to stderr and exit with code 1.

Notes

If no database is specified, a :memory: database is used.

On the server side the get_remote_automate_permitted hook has to be configured to include every command which should be executable over this interface.

For both, the client and the server, keyboard interaction is disabled, just as if --non-interactive is specified. Actions which require operations on password-encrypted private keys will therefor fail unless the get_passphrase hook is set up locally and / or remotely.

mtn automate roots
Arguments:

None.

Added in:

4.3

Purpose:

Prints the roots of the revision graph, i.e. all revisions that have no parents.

Sample output:
276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f
Output format:

Zero or more lines, each a root of the revision graph. Each line consists of a revision ID, in hexadecimal, followed by a newline. The lines are printed in alphabetically sorted order.

Error conditions:

None.

mtn automate select selector
Arguments:

One selector (or combined selector).

Added in:

0.2

Purpose:

Print all revisions that match the given selector.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

Zero or more lines, each giving the ID of one revision that matches the given selector. Each line consists of a revision ID, in hexadecimal, followed by a newline. Revision ids are printed in alphabetically sorted order.

Error conditions:

None.

mtn automate set_attribute path key value
Arguments:

A path, an attribute key and an attribute value.

Added in:

5.0

Purpose:

Edits the current workspace revision and inserts the given attribute key and value for the specified path. Note that this change is not committed and therefor behaves exactly like mtn attr set key value.

Output format:

This command does not print out anything if successful.

Error conditions:

If the path specified is unknown in the new workspace revision, prints an error message to stderr and exits with status 1.

mtn automate set_db_variable domain name value
Arguments:

The domain and name specify the database variable which is changed to value.

Changes:
  • 7.0 – renamed to ’set_db_variable’
  • 4.1 – added as ’db_set’
Purpose:

Change a database variable; see Vars.

Sample usage:
mtn automate set_db_variable database default-server off.net
Output format:

No output.

Error conditions:

None.

mtn automate show_conflicts [--branch BRANCH] [left_rev right_rev]
Arguments:

Optional left and right revision ids.

If no revs are given, they default to the first two heads that would be chosen by the merge command for the current branch. If no workspace is present, the branch may be given by the –branch option.

Changes:
  • FIXME: – Add reporting and resolution for dropped/modified conflicts.
  • 11.0 – Add resolution for orphaned node conflicts. Deleted resolved_user conflict resolution; use resolved_*_left for single file conflicts. Add resolved_keep_left, resolved_keep_right resolutions.
  • 9.0 – Added default resolution for file content conflicts, user resolutions for others. directory_loop_created changed to directory_loop.
  • 8.0 – initial
Purpose:

Show all conflicts between two revisions.

This is intended to be used before a merge; an external tool can guide the user thru resolving each conflict in turn, then do the merge.

The same file format is output by the conflicts store command, which also allows specifying user conflict resolutions. The file syntax for the resolutions is given here, so an external tool can set them directly.

For more information on conflicts, see Merge Conflicts.

Note that this cannot be used to show conflicts that would occur in an update, since in that case one revision is the workspace.

Sample output:

The output starts by listing the revisions and their common ancestor:

    left [532ab5011ea9e64aa212d4ea52363b1b8133d5ba]
   right [b94a03a922c2c281a88d8988db64e76a32edb6a1]
ancestor [ead03530f5fefe50c9010157c42c0ebe18086559]

If there are no conflicts, the ancestor revision is not output, and no conflict stanzas are output.

Attribute changed in both branches, or dropped in one:

        conflict attribute
       node_type "file"
       attr_name "attr1"
   ancestor_name "foo"
ancestor_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
       left_name "foo"
    left_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
 left_attr_value "valueX"
      right_name "foo"
   right_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
right_attr_value "valueZ"

        conflict attribute
       node_type "file"
       attr_name "attr2"
   ancestor_name "foo"
ancestor_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
       left_name "foo"
    left_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
 left_attr_value "valueY"
      right_name "foo"
   right_file_id [bab2022ff2ed13501a8a83bcc6bd53f5042141be]
right_attr_state "dropped"

Missing root directory:

     conflict missing_root
    left_type "pivoted root"
ancestor_name "foo"
   right_type "deleted directory"
ancestor_name "foo"

Directory deleted and/or renamed:

     conflict orphaned_directory
   right_type "deleted directory"
ancestor_name ""
    left_type "renamed directory"
ancestor_name ""
    left_name "bar"

     conflict orphaned_file
   right_type "deleted directory"
ancestor_name "foo"
    left_type "added file"
    left_name "foo/baz"
 left_file_id [f5122a7f896cb2dd7ecaa84be89c94ab09c15101]

        conflict orphaned_file
      right_type "deleted directory"
   ancestor_name "foo"
       left_type "renamed file"
   ancestor_name "bar"
ancestor_file_id [ac4c6d06436632e017bb7d3ea241734e8899f8ce]
       left_name "foo/baz"
    left_file_id [ac4c6d06436632e017bb7d3ea241734e8899f8ce]

     conflict multiple_names
    left_type "renamed directory"
ancestor_name ""
    left_name "aaa"
   right_type "renamed directory"
ancestor_name ""
   right_name "bbb"

     conflict duplicate_name
    left_type "renamed directory"
ancestor_name "foo"
    left_name ""
   right_type "renamed directory"
ancestor_name "bar"
   right_name ""

     conflict multiple_names
    left_type "renamed directory"
ancestor_name "foo"
    left_name "a/foo"
   right_type "renamed directory"
ancestor_name "foo"
   right_name "b/foo"

Directory loop created:

     conflict directory_loop
    left_type "renamed directory"
ancestor_name "foo"
    left_name "bar/foo"
   right_type "renamed directory"
ancestor_name "bar"
   right_name "foo/bar"

File content changed (this may be resolvable by the internal line merger), file also renamed:

         conflict content
        node_type "file"
    ancestor_name "bar"
 ancestor_file_id [f0ef49fe92167fe2a086588019ffcff7ea561786]
        left_name "bar"
     left_file_id [08cd878106a93ce2ef036a32499c1432adb3ee0d]
       right_name "bar"
    right_file_id [0cf419dd93d38b2daaaf1f5e0f3ec647745b9690]
resolved_internal

        conflict content
       node_type "file"
   ancestor_name "foo"
ancestor_file_id [50bf338804db2685a575124c8c8371d06b65c523]
       left_name "bar"
    left_file_id [f1bb6fff2ad16d67143d89fc374ede7abec5d437]
      right_name "baz"
   right_file_id [b966b2d35b99e456cb0c55e4573ef0b1b155b4a9]

resolved_internal is a conflict resolution. If the file contents in the two revs can be successfully merged by the internal line merger, resolved_internal is output.

File added and/or renamed:

     conflict duplicate_name
    left_type "added file"
    left_name "bar"
 left_file_id [ba4637112ee3e55a6106d647d6c4e04a6643f8eb]
   right_type "added file"
   right_name "bar"
right_file_id [fe6d523f607e2f2fc0f0defad3bda0351a95a337]

        conflict duplicate_name
       left_type "renamed file"
   ancestor_name "foo"
ancestor_file_id [c6864a8456855c48afe83488a47501fe8b94bd57]
       left_name "bar"
    left_file_id [c6864a8456855c48afe83488a47501fe8b94bd57]
      right_type "added file"
      right_name "bar"
   right_file_id [c809d71002ec57a2f1d10221f05993012a491436]

        conflict duplicate_name
       left_type "renamed file"
   ancestor_name "foo"
ancestor_file_id [918f3642b57a5e2dd13ee874e3dc2518a53ab4b4]
       left_name "abc"
    left_file_id [918f3642b57a5e2dd13ee874e3dc2518a53ab4b4]
      right_type "renamed file"
   ancestor_name "bar"
ancestor_file_id [bdf46a521d5f1dd54c31dda15e99ff6b0c80394a]
      right_name "abc"
   right_file_id [bdf46a521d5f1dd54c31dda15e99ff6b0c80394a]

File renamed to different names:

        conflict multiple_names
       left_type "renamed file"
   ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
       left_name "bar"
    left_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
      right_type "renamed file"
   ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
      right_name "baz"
   right_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]

File dropped and modified (and possibly renamed):

        conflict dropped_modified
   ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
       left_type "dropped file"
        left_rev [b0d6953684d49dd6bd345c312d6a0c8fed3078ce]
       left_name "foo"
    left_file_id [420cde699a422f7c3d2c8951c46ddfd546db66c0]
      right_type "modified file"
      right_name "baz"
   right_file_id [fe6d523f607e2f2fc0f0defad3bda0351a95a337]

Here left_name, left_file_id are from left_rev, just before the file was dropped.

File orphaned and modified (and possibly renamed):

        conflict dropped_modified
   ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
       left_type "orphaned file"
        left_rev [b0d6953684d49dd6bd345c312d6a0c8fed3078ce]
       left_name "foo"
    left_file_id [420cde699a422f7c3d2c8951c46ddfd546db66c0]
      right_type "modified file"
      right_name "baz"
   right_file_id [fe6d523f607e2f2fc0f0defad3bda0351a95a337]

Orphaned/modified is different from dropped/modified because the possible resolutions are different; orphaned requires a rename if the file is kept.

File dropped and recreated on one side; modified on the other (and possibly renamed):

        conflict dropped_modified
   ancestor_name "foo"
ancestor_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
       left_type "recreated file"
       left_name "foo"
    left_file_id [e80910e54d0bdea1b6d295ada320b87aaf9fdc23]
      right_type "modified file"
      right_name "baz"
   right_file_id [fe6d523f607e2f2fc0f0defad3bda0351a95a337]

Invalid file name (_MTN in root directory):

     conflict invalid_name
    left_type "pivoted root"
ancestor_name "foo"
   right_type "added directory"
   right_name "foo/_MTN"

        conflict invalid_name
       left_type "pivoted root"
   ancestor_name "foo"
      right_type "renamed file"
   ancestor_name "bad/_MTN"
ancestor_file_id [629d9e5d254241abf4b46f108fb53189e314e41d]
      right_name "foo/_MTN"
   right_file_id [629d9e5d254241abf4b46f108fb53189e314e41d]

Revisions that don’t share a common ancestor:

    left [161e426c3b0c3f98d0be225f69d6f893ce8e0442]
   right [0e3260f51acd1e98c40666557eb6c0eefeae5f02]
ancestor []

conflict missing_root

  conflict duplicate_name
 left_type "added directory"
 left_name ""
right_type "added directory"
right_name ""

All possible conflict resolutions:

   resolved_drop_left
  resolved_drop_right
   resolved_keep_left
  resolved_keep_right
    resolved_internal
 resolved_rename_left file
resolved_rename_right file
   resolved_user_left file
  resolved_user_right file

For single file conflicts, the resolved_*_left resolution name is used.

See Conflicts, for more information on conflict resolutions.

Output format:

First the revision ids of the left and right revisions, and their common ancestor, are printed in one basic_io stanza.

Then each conflict is listed in a basic_io stanza. Stanzas are separated by blank lines.

Each conflict stanza starts with a conflict line, and contains up to eleven lines. The order of the lines is not important, and may change in future revisions, except that the first line will always be conflict.

When the conflicts involve files, the file ids are output, so the file contents can be retrieved efficiently via automate get_file, to aid in conflict resolution.

Only the resolved_internal conflict resolution is output by this command; the other conflict resolutions are inserted in a conflicts file by conflicts resolve_first or an external tool, and read by merge.

Error conditions:

If the revision IDs are given, but either is unknown or invalid, prints an error message to stderr and exits with status 1.

mtn automate stdio [--automate-stdio-size <size>]
Arguments:

none

Changes:
  • 12.0 – Introduced out of band streams (’e’, ’p’, ’t’, ’w’); the main output of a command now only happens in the ’m’ stream; the ’l’ stream now marks the end of all streams of a command; introduced the concept of "headers" which are output before the first command is issued; specific error codes to distinguish command from interface errors have also been introduced.
  • 3.1 – Added the ’o’ item to the recognized input. This change should not break anything.
  • 1.0 – Initial version.
Purpose:

Allow multiple automate commands to be run from one instance of monotone.

Sample input:
l6:leavese
l7:parents40:0e3171212f34839c2e3263e7282cdeea22fc5378e
o3:key11:foo@bar.come l4:cert40:0e3171212f34839c2e3263e7282cdeea22fc53783:foo3:bare
Input format:
[ 'o' <string> <string> [ <string> <string> [ ... ] ] 'e' ]
'l' <string> [ <string> [ ... ] ] 'e'

The input is a series of commands and options. The command name plus arguments are provided as ’l’ <string> [<string> ...] ’e’, where <string> = <size> colon <data> . This may optionally be preceded by a set of key=value pairs (command options) as ’o’ <string> <string> [<string> <string> ...] ’e’, where strings come in pairs, key followed by value. For flag options that don’t take values, specify the second string as zero length; 0:. The option names do not include the leading --.

The space between the ending ’e’ of one group of strings and the beginning ’l’ or ’o’ of the next is reserved. Any characters other than whitespace will cause an error.

Sample output:
format-version: 2

0:m:41:7706a422ccad41621c958affa999b1a1dd644e79
0:l:1:0
...
1:e:38:misuse: key 'test@test' already exists
1:l:1:2
...
2:w:39:skipping file '\' with unsupported name
2:m:144:    path ""
old_type "directory"
new_type "directory"
 fs_type "directory"
   birth [276264b0b3f1e70fc1835a700e6e61bdbe4c3f2f]
  status "known"
...
3:t:34:c:certificates;k:keys;r:revisions;
3:t:12:c=0;k=0;r=0;
3:t:13:c#0;k#0;r#64;
3:t:14:c#0;k#0;r#128;
3:t:6:c;k;r;
...
Output format:

Right after a stdio session has been set up, header information is issued; to date the only header defined is format-version, which denotes the version of the stdio format used throughout the session. The original format had no such version output, so our numbering starts with "2" here.

Headers are separated from each other by single newline character '\n' and the last is separated from the following output by a pair of newline characters.

After a command has been issued, one or more packets are returned for it. A packet looks like:

<command number>:<stream>:<size>:<output>

Packet size is limited by the --automate-stdio-size option (default 32k bytes).

<command number> is a decimal number specifying which command this output is from. It is 0 for the first command, and increases by one each time.

<stream> is an identifier for which output stream this packet represents, allowing multiple streams to be multiplexed over the channel. The following streams are presently defined; more streams may be added later.

  • m: this stream represents the normal ("main") stdout automate output of the command, formatted as described in the description for that command.
  • e: this stream represents any (unstructured) error message data.

    Internally, this maps to calls to the E() print macros that would normally be written by the command to the program’s stderr stream, if the automate sub-command had been called directly rather than via ”’stdio”’.

  • w: this stream represents any (unstructured) warning message data.

    Internally, this maps to calls to the W() print macro that would normally be written by the command to the program’s stderr stream, if the automate sub-command had been called directly rather than via ”’stdio”’.

  • p: this stream represents any (unstructured) progress message data.

    Internally, this maps to calls to the P() print macro that would normally be written by the command to the program’s stderr stream, if the automate sub-command had been called directly rather than via ”’stdio”’.

  • t: this stream represents ticker updates, which may be used by a user interface to display the progress of a command.

    The output for this channel can be described as follows:

    • <output> ::= <definition><payload><end>
    • <definition> ::= <shortname> ':' <longname> <eol>
    • <payload> ::= <total_count><advance>+
    • <end> ::= <shortname> <eol>
    • <total_count> ::= <shortname> '=' <count> <eol>
    • <advance> ::= <shortname> '#' <count> <eol>
    • <shortname> ::= "\w+"
    • <longname> ::= "[^;]+"
    • <count> ::= ['0'-'9']+
    • <eol> ::= ';'

    The definition tells the implementor the short name and long name of any upcoming ticker event. The names and meanings are command-specific and are therefore explained in the sections for the particular commands which support ticker output.

    The total_count might be 0 right at the start and can later be changed to a different number if the command later on knows a more exact value. If this is the case, this stanza is output again with this new value. A constant total_count of 0 means that the command may continue to run for a undefined amount of time until the end stanza appears.

    The advance tells the implementor how much work has been done so far.

    Finally, the end stanza is printed just before the ticker ends (i.e. the work has been done).

    All counts output absolute, raw values; no modulation takes place. It is usually the case that definition, total_count, advance and end are output in separate stanzas. It is also possible that two or more parallel tickers output their stanzas at the same time, in this case it’s ensured that the output does not get intermixed; first all definitions are output, afterwards all total_counts, and so on.

    Note: The ticker format used for stdio is fixed and cannot be selected explicitely via the global --ticker option. However, if you run an automate command outside of stdio you can set a different ticker type, f.e. count, dot or none.

  • l: this stream marks the termination of a command and all of its streams and carries the return code of the command in the payload.

    A return code "0" stands for success, "1" for an error which occurred within the stdio interface (f.e. syntax errors or missing privileges) before the command is run and finally "2" for any other command-specific error.

<size> is the number of bytes in the output.

<output> is a piece of the output of the command.

Error conditions:

Errors in the commands run through this interface do not affect the exit status of this command. Instead, if a badly formatted or invalid command is received, or a command is given with invalid arguments or options, an error message to the error stream is printed and and the particular sub-command exits with return code "1". Other command-specific errors are returned as code "2".

Trying to run the automate stdio or automate remote_stdio sub-commands will exit the particular command with return code "1".

Notes:

Keyboard interaction is disabled, just as if --non-interactive is specified. Actions which require operations on password-encrypted private keys will therefore fail unless the get_passphrase hook is set up locally.

Workspace options are read before executing each command.

Multiple streams

The multiple stream encoding allows the output of errors and warnings to be associated with the command that generated them, allows the communication path to always stay in sync, and offers the opportunity to add other stream types for other useful purposes in the future as needs arise.

mtn automate sync

See mtn automate pull

mtn automate tags [branch_pattern]
Arguments:

A branch pattern (defaults to all).

Changes:
  • 11.0 – signer now prints the hash of the signing key, no longer the name. Also, the format_version stanza has been removed in favour of the global interface_version.
  • 2.2 – added
Purpose:

If a branch pattern is given, prints all tags that are attached to revisions on branches matched by the pattern; otherwise prints all tags of the revision graph.

If a branch name is ignored by means of the Lua hook ignore_branch, it is neither printed, nor can it be matched by a pattern.

Sample output:
     tag "monotree-0.1"
revision [8a121346ce2920b6f85df68b3b620de96bd14a8d]
  signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib" "net.venge.monotone.contrib.monotree"

     tag "monotree-0.2"
revision [5d288b39b49613b0d9dca8ece6b9a42c3773f35b]
  signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"

     tag "monotree-0.3"
revision [35cff8e8ba14155f5f7ddf7965073f514fd60f61]
  signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"

     tag "monotree-0.4"
revision [f1afc520474f83c58262896ede027ef77226046e]
  signer [de84b575d5e47254393eba49dce9dc4db98ed42d]
branches "net.venge.monotone.contrib.monotree"
Output format:

There is one basic_io stanza for each tag.

Each stanza has exactly the following four entries:

'tag'

the value of the tag cert, i.e. the name of the tag

'revision'

the hexadecimal id of the revision the tag is attached to

'signer'

the hexadecimal value of the key used to sign the tag cert

'branches'

a (possibly empty) list of all branches the tagged revision is on

Stanzas are printed in arbitrary order.

Error conditions:

A run-time exception occurs if an illegal branch pattern is specified.

mtn automate toposort [rev...]
Arguments:

One or more revision IDs.

Added in:

0.1

Purpose:

Prints all arguments, topologically sorted. I.e., if rev1 is an ancestor of rev2, then rev1 will appear before rev2 in the output; if rev2 is an ancestor of rev1, then rev2 will appear before rev1 in the output; and if neither is an ancestor of the other, then they may appear in either order.

If there are no arguments, prints nothing.

Sample output:
28ce076c69eadb9b1ca7bdf9d40ce95fe2f29b61
75156724e0e2e3245838f356ec373c50fa469f1f
Output format:

A list of revision IDs, in hexadecimal, each followed by a newline.

Error conditions:

If any of the revisions do not exist, prints nothing to stdout, prints an error message to stderr, and exits with status 1.

mtn automate update
Arguments:

Same as mtn update.

Added in:

12.1

Purpose:

Update the current workspace to the latest or given revision; see mtn update.

Sample output:

Nothing on the main stream. The progress stream gives messages of the form:

mtn: updating along branch 'mms.work_stephe'
mtn: selected update target 233afb8c4832bf33d5f5734225164de5f5a6278c
mtn: [left]  4a368a6b217c40b2ff3b12bb7cfa00987e0f191c
mtn: [right] 233afb8c4832bf33d5f5734225164de5f5a6278c
mtn: renaming build/windows_common.make to build/utf_common.make
mtn: adding build/x86_gnu_linux_release
Output format:

Free form, prefixed by “mtn:”.

Error conditions:

see mtn update.


Next: , Previous: , Up: Command Reference   [Contents][Index]

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status