NAME¶

monotone - a distributed version control system

SYNOPSIS¶

mtn [options...] command [arguments...]

DESCRIPTION¶

monotone is a highly reliable, very customizable distributed version control system that provides lightweight branches, history-sensitive merging and a flexible trust setup. monotone has an easy-to-learn command set and comes with a rich interface for scripting purposes and thorough documentation. For more information on monotone, visit http://www.monotone.ca. The complete documentation, including a tutorial for a quick start with the system, can be found online on http://www.monotone.ca/docs.

GLOBAL OPTIONS¶

--confdir <arg>

set location of configuration directory

--date-format <arg>

strftime(3) format specification for printing dates

--db [ -d ] <arg>

set name of database

--dump <arg>

file to dump debugging log to, on failure

--help [ -h ]

display help message

--ignore-suspend-certs / --no-ignore-suspend-certs

do not ignore revisions marked as suspended

--key [ -k ] <arg> / --use-default-key

sets the key for signatures, using either the key name or the key hash

--keydir <arg>

set location of key store

--log <arg>

file to write the log to

--no-builtin-rcfile / --builtin-rcfile

do not load the built-in lua file with the default hooks

--no-default-confdir / --allow-default-confdir

forbid use of the default confdir

--no-format-dates

print date certs exactly as stored in the database

--no-standard-rcfiles / --standard-rcfiles

do not load '~/.monotone/monotonerc' or '_MTN/monotonerc' lua files

--no-workspace / --allow-workspace

don't look for a workspace

--non-interactive / --interactive

do not prompt the user for input

--quiet [ -q ]

decrease verbosity (undo previous '-v', then disable informational output, then disable warnings)

--rcfile <arg> / --clear-rcfiles

load extra lua file

--root <arg>

limit search for workspace to specified root

--ssh-sign <arg>

controls use of ssh-agent. valid arguments are: 'yes' to use ssh-agent to make signatures if possible, 'no' to force use of monotone's internal code, 'only' to force use of ssh-agent, 'check' to sign with both and compare

--ticker <arg>

set ticker style (count|dot|none)

--timestamps

show timestamps in front of errors, warnings and progress messages

--verbose [ -v ]

increase verbosity (undo previous '-q', and then enable debug output)

--version

print version number, then exit

--xargs [ -@ ] <arg>

insert command line arguments taken from the given file

 

COMMANDS¶

command group 'automation'¶

Commands that aid in scripted execution.

automate ancestors REV1 [REV2 [REV3 [...]]]

Prints the ancestors of the given revisions.

automate ancestry_difference NEW_REV [OLD_REV1 [OLD_REV2 [...]]]

Lists the ancestors of the first revision given, not in the others.

automate branches

Prints all branch certs in the revision graph.

automate cert REVISION-ID NAME VALUE

Adds a revision certificate.

automate certs REV

Prints all certificates attached to a revision.

automate checkout [DIRECTORY]

Checks out a revision from the database into a directory. If a revision is given, that's the one that will be checked out. Otherwise, it will be the head of the branch (given or implicit). If no directory is given, the branch name will be used as directory.

automate children REV

Prints the children of a revision.

automate common_ancestors REV1 [REV2 [REV3 [...]]]

Prints revisions that are common ancestors of a list of revisions.

automate content_diff [FILE [...]]

Calculates diffs of files.

automate descendents REV1 [REV2 [REV3 [...]]]

Prints the descendents of the given revisions.

automate drop_attribute PATH [KEY]

Drops an attribute or all of them from a certain path.

automate drop_db_variables DOMAIN [NAME]

Drops a database variable.

automate drop_public_key KEY_NAME_OR_HASH

Drops a public key.

automate erase_ancestors [REV1 [REV2 [REV3 [...]]]]

Erases the ancestors in a list of revisions.

automate file_merge LEFT_REVID LEFT_FILENAME RIGHT_REVID RIGHT_FILENAME

Prints the results of the internal line merger, given two child revisions and file names.

automate generate_key KEY_NAME PASSPHRASE

Generates an RSA key-pair.

automate get_attributes PATH

Prints all attributes for the specified path.

automate get_base_revision_id

Shows the revision on which the workspace is based.

automate get_content_changed REV FILE

Lists the revisions that changed the content relative to another revision.

automate get_corresponding_path REV1 FILE REV2

