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.
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.
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.
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:
author
cert, indicating the person responsible for the changes
leading to the new revision. Normally this defaults to your signing key
or the return value of the get_author
hook; you may override this
by passing the --author option to commit. This is useful when
committing a patch on behalf of someone else, or when importing “by
hand” from another version control system.
branch
cert, indicating the branch the committed revision
belongs to.
date
cert, indicating when the new revision was created.
Normally this defaults to the current time; you may override this by
passing the --date option to commit. This is useful when
importing “by hand” from another version control system.
changelog
cert, containing the “log message” for these
changes. If you provided logmsg on the command line, this text
will be used, otherwise commit will run the Lua hook
edit_comment (
commentary,
user_log_content)
, which
typically invokes an external editor program, in which you can compose
and/or review your log message for the change.
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.
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.
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.
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.
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.
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.
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.