Next: , Up: Command Reference


5.1 Tree

mtn cat path
mtn cat --revision=id path
Write the contents of a specific file path to standard output.

Without a --revision argument, the command outputs the contents of path as found in the current revision. This requires the command be executed from within a workspace.

With an explicit --revision argument, the command outputs contents of path at that revision.

mtn checkout --revision=id directory
mtn co --revision=id directory
mtn --branch=branchname checkout directory
mtn --branch=branchname co directory
These commands copy a revision id out of your database, recording the chosen revision (the base revision) in the file directory/_MTN/revision. These commands then copy every file version listed in the revision's manifest to paths under directory. For example, if the revision's manifest contains these entries:
          dir ""
          
             file "Makefile"
          content [84e2c30a2571bd627918deee1e6613d34e64a29e]
          
             file "include/hello.h"
          content [c61af2e67eb9b81e46357bb3c409a9a53a7cdfc6]
          
             file "src/hello.c
          content [97dfc6fd4f486df95868d85b4b81197014ae2a84]

Then the following files are created:

          directory/
          directory/Makefile
          directory/include/hello.h
          directory/src/hello.c

If you wish to checkout in the current directory, you can supply the special name . (a single period) for directory. When running checkout into an existing directory, it is sometimes possible for Workspace Collisions to occur.

If no id is provided, as in the latter two commands, you must provide a branchname; monotone will attempt to infer id as the unique head of branchname if it exists.

mtn clone --branch=branchname address directory
The clone command is a helper command that performs the roles of a number of other commands all at once. Firstly, it constructs a new database. It then populates this database by pulling any data in the branch branchname from the remote database, address. Finally, it copies the files out of the newly created database into a local directory, just as checkout would. The created database is placed in the new workspace as directory/_MTN/mtn.db.
mtn disapprove id
This command records a disapproval of the changes between id's ancestor and id. It does this by committing the inverse changes as a new revision descending from id. The new revision will show up as a new head and thus a subsequent merge will incorporate the inverse of the disapproved changes in the other head(s).

Conceptually, disapproves contract is that disapprove(A) gives a revision B such that whenever B is merged with a descendant D of A the merge will result in what D “would have looked like” if A had never happened.

Note that as a consequence of this contract the disapprove command only works if id has exactly one ancestor, since it hasn't been worked out how to generate such a descendant in the multi-ancestor case.

mtn heads --branch=branchname
This command lists the “heads” of branchname.

The “heads” of a branch is the set of revisions which are members of the branch, but which have no descendants. These revisions are generally the “newest” revisions committed by you or your colleagues, at least in terms of ancestry. The heads of a branch may not be the newest revisions, in terms of time, but synchronization of computer clocks is not reliable, so monotone usually ignores time.

mtn merge [--branch=branchname]
This command merges the “heads” of branchname, if there are multiple heads, and commits the results to the database, marking the resulting merged revision as a member of branchname. The merged revision will contain each of the head revision IDs as ancestors.

Merging is performed by repeated pairwise merges: two heads are selected, then their least common ancestor is located in the ancestry graph and these 3 revisions are provided to the built-in 3-way merge algorithm. The process then repeats for each additional head, using the result of each previous merge as an input to the next.

mtn propagate sourcebranch destbranch
This command takes a unique head from sourcebranch and merges it with a unique head of destbranch, using the least common ancestor of the two heads for a 3-way merge. The resulting revision is committed to destbranch. If either sourcebranch or destbranch has multiple heads, propagate aborts, doing nothing.

The purpose of propagate is to copy all the changes on sourcebranch, since the last propagate, to destbranch. This command supports the idea of making separate branches for medium-length development activities, such as maintenance branches for stable software releases, trivial bug fix branches, public contribution branches, or branches devoted to the development of a single module within a larger project.

mtn explicit_merge id id destbranch
This command merges exactly the two ids you give it, and places the result in branch destbranch. It is useful when you need more control over the merging process than propagate or merge give you. For instance, if you have a branch with three heads, and you only want to merge two of them, you can use this command. Or if you have a branch with two heads, and you want to propagate one of them to another branch, again, you can use this command.
mtn merge_into_dir sourcebranch destbranch dir
This command takes a unique head from sourcebranch and merges it into a unique head of destbranch, as a directory. The resulting revision is committed to destbranch. If either sourcebranch or destbranch has multiple heads, merge_into_dir aborts, doing nothing.

The purpose of merge_into_dir is to permit a project to contain another project in such a way that propagate can be used to keep the contained project up-to-date. It is meant to replace the use of nested checkouts in many circumstances.

Note that merge_into_dir does not permit changes made to the contained project in destbranch to be propagated back to sourcebranch. Attempting this would lead to sourcebranch containing both projects nested as in destbranch instead of only the project originally in sourcebranch, which is almost certainly not what would be intended.

mtn import --branch=branch [--message=message] [--dry-run] dir
mtn import --revision=revision [--message=message] [--dry-run] dir
This command imports the contents of the given directory and commits it to the head of the given branch or as a child of the given revision (and consequently into the branch that revision resides in).

If the given branch doesn't exist, it is created automatically. If the branch already exists, any missing files are dropped and any unknown files are added before committing.

If --dry-run is given, no commit is done.