Prints the name of a file in a target revision relative to a given revision.

automate get_current_revision [PATHS ...]

Shows change information for a workspace.

automate get_current_revision_id

Shows the revision of the current workspace.

automate get_db_variables [DOMAIN]

Retrieve database variables.

automate get_extended_manifest_of REVISION

Prints the extended manifest for the given identifier.

automate get_file FILEID

Prints the contents of a file (given an identifier).

automate get_file_of FILENAME

Prints the contents of a file (given a name).

automate get_file_size FILEID

Prints the size of a file (given an identifier).

automate get_manifest_of [REVID]

Shows the manifest associated with a revision.

automate get_option OPTION

Shows the value of an option.

automate get_public_key KEY_NAME_OR_HASH

Prints a public key packet.

automate get_revision REVID

Shows change information for a revision.

automate get_workspace_root

Prints the workspace root for the current directory.

automate graph

Prints the complete ancestry graph.

automate heads [BRANCH]

Prints the heads of the given branch.

automate identify PATH

Prints the file identifier of a file.

automate interface_version

Prints the automation interface's version.

automate inventory [PATH]...

Prints a summary of files found in the workspace.

automate keys

Lists all keys in the keystore.

automate leaves

Lists the leaves of the revision graph.

automate log [PATH] ...

Lists the selected revision history.

automate lua LUA_FUNCTION [ARG1 [ARG2 [...]]]

Executes the given lua function and returns the result.

automate packet_for_fdata FILEID

Prints the file data in packet format.

automate packet_for_fdelta OLD_FILE NEW_FILE

Prints the file delta in packet format.

automate packet_for_rdata REVID

Prints the revision data in packet format.

automate packets_for_certs REVID

Prints the certs associated with a revision in packet format.

automate parents REV

Prints the parents of a revision.

automate pull [URI]

