Next: , Previous: Tree, Up: Command Reference


5.2 Workspace

mtn setup [directory]
This command prepares directory as a monotone workspace, by creating and populating the _MTN directory with basic information. This information must include at least the branch and the database to be used, both of which will be placed in the _MTN/options file.

This can be used with an empty directory to start a new blank project, or within an existing directory full of files, prior to using mtn commit. If no directory is specified, the current directory is used.

mtn add [--recursive | -R] [--no-respect-ignore] pathname...
mtn add [--recursive | -R] [--no-respect-ignore] --unknown [pathname...]
This command places “add” entries for the paths specified in pathname... in the workspace's “work list”. The work list of your workspace is stored in _MTN/revision, and is a list of explicit pathname changes you wish to commit at some future time, such as addition, removal or renaming of files.

As a convenience, the --unknown option can be used; this option will cause all of the files listed by mtn list unknown to be added.

While this command places an “add” entry on your work list, it does not immediately affect your database. When you commit your workspace, monotone will use the work list to build a new revision, which it will then commit to the database. The new revision will have any added entries inserted in its manifest.

Adding directories, whether explicitly or using the --unknown option, is non-recursive by default. The add command can be made recursive using the --recursive option. When adding a directory non-recursively, monotone will warn if the directory has any files that would be added by a recursive add.

mtn [--no-respect-ignore] mkdir directory...
This command creates a directory in the filesystem relative to your current location and adds it to your workspace's “work list”. The changes are not reflected in your database until such time as you perform a commit. If you use the --no-respect-ignore flag, entries in .mtn-ignore will not be honored.
mtn [--bookkeep-only] drop pathname...
mtn drop --missing
This command places “drop” entries for the paths specified in pathname... in the workspace's “work list” and deletes the file from the workspace. The work list of your workspace is stored in _MTN/revision, and is a list of explicit pathname changes you wish to commit at some future time, such as addition, removal, or renaming of files. This command also removes any attributes on pathname; see File Attributes for more details. If you use the --missing flag it will add drop entries for any paths that monotone is tracking for which you have already removed the files from the filesystem, in addition to all those specified in pathname....

While this command places a “drop” entry on your work list, it does not immediately affect your database. When you commit your workspace, monotone will use the work list to build a new revision, which it will then commit to the database. The new revision will have any dropped entries removed from its manifest.

There are situations in which drop will tell monotone to remove the file from the revision at commit time, but where it will not to remove the file from the workspace immediately. One is if the --bookkeep-only option is supplied. Another is if a file has un-committed changes or if a directory is not empty.

mtn [--bookkeep-only] rename src dst
mtn [--bookkeep-only] mv src dst
mtn [--bookkeep-only] rename src1 ... dst/
mtn [--bookkeep-only] mv src1 ... dst/
This command places “rename” entries for the paths specified in src and dst in the workspace's “work list”. The second form renames a number of source paths to the given destination. The work list of your workspace is stored in _MTN/revision, and is a list of explicit pathname changes you wish to commit at some future time, such as addition, removal, or renaming of files. This command also moves any attributes on src to dst; see File Attributes for more details, and, unless the --bookkeep-only option is supplied, it will rename the files immediately in the filesystem. In the case where dst must be a directory (multiple src items), exists physically in the filesystem as a directory or is specified as a directory by convention (a trailing /), it will be automatically added to the workspace if it is not already versioned.
mtn commit
mtn ci
mtn commit --message=logmsg [--message=logmsg...]
mtn ci --message=logmsg [--message=logmsg...]
mtn commit --message-file=logfile
mtn ci --message-file=logfile
mtn commit pathname...
mtn ci pathname...
mtn commit --message=logmsg [--message=logmsg...] pathname...
mtn ci --message=logmsg [--message=logmsg...] pathname...
mtn commit --message-file=logfile pathname...
mtn ci --message-file=logfile pathname...
This command looks at your workspace, decides which files have changed, and saves the changes to your database. It does this by loading the revision named in _MTN/revision, locating the base manifest for your workspace, applying any pathname changes described in _MTN/revision, and then comparing the updated base manifest to the files it finds in your workspace, to determine which files have been edited.

