Workspace collisions can happen for many reasons; some examples include:
added it). Someone else has
commited a file with the same name. If you try to
updateyour workspace to their revision, the added file in the incoming revision will collide with your file.
commits a revision that
drops the versioned files and the containing directory. If you try to
updateto this revision, your directory will still contain the untracked files, and monotone will not delete them.
updateto a revision that
adds a directory with the same name.
These examples describe collisions on
update; the same kinds
of things can happen with other commands that can bring changes into
your workspace, such as
In order to handle such collisions safely, before changing the workspace, monotone will detect them, and the command will fail with a warning. The file content in the database is safe and can be recovered at any time, so monotone is conservative and will refuse to destroy the information in your workspace contents.
In addition, all workspace-changing commands have an option --move-conflicting-paths, which moves unversioned but conflicting files and directories from the workspace into a corresponding directory under _MTN/resolutions. This is useful if you want to ensure that an update always succeeds and you just want to move blocking paths out of the way.
However, monotone cannot detect all kinds of failures and collisions in your workspace. For example:
These are all hopefully very rare occurrences. If such a filesystem error does cause a failure part-way during a workspace alteration, monotone will stop immediately rather than risk potentially doing further damage, and your workspace may be left in an incomplete state. If this happens, you will need to resolve the issue and clean up the workspace manually. If you need to do so, understanding how monotone manipulates the workspace is helpful.
When monotone applies renaming changes to the workspace, each file is first detached from the workspace under its old name, then attached under the new name. This is done by moving it to the _MTN/detached directory. Newly added files are created here before being moved into place, too. While inside _MTN/detached, the file or directory is named as a simple integer (monotone’s internal identification of the file node). If the detached node is a directory, the directory is moved with all of its contents (including unversioned files); this can help identify which directory has been detached.
If a previous workspace alteration failed part-way, the _MTN/detached directory will still exist, and monotone will refuse to attempt another alteration while the workspace is in this inconsistent state. This also acts as a lock against multiple monotone processes performing workspace alterations (but not other programs).
The best way to avoid a messy recovery from such a failure is simply to
ensure that you always
commit before trying to
pluck, etc) other changes from the
database into your workspace. This ensures that your current workspace
contents are safely stored, and can be retrieved later (such as with