automate pull [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Pulls branches from a netsync server.

automate push [URI]

automate push [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Pushes branches to a netsync server.

automate put_file [FILEID] CONTENTS

Stores a file in the database.

automate put_public_key KEY-PACKET-DATA

Store the public key in the database.

automate put_revision REVISION-DATA

Stores a revision into the database.

automate read_packets PACKET-DATA

Load the given packets into the database.

automate remote COMMAND [ARGS]

Executes COMMAND on a remote server.

automate remote_stdio [URI]

automate remote_stdio [ADDRESS[:PORTNUMBER]]

Opens an 'automate stdio' connection to a remote server.

automate roots

Lists the roots of the revision graph.

automate select SELECTOR

Lists the revisions that match a selector.

automate set_attribute PATH KEY VALUE

Sets an attribute on a certain path.

automate set_db_variable DOMAIN NAME VALUE

Sets a database variable.

automate show_conflicts [LEFT_REVID RIGHT_REVID]

Shows the conflicts between two revisions. If no arguments are given, LEFT_REVID and RIGHT_REVID default to the first two heads that would be chosen by the 'merge' command.

automate stdio

Automates several commands in one run.

automate sync [URI]

automate sync [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Synchronizes branches with a netsync server.

automate tags [BRANCH_PATTERN]

Prints all tags attached to a set of branches.

automate toposort [REV1 [REV2 [REV3 [...]]]]

Topologically sorts a list of revisions.

automate update

Updates the workspace.

command group 'database'¶

Commands that manipulate the database.

db changesetify

Converts the database to the changeset format.

db check

Does some sanity checks on the database. Ensures that the database is consistent by issuing multiple checks.

db dump

Dumps the contents of the database. Generates a list of SQL instructions that represent the whole contents of the database. The resulting output is useful to later restore the database from a text file that serves as a backup.

db execute

Executes an SQL command on the database. Directly executes the given SQL command on the database

db fix_certs

Attempt to fix bad certs. Older monotone versions could sometimes associate certs with the wrong key. This fixes such certs if you have the correct key, and can optionally drop any certs that you don't have the correct key for. This should only be needed if you had such certs in your db when upgrading from 0.44 or earlier, or if you loaded such certs with 'mtn read'.

db info

Shows information about the database.

db init

Initializes a database. Creates a new database file and initializes it.

db load

Loads the contents of the database. Reads a list of SQL instructions that regenerate the contents of the database. This is supposed to be used in conjunction with the output generated by the 'dump' command.

db migrate

Migrates the database to a newer schema. Updates the database's internal schema to the most recent one. Needed to automatically resolve incompatibilities that may be introduced in newer versions of monotone.

db regenerate_caches

Regenerates the caches stored in the database.

db rosterify

Converts the database to the rosters format.

db set_epoch BRANCH EPOCH

Sets the branch's epoch.

db version

Shows the database's version.

local kill_certs SELECTOR CERTNAME [CERTVAL]

Deletes the specified certs from the local database. Deletes all certs which are on the given revision(s) and have the given name and if a value is specified then also the given value.

local kill_revision REVID

Kills a revision from the local database.

command group 'debug'¶

Commands that aid in program debugging.

asciik SELECTOR

Prints an ASCII representation of the revisions' graph.

fdiff SRCNAME DESTNAME SRCID DESTID

Differences 2 files and outputs the result.

fload

Loads a file's contents into the database.

fmerge PARENT_FILEID LEFT_FILEID RIGHT_FILEID

Merges 3 files and outputs the result.

get_roster [REVID]

Dumps the roster associated with a given identifier. If no REVID is given, the workspace is used.

identify [PATH]

Calculates the identity of a file or stdin. If any PATH is given, calculates their identity; otherwise, the one from the standard input is calculated.

rcs_import RCSFILE...

Parses versions in RCS files. This command doesn't reconstruct or import revisions. You probably want to use cvs_import.

command group 'informative'¶

Commands for information retrieval.

annotate PATH

Prints an annotated copy of a file. Calculates and prints an annotated copy of the given file from the specified REVISION.

bisect bad

Marks the current revision or specified revisions as bad. Known bad revisions are removed from the set being searched.

bisect good

Marks the current revision or specified revisions as good. Known good revisions are removed from the set being searched.

bisect reset

Reset the current bisection search. Update the workspace back to the revision from which the bisection was started and remove all current search information, allowing a new search to be started.

bisect skip

Excludes the current revision or specified revisions from the search. Skipped revisions are removed from the set being searched. Revisions that cannot be tested for some reason should be skipped.

bisect status

Reports on the current status of the bisection search. Lists the total number of revisions in the search set, the number of revisions that have been determined to be good or bad, the number of revisions that have been skipped and the number of revisions remaining to be tested.

bisect update

Updates the workspace to the next revision to be tested by bisection. This command can be used if updates by good, bad or skip commands fail due to blocked paths or other problems.

cat FILENAME

Prints a file from the database. Fetches the given file FILENAME from the database and prints it to the standard output.

complete (revision|file|key) PARTIAL-ID

Completes a partial identifier.

di [PATH]...

diff [PATH]...

Shows current differences. Compares the current tree with the files in the repository and prints the differences on the standard output. If one revision is given, the diff between the workspace and that revision is shown. If two revisions are given, the diff between them is given. If no format is specified, unified is used by default.

help command [ARGS...]

Displays help about commands and options.

list branches [PATTERN]

Lists branches in the database that match a pattern.

list certs REVID

Lists certificates attached to a revision.

list changed [PATH...]

Lists files that have changed with respect to the current revision.

list databases

list dbs

Lists managed databases and their known workspaces.

list duplicates

Lists duplicate files in the specified revision. If no revision is specified, use the workspace.

list epochs [BRANCH [...]]

Lists the current epoch of branches that match a pattern.

list ignored [PATH]

Lists workspace files that are ignored in the current branch.

list keys [PATTERN]

Lists keys that match a pattern.

list known

Lists workspace files that belong to the current branch.

list missing

Lists files that belong to the branch but are not in the workspace.

list tags [PATTERN]

Lists all tags in the database.

list unknown [PATH]

Lists workspace files that are unknown in the current branch.

list vars [DOMAIN]

Lists variables in the whole database or a domain.

list workspaces

Lists known workspaces of a specified database.

log [PATH] ...

Prints selected history in forward or reverse order. This command prints selected history in forward or reverse order, filtering it by PATH if given.

manpage

Generate a manual page from monotone's command help.

show_conflicts REV REV

Shows what conflicts need resolution between two revisions. The conflicts are calculated based on the two revisions given in the REV parameters.

status [PATH]...

Shows workspace's status information.

version

Shows the program version.

command group 'key_and_cert'¶

Commands to manage keys and certificates.

cert SELECTOR CERTNAME [CERTVAL]

Creates a certificate for a revision or set of revisions. Creates a certificate with the given name and value on each revision that matches the given selector

dropkey KEY_NAME_OR_HASH

Drops a public and/or private key.

genkey KEY_NAME

Generates an RSA key-pair.

passphrase KEY_NAME_OR_HASH

Changes the passphrase of a private RSA key.

ssh_agent_add

Adds a private key to ssh-agent.

ssh_agent_export [FILENAME]

Exports a private key for use with ssh-agent.

trusted REVISION NAME VALUE SIGNER1 [SIGNER2 [...]]

Tests whether a hypothetical certificate would be trusted. The current settings are used to run the test.

command group 'network'¶

Commands that access the network.

clone URI [DIRECTORY]

clone HOST[:PORTNUMBER] BRANCH [DIRECTORY]

Checks out a revision from a remote database into a directory. If a revision is given, that's the one that will be checked out. Otherwise, it will be the head of the branch supplied. If no directory is given, the branch name will be used as directory

pull [URI]

pull [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Pulls branches from a netsync server. This pulls all branches that match the pattern given in PATTERN from the netsync server at the address ADDRESS.

push [URI]

push [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Pushes branches to a netsync server. This will push all branches that match the pattern given in PATTERN to the netsync server at the address ADDRESS.

serve

Serves the database to connecting clients.

sync [URI]

sync [ADDRESS[:PORTNUMBER] [PATTERN ...]]

Synchronizes branches with a netsync server. This synchronizes branches that match the pattern given in PATTERN with the netsync server at the address ADDRESS.

command group 'packet_io'¶

Commands for packet reading and writing.

privkey KEY_NAME_OR_HASH

Prints a private key packet.

pubkey KEY_NAME_OR_HASH

Prints a public key packet.

read [FILE1 [FILE2 [...]]]

Reads packets from files. If no files are provided, the standard input is used.

command group 'review'¶

Commands to review revisions.

approve REVISION

Approves a particular revision.

comment REVISION [COMMENT]

Comments on a particular revision.

disapprove [PARENT-REVISION] CHILD-REVISION

Disapproves a particular revision or revision range.

suspend REVISION

Suspends a particular revision.

tag REVISION TAGNAME

Puts a symbolic tag certificate on a revision.

testresult REV (pass|fail|true|false|yes|no|1|0)

Notes the results of running a test on a revision.

command group 'tree'¶

Commands to manipulate the tree.

checkout [DIRECTORY]

co [DIRECTORY]

Checks out a revision from the database into a directory. If a revision is given, that's the one that will be checked out. Otherwise, it will be the head of the branch (given or implicit). If no directory is given, the branch name will be used as directory.

conflicts clean

Delete any bookkeeping files related to conflict resolution.

conflicts resolve_first RESOLUTION

Set the resolution for the first unresolved single-file conflict.. Use 'mtn conflicts show_first' to see possible resolutions.

conflicts resolve_first_left RESOLUTION

Set the left resolution for the first unresolved two-file conflict.

conflicts resolve_first_right RESOLUTION

Set the right resolution for the first unresolved two-file conflict.

conflicts show_first

Show the first unresolved conflict in the conflicts file, and possible resolutions.

conflicts show_remaining

Show the remaining unresolved conflicts in the conflicts file.

conflicts store [LEFT_REVID RIGHT_REVID]

Store the conflicts from merging two revisions. If no arguments are given, LEFT_REVID and RIGHT_REVID default to the first two heads that would be chosen by the 'merge' command. If '--conflicts-file' is not given, '_MTN/conflicts' is used.

explicit_merge LEFT-REVISION RIGHT-REVISION DEST-BRANCH

Merges two explicitly given revisions. The results of the merge are placed on the branch specified by DEST-BRANCH.

heads

Shows unmerged head revisions of a branch.

import DIRECTORY

Imports the contents of a directory into a branch.

merge

Merges unmerged heads of a branch.

merge_into_dir SOURCE-BRANCH DEST-BRANCH DIR

Merges one branch into a subdirectory in another branch.

merge_into_workspace OTHER-REVISION

Merges a revision into the current workspace's base revision. Merges OTHER-REVISION into the current workspace's base revision, and update the current workspace with the result. There can be no pending changes in the current workspace. Both OTHER-REVISION and the workspace's base revision will be recorded as parents on commit. The workspace's selected branch is not changed.

migrate_workspace [DIRECTORY]

Migrates a workspace directory's metadata to the latest format. If no directory is given, defaults to the current workspace.

propagate SOURCE-BRANCH DEST-BRANCH

Merges from one branch to another asymmetrically.

refresh_inodeprints

Refreshes the inodeprint cache.

setup [DIRECTORY]

Sets up a new workspace directory. If no directory is specified, uses the current directory.

command group 'variables'¶

Commands to manage persistent variables.

cleanup_workspace_list

Removes all invalid, registered workspace paths for the current database.

register_workspace [WORKSPACE_PATH]

Registers a new workspace for the current database. This command adds WORKSPACE_PATH to the list of `known-workspaces'.

set DOMAIN NAME VALUE

Sets a database variable. This command modifies (or adds if it did not exist before) the variable named NAME, stored in the database, and sets it to the given value in VALUE. The variable is placed in the domain DOMAIN.

unregister_workspace [WORKSPACE_PATH]

Unregisters an existing workspace for the current database. This command removes WORKSPACE_PATH to the list of `known-workspaces'.

unset DOMAIN NAME

Unsets a database variable. This command removes the variable NAME from domain DOMAIN, which was previously stored in the database.

command group 'vcs'¶

Commands for interaction with other version control systems.

cvs_import CVSROOT

Imports all versions in a CVS repository.

git_export

Produces a git fast-export data stream on stdout.

command group 'workspace'¶

Commands that deal with the workspace.

add [PATH]...

Adds files to the workspace.

attr drop PATH [ATTR]

Removes attributes from a file. If no attribute is specified, this command removes all attributes attached to the file given in PATH. Otherwise only removes the attribute specified in ATTR.

attr get PATH [ATTR]

Gets the values of a file's attributes. If no attribute is specified, this command prints all attributes attached to the file given in PATH. Otherwise it only prints the attribute specified in ATTR.

attr set PATH ATTR VALUE

Sets an attribute on a file. Sets the attribute given on ATTR to the value specified in VALUE for the file mentioned in PATH.

ci [PATH]...

commit [PATH]...

Commits workspace changes to the database.

drop [PATH]...

rm [PATH]...

Drops files from the workspace.

mkdir [DIRECTORY...]

Creates directories and adds them to the workspace.

pivot_root NEW_ROOT PUT_OLD

Renames the root directory. After this command, the directory that currently has the name NEW_ROOT will be the root directory, and the directory that is currently the root directory will have name PUT_OLD. Use of '--bookkeep-only' is NOT recommended.

pluck [PATH...]

Applies changes made at arbitrary places in history. This command takes changes made at any point in history, and edits your current workspace to include those changes. The end result is identical to 'mtn diff -r FROM -r TO | patch -p0', except that this command uses monotone's merger, and thus intelligently handles renames, conflicts, and so on. If one revision is given, applies the changes made in that revision compared to its parent. If two revisions are given, applies the changes made to get from the first revision to the second.

mv SRC DEST

mv SRC1 [SRC2 [...]] DEST_DIR

rename SRC DEST

rename SRC1 [SRC2 [...]] DEST_DIR

Renames entries in the workspace.

revert [PATH]...

Reverts files and/or directories. In order to revert the entire workspace, specify '.' as the file name.

undrop PATH...

Reverses a mistaken 'drop'. If the file was deleted from the workspace, this is the same as 'revert'. Otherwise, it just removes the 'drop' from the manifest.

update

Updates the workspace. This command modifies your workspace to be based off of a different revision, preserving uncommitted changes as it does so. If a revision is given, update the workspace to that revision. If not, update the workspace to the head of the branch.

SEE ALSO¶

info mtn and the documentation on http://www.monotone.ca/docs

BUGS¶

Please report bugs to https://code.monotone.ca/p/monotone/issues/.

AUTHORS¶

monotone was written originally by Graydon Hoare <graydon@pobox.com> in 2003 and has since then received numerous contributions from many individuals. A complete list of authors can be found in AUTHORS. Nowadays, monotone is maintained by a collective of enthusiastic programmers, known as the monotone development team.

COPYRIGHT¶

monotone and this man page is Copyright (c) 2003 - 2012 by the monotone development team.