Next: , Previous: Database, Up: Command Reference


5.9 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.

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 the 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, followed by end-of-file. The first decimal number is the major version, the second is the minor version.
Error conditions:
None.

mtn automate heads [branch]
Arguments:
One branch name, branch. If none is given, the current default 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 contains no members or does not exist, then no lines are printed.

mtn automate ancestors rev1 [rev2 [...]]
Arguments:
One or more revision IDs, rev1, rev2, etc.
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 rev1, rev2, etc., except if rev2 is itself an ancestor of rev1, then rev2 will be included in the output.

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 common_ancestors rev1 [rev2 [...]]
Arguments:
One or more revision IDs, rev1, rev2, etc.
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 parents rev
Arguments:
One revision ID, rev.
Added in:
0.2
Purpose:
Prints the immediate parents of a revision. This is like a non-recursive version of 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 descendents rev1 [rev2 [...]]
Arguments:
One or more revision IDs, rev1, rev2, etc.
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 rev1, rev2, etc., except that if rev2 is itself a descendant of rev1, then rev2 will be included in the output.

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 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 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 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 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 erase_ancestors [rev1 [rev2 [...]]]
Arguments:
One or more revision IDs, rev1, rev2, etc.
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 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.
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 toposort [rev1 [rev2 [...]]]
Arguments:
One or more revision IDs, rev1, rev2, etc.
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. 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 ancestry_difference new [old1 [old2 [...]]]
Arguments:
A “new” revision ID new, followed by zero or more “old” revision IDs old1, old2, etc.
Added in:
0.1
Purpose:
Prints all ancestors of the revision new, that are not also ancestors of one of the old revisions. For purposes of this command, “ancestor” is an inclusive term; for example, if new is an ancestor of old1, it will not be printed; but if new is not an ancestor of any of the “old” revisions, then it will be. Similarly, old1 will never be printed, because it is considered to be an ancestor of itself. The reason for the names is that if new a new revision, and old1, old2, etc. are revisions that you have processed before, then this command tells you which revisions are new since then.
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 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 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 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 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 tags [branch_pattern]
Arguments:
A branch pattern (optional).
Added in:
2.2
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:
          format_version "1"
          
               tag "monotree-0.3"
          revision [35cff8e8ba14155f5f7ddf7965073f514fd60f61]
            signer "njs@pobox.com"
          branches "net.venge.monotone.contrib.monotree"
          
               tag "monotree-0.2"
          revision [5d288b39b49613b0d9dca8ece6b9a42c3773f35b]
            signer "njs@pobox.com"
          branches "net.venge.monotone.contrib.monotree"
          
               tag "monotree-0.1"
          revision [8a121346ce2920b6f85df68b3b620de96bd14a8d]
            signer "njs@pobox.com"
          branches "net.venge.monotone.contrib" "net.venge.monotone.contrib.monotree"
          
               tag "monotree-0.4"
          revision [f1afc520474f83c58262896ede027ef77226046e]
            signer "njs@pobox.com"
          branches "net.venge.monotone.contrib.monotree"
     

Output format:
There is one basic_io stanza for each tag.

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

Each stanza has exactly the following four entries:

'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 name 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 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 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 exists, is a special file or not readable, prints an error message to stderr and exists with status 1. A single file path only consisting of "-" is disallowed since it collides with the UNIX stdin marker.

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).
--depth=n
Maximum number of directories to descend.
--exclude=exclude-glob
File or directory to exclude.
--no-ignored
Don't output ignored files or directories.
--no-unknown
Don't output unknown directories.
--no-unchanged
Don't output files that are known but not changed in any way.
--no-corresponding-renames
If restricted to a renamed path, do not output the corresponding old / new paths for this restriction.

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 the inventory of every file found in the workspace or its associated base and revision manifests. Each unique path is listed in a basic_io stanza. Stanzas are separated by blank lines.
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. The order of the lines is not important, and may change in future revisions, except that the first line will always be path.
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 certs id
Arguments:
A revision ID id, for which any certificates will be printed.
Added in:
1.0
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'
                a string indicating 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 "emile@alumni.reed.edu"
          signature "ok"
               name "author"
              value "emile@alumni.reed.edu"
              trust "trusted"
          
                key "emile@alumni.reed.edu"
          signature "ok"
               name "branch"
              value "net.venge.monotone"
              trust "trusted"
          
                key "emile@alumni.reed.edu"
          signature "ok"
               name "changelog"
              value "propagate from branch 'net.venge.monotone.annotate' (head 76a886ef7c8ae12a4bba5fc2bd252557bf863aff)
                      to branch 'net.venge.monotone' (head 2490479a4e4e99243fead6d627d78291fde592f0)
          "
              trust "trusted"
          
                key "emile@alumni.reed.edu"
          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 stdio