For each edited file, a delta is copied into the database. Then the newly constructed manifest is recorded (as a delta) and finally the new revision. Once all these objects are recorded in you database, commit updates _MTN/revision to indicate that the base revision is now the newly created revision, and that there are no pathname changes to apply.

Specifying pathnames to commit restricts the set of changes that are visible and results in only a partial commit of the workspace. Changes to files not included in the specified set of pathnames will be ignored and will remain in the workspace until they are included in a future commit. With a partial commit, only the relevant entries in _MTN/revision will be removed and other entries will remain for future commits.

From within a subdirectory of the workspace the commit command will, by default, include all changes in the workspace. Specifying only the pathname "." will restrict commit to files changed within the current subdirectory of the workspace.

The --message and --message-file options are mutually exclusive. Both provide a logmsg describing the commit. --message-file actually specifies the name of the file containing the log message, while --message provides it directly.

Multiple --message options may be provided on the command line. The log message will be formed by concatenating the --message options provided, with each one starting at the beginning of a new line.

The _MTN/log file can be edited by the user during their daily work to record the changes made to the workspace. When running the commit command without a logmsg supplied, the contents of the _MTN/log file will be read and passed to the Lua hook edit_comment as a second parameter named user_log_content. The log message will be prepended with a 'magic' string that must be removed to confirm the commit. This allows the user to easily cancel a commit, without emptying the entire log message. If the commit is successful, the _MTN/log file is cleared of all content making it ready for another edit/commit cycle.

If --message-file=_MTN/log is specified, the contents of _MTN/log will be used without confirmation.

If a --branch option is specified, the commit command commits to this branch (creating it if necessary). The branch becomes the new default branch of the workspace.

The commit command also synthesizes a number of certificates, which it attaches to the new manifest version and copies into your database:


mtn revert pathname...
mtn revert --missing pathname...
This command changes your workspace, so that changes you have made since the last checkout or update are discarded. The command is restricted the set of files or directories given as arguments. To revert the entire workspace, use revert "." in the top-level directory. Specifying "." in a subdirectory will restrict revert to files changed within the current subdirectory.

If the flag --missing is given it reverts (ie, restores) any files which monotone has listed in its manifest, but which have been deleted from the workspace. Only missing files matching the given file or directory arguments are reverted.

mtn update [--move-conflicting-paths]
mtn update [--move-conflicting-paths] --revision=revision
Without a --revision argument, this command incorporates “recent” changes found in your database into your workspace. It does this by performing 3 separate stages. If any of these stages fails, the update aborts, doing nothing. The stages are:

With an explicit --revision argument, the command uses that revision as the update target instead of finding an acceptable candidate.

The effect is always to take whatever changes you have made in the workspace, and to “transpose” them onto a new revision, using monotone's 3-way merge algorithm to achieve good results. Note that with the explicit --revision argument, it is possible to update “backwards” or “sideways” in history — for example, reverting to an earlier revision, or if your branch has two heads, updating to the other. In all cases, the end result will be whatever revision you specified, with your local changes (and only your local changes) applied.

If a --branch option is specified, the update command tries to select the revision to update to from this branch. The branch becomes the new default branch of the workspace (even if you also specify an explicit --revision argument).

When running update, it is sometimes possible for Workspace Collisions to occur.

mtn pluck [--move-conflicting-paths] --revision=to
mtn pluck [--move-conflicting-paths] --revision=from --revision=to
This command takes changes made at any point in history, and attempts to edit your current workspace to include those changes. The end result is identical to running 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 only one revision is given, applies the changes made in to as compared with to's parent. If two revisions are given, applies the changes made to get from from to to.

Note that this is not a true cherrypick operation. A true cherrypick, as that word is used in version control theory, involves applying some changes out of context, and then recording the identity between the original changes and the newly applied changes for the use of later merges. This command does the first part, not the second. As far as monotone is concerned, the changes made by mtn pluck are exactly like those made in an editor; the command is simply a convenient way to make certain edits quickly. In practice, this is rarely a problem. mtn pluck should almost always be used between branches that will never be merged — for instance, backporting fixes from a development branch to a stable branch.

When you use pluck you are going behind monotone's back, and reducing its ability to help you keep track of what has happened in your history. Never use pluck where a true merging command like merge, propagate, or explicit_merge will do. If you find yourself using pluck often, you should consider carefully whether there is any way to change your workflow to reduce your need for plucking.

When running pluck, it is sometimes possible for Workspace Collisions to occur.

mtn refresh_inodeprints
This command puts the current workspace into Inodeprints mode, if it was not already, and forces a full inodeprints cache refresh. After running this command, you are guaranteed that your workspace is in inodeprints mode, and that the inodeprints cache is accurate and up to date.
mtn pivot_root [--bookkeep-only] [--move-conflicting-paths] pivot_root new_root put_old
Most users will never need this command. It is primarily useful in certain tricky cases where one wishes to combine several projects into one, or split one project into several. See also merge_into_dir.

Its effect is to rename the directory whose name is currently new_root to become the root directory of the versioned tree, and to at the same time rename the directory that is currently the root of the versioned tree to have the name put_old. Conceptually, it is equivalent to executing the following commands in the root of the workspace:

     $ mtn rename . new_root/put_old
     $ mtn rename new_root .

Except, of course, that these rename commands are illegal, because after the first command the tree has no root at all, and there is a directory loop. This illegality is the only reason for pivot_root's existence; internally, the result is treated exactly like two renames, including with respect to merges and updates.

The use of --bookkeep-only with this command is not recommended. It causes the changes to be made in monotone's records, but not in the filesystem itself.

When running pivot_root, it is sometimes possible for Workspace Collisions to occur.

mtn bisect good [--revision=id ...] [--move-conflicting-paths]
Mark the specified revisions as “good” for the current bisection operation. If no bisection operation is in progress a new bisection is initialized. If a bisection operation is in progress the next update target is selected and the workspace is updated to the selected revision.

If the update is blocked by conflicting unversioned paths existing in the workspace this command may be re-issued with the --move-conflicting-paths option. Alternatively, the bisect update command can be used with this option to update the workspace and move the conflicting paths out of the way.

mtn bisect bad [--revision=id ...] [--move-conflicting-paths]
Mark the specified revisions as “bad” for the current bisection operation. If no bisection operation is in progress a new bisection is initialized. If a bisection operation is in progress the next update target is selected and the workspace is updated to the selected revision.

If the update is blocked by conflicting unversioned paths existing in the workspace this command may be re-issued with the --move-conflicting-paths option. Alternatively, the bisect update command can be used with this option to update the workspace and move the conflicting paths out of the way.

mtn bisect skip [--revision=id ...] [--move-conflicting-paths]
Mark the specified revisions as “skipped” for the current bisection operation. If no bisection operation is in progress a new bisection is initialized. If a bisection operation is in progress the next update target is selected and the workspace is updated to the selected revision.

If the update is blocked by conflicting unversioned paths existing in the workspace this command may be re-issued with the --move-conflicting-paths option. Alternatively, the bisect update command can be used with this option to update the workspace and move the conflicting paths out of the way.

mtn bisect update [--move-conflicting-paths]
Update the workspace to the next revision selected by the previous bisect operation. This command can be useful when the previous bisect operation fails to update the workspace because of conflicting unversioned paths existing in the workspace.
mtn bisect status
Report the status of the current bisection operation including the number of revisions that remain to be tested, the number of revisions that have been tested and the next revision that will selected for testing.
mtn bisect reset
Reset the current bisection operation by updating the workspace back to the revision from which the bisection was started and clearing the current bisection information.