3.7 Workspace Collisions

Workspace collisions can happen for many reasons; some examples include:

• You have a file in your workspace that is unknown to monotone (you have not added it). Someone else has added and commited a file with the same name. If you try to update your workspace to their revision, the added file in the incoming revision will collide with your file.
• There is a directory which contains both versioned and unversioned files (perhaps versioned sources, and unversioned object files built from the sources). Someone else commits a revision that drops the versioned files and the containing directory. If you try to update to this revision, your directory will still contain the untracked files, and monotone will not delete them.
• You have an unversioned file in your workspace, and you’re trying to update to 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 checkout, pivot_root or pluck.

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:

• On some systems with case-insensitive and/or internationalised filesystems, names that look distinct to monotone may in fact be considered the same by the underlying platform.
• If some other program is creating files in the workspace at the same time as monotone, the colliding file might be created after the collision check at the start.
• Other kinds of unpredictable system errors, like permissions problems or disk full conditions, might cause failures when monotone is rearranging the workspace content.

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 update (or 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 revert).