Arguments:
none
Changes:
  • 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. The command name plus arguments are provided as 'l' <string> [<string> ...] 'e', where <string> = <size> colon <data> . This may optionally be preceded by a set of key=value pairs (command options) as 'o' <string> <string> [<string> <string> ...] 'e', where strings come in pairs, key followed by value. For flag options that don't take values, specify the second string as zero length; 0:.

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

Sample output:
          0:0:l:205:0e3171212f34839c2e3263e7282cdeea22fc5378
          1f4ef73c3e056883c6a5ff66728dd764557db5e6
          2133c52680aa2492b18ed902bdef7e083464c0b8
          23501f8afd1f9ee037019765309b0f8428567f8a
          2c295fcf5fe20301557b9b3a5b4d437b5ab8ec8c
          1:0:l:41:7706a422ccad41621c958affa999b1a1dd644e79
     

Output format:
The output consists of one or more packets for each command. A packet looks like:

<command number>:<err code>:<last?>:<size>:<output>

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

<err code> is 0 for success, 1 for a syntax error which occurred in stdio scope (before the command is executed), and 2 for a command error.

<last?> is 'l' if this is the last piece of output for this command, and 'm' if there is more output to come.

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

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

All but the last packet for a given command will have the <last?> field set to 'm'.

Error conditions:
If a badly formatted or invalid command is received, or a command is given with invalid arguments or options, prints an error message to standard error and exits with nonzero status. Errors in the commands run through this interface do not affect the exit status. Instead, the <err code> field in the output is set to 2, and the output of the command becomes whatever error message would have been given.

mtn automate genkey 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:
  • 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_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.

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

Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are:

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

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

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

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.

Options excl and depth work just like in mtn commit.

Added in:
7.0
Purpose:
Prints change information for the current workspace, optionally restricted by one or more paths.
Sample output:
See automate get_revision
Output format:
See 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_base_revision_id
Arguments:
None.
Added in:
2.0
Purpose:
Prints the revision id the current workspace is based on. 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 book keeping _MTN directory is found, 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 book keeping _MTN directory is found, prints an error message to stderr, and exits with status 1.

mtn automate get_manifest_of
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. (You can think of leaving the argument blank as meaning “give me the manifest of THIS”.)
Added in:
2.0
Purpose:
Prints the contents of the manifest associated with the given roster.
Sample output:
          format_version "1"
          
          dir ""
          
             file ".htaccess"
          content [e3915658cb464d05f21332e03d30dca5d94fe776]
          
             file "AUTHORS"
          content [80d8f3f75c9b517ec462233e155f7dfb93379f67]
          
             file "ChangeLog"
          content [fc74a48c7f73eedcbe1ea709755fbe819b29736c]
          
             file "LICENSE"
          content [dfac199a7539a404407098a2541b9482279f690d]
          
             file "README"
          content [440eec971e7bb61ccbb61634deb2729bb25931cd]
          
             file "TODO"
          content [e0ea26c666b37c5f98ccf80cb933d021ee55c593]
          
             file "branch.psp"
          content [b28ece354969314ce996f3030569215d685973d6]
          
             file "common.py"
          content [1fdb62e05fb2a9338d2c72ddc58de3ab2b3976fe]
          
             file "config.py.example"
          content [64cb5898e3a026b4782c343ca4386585e0c3c275]
          
             file "error.psp"
          content [7152c3ff110418aca5d23c374ea9fb92a0e98379]
          
             file "fileinbranch.psp"
          content [5d8536100fdf51d505b6f20bc9c16aa78d4e86a8]
          
             file "headofbranch.psp"
          content [981df124a0b5655a9f78c42504cfa8c6f02b267a]
          
             file "help.psp"
          content [a43d0588a69e622b2afc681678c2a5c3b3b1f342]
          
             file "html.py"
          content [18a8bffc8729d7bfd71d2e0cb35a1aed1854fa74]
          
             file "index.psp"
          content [c621827db187839e1a7c6e51d5f1a7f6e0aa560c]
          
             file "monotone.py"
          content [708b61436dce59f47bd07397ce96a1cfabe81970]
          
             file "revision.psp"
          content [a02b1c161006840ea8685e461fd07f0e9bb145a3]
          
             file "rss_feed.gif"
          content [027515fd4558abf317d54c437b83ec6bc76e3dd8]
          
             file "tags.psp"
          content [638140d6823eee5844de37d985773be75707fa25]
          
             file "tarofbranch.psp"
          content [be83f459a152ffd49d89d69555f870291bc85311]
          
             file "test.py"
          content [e65aace9237833ec775253cfde97f59a0af5bc3d]
             attr "mtn:execute" "true"
          
             file "utility.py"
          content [fb51955563d64e628e0e67e4acca1a1abc4cd989]
          
             file "viewmtn.css"
          content [8d04b3fc352a860b0e3240dcb539c1193705398f]
          
             file "viewmtn.py"
          content [7cb5c6b1b1710bf2c0fa41e9631ae43b03424a35]
          
             file "wrapper.py"
          content [530290467a99ca65f87b74f653bf462b28c6cda9]
     

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

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

Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are:

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

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

Stanzas are sorted by the path string.

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_attributes path
Arguments:
The argument path determines which path's attributes should be printed.
Added in:
  • 5.0 – renamed from attributes to get_attributes
  • 3.0 – initial

Purpose:
Prints all attributes of the given file and the attribute states.
Sample output:
          format_version "1"
          
           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).

The complete format:

          'format_version'
                used in case this format ever needs to change.
                format: ('format_version', the string "1")
                occurs: exactly once
          '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 new workspace revision, prints an error message to stderr and exits with status 1.

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 drop_attribute path [key]
Arguments:
A path and an attribute key (optional).
Added in:
5.0
Purpose:
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 and therefor behaves exactly like mtn attr drop path [key].
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 content_diff [--revision=id1 [--revision=id2]] [files ...]
Arguments:
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 between the workspace revision and the parent (base) revision of this workspace
  • one revision: the diff is done between the workspace revision and the given revision id1,
  • two revisions: the diff is done between id1 and 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 way 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 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's 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 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 file id is unknown or invalid, or if the internal line merger fails, 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 keys
Arguments:
None.
Changes:
  • 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:
                      name "tbrownaw@gmail.com"
                      hash [475055ec71ad48f5dfaf875b0fea597b5cbbee64]
           public_location "database" "keystore"
          private_location "keystore"
          
                     name "tomfa@debian.org"
                     hash [3ac4afcd86af28413b0a23b7d22b9401e15027fc]
          public_location "database"
          
                      name "underwater@fishtank.net"
                      hash [115fdc73d87a5e9901d018462b21a1f53eca33a1]
           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. The keys are ordered alphabetically by name.
Error conditions:
None.

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 monotone 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_certs id
Arguments:
The id specifies the revision to output cert packets for.
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 monotone 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_fdata id
Arguments:
The id specifies the file to output an fdata packet for.
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 monotone 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:
The 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 monotone 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 get_content_changed id file
Arguments:
The id 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 id. 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.

The complete format:

          'content_mark'
                   the hexadecimal id of the revision the content mark is attached to
     

Error conditions:
If id 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 current 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 stanzas. Zero stanzas 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 stanza with the following details is output.

The complete format:

             'file'
                   the file name corresponding to "file name" (arg 2) in the target revision
     

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_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:
Reads and outputs database variables. 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" "monotone.ca"
          
          domain "known-servers"
           entry "monotone.ca" "3e6f5225bc2fffacbc20c9de37ff2dae1e20892e"
           entry "monotone.mtn-host.prjek.net" "a52f85615cb2445989f525bf17a603250381a751"
           entry "venge.net" "70a0f283898a18815a83df37c902e5f1492e9aa2"
     

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 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 also Vars.
Sample usage:
          mtn automate set_db_variable database default-server off.net
     

Output format:
No output.
Error conditions:
None.

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 also 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 put_file [base-id] contents
Arguments:
The optional base-id specifies a file-id on which the contents are based on. This is used for delta encoding. contents are the contents of the new file.
Added in:
4.1
Purpose:
Preparation of a workspace-less commit. See also automate put_revision. Normally used via automate stdio.
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_revision revision-data
Arguments:
revision-data is the new revision. See example below. 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.
Added in:
4.1
Purpose:
Workspace-less commit. Normally used via automate stdio.
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 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 stdio capable variant of mtn cert. To sign the cert with a specific private key, use --key.
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 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:
  • 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, 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]
     

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_internal
           resolved_rename_left file
          resolved_rename_right file
                  resolved_user file
             resolved_user_left file
            resolved_user_right file
     

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 get_workspace_root
Arguments:
None.
Added in:
8.0
Purpose:
To show 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 read_packets packet-data
Arguments:
A data packet, packet-data, as produced by mtn pubkey keyname.
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 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.

Complex types are also supported, anything which can be evaluated as valid Lua expression can be given as input, including nested tables and functions, like f.e. {1,true,{['func'] = function(...) return ... end }}

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.