# # # patch "monotone.texi" # from [15bafc5e32dcc384d7017e773c93e3eeb37833a2] # to [8ab23243b1975df8e2f632567a65e467d619bc2a] # ============================================================ --- monotone.texi 15bafc5e32dcc384d7017e773c93e3eeb37833a2 +++ monotone.texi 8ab23243b1975df8e2f632567a65e467d619bc2a @@ -2543,6 +2543,7 @@ @chapter Advanced Uses * Restrictions:: Limit workspace changes to specified files. * Scripting:: Running monotone from other programs. * Inodeprints:: Trading off safety for speed in your workspace. +* Workspace Collisions:: Workspace files that collide with new versioned files. * Quality Assurance:: Integrating testing and review with development. * Vars:: Simple per-database configuration information. * Reserved Files:: File names with special meanings. @@ -2929,6 +2930,101 @@ @section Inodeprints workspaces you create. See @ref{Hook Reference} for details. @page address@hidden Workspace Collisions address@hidden Collisions} address@hidden Workspace Collisions + +Sometimes when you work on a project, several people make similar +changes in parallel. When these changes occur in an existing file that +is known to both sides, monotone can merge the edits when the two +revisions meet (possibly after getting help to resolve content +conflicts). Other kinds of changes cannot be merged so readily, +especially ones that involve files in your workspace that are not +tracked by monotone. + +Workspace collisions can happen for many reasons; some examples include: address@hidden address@hidden +You have a file in your workspace that is unknown to monotone (you +have not @command{add}ed it). Someone else has @command{add}ed and address@hidden a different file with the same name. If you try to address@hidden your workspace to their revision, the added file in the +incoming revision will collide with your file over use of the name. address@hidden +There is a directory which contains both versioned and unversioned files +(perhaps versioned sources, and unversioned object files built from the +sources). Someone else @command{commit}s a revision that address@hidden the versioned files @emph{and} the containing +directory. If you try to @command{update} to this revision, your +directory will still contain the untracked files, and therefore cannot +be deleted. address@hidden +You have an unversioned file in your workspace, and you're trying to address@hidden to a revision that @command{add}s a directory with the +same name. address@hidden itemize + +These examples describe collisions on @command{update}; the same kinds +of things can happen with other commands that can bring changes into +your workspace, such as @command{checkout} or @command{pluck} too. + +Monotone is careful to avoid hitting such collisions. Before changing +the workspace, it will try and detect the possibility of collisions, and +the command will fail, warning you about the names that collide. 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. + +However, monotone cannot detect all kinds of failures and collisions in +your workspace. For example: address@hidden address@hidden +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. address@hidden +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. address@hidden +Other kinds of unpredictable system errors, like permissions problems or +disk full conditions, might cause failures when monotone is rearranging +the workspace content. address@hidden itemize + +These are all hopefully very rare occurrences. If such a filesystem +error @emph{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 @dfn{detached} from the workspace under its old name, then address@hidden under the new name. This is done by moving it to the address@hidden/detached} directory. Newly added files are created here +before being moved into place, too. While inside @file{_MTN/detached}, +the file or directory is named as a simple integer (these numbers come +from monotone's internal identification of the 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 address@hidden/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 @command{commit} before trying to address@hidden (or @command{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 address@hidden). + address@hidden @node Quality Assurance @section Quality Assurance @@ -4032,13 +4128,14 @@ @section Tree If you wish to @command{checkout} in the current directory, you can supply the special name @file{.} (a single period) for address@hidden address@hidden When running @command{checkout} into an existing +directory, it is sometimes possible for @xref{Workspace Collisions} to +occur. If no @var{id} is provided, as in the latter two commands, you @emph{must} provide a @var{branchname}; monotone will attempt to infer @var{id} as the unique head of @var{branchname} if it exists. - @item mtn disapprove @var{id} This command records a disapproval of the changes between @var{id}'s @@ -4380,6 +4477,9 @@ @section Workspace becomes the new default branch of the workspace (even if you also specify an explicit @option{--revision} argument). +When running @command{update}, it is sometimes possible for address@hidden Collisions} to occur. + @item mtn pluck address@hidden @itemx mtn pluck address@hidden address@hidden @@ -4414,6 +4514,9 @@ @section Workspace consider carefully whether there is any way to change your workflow to reduce your need for @command{pluck}ing. +When running @command{pluck}, it is sometimes possible for address@hidden Collisions} to occur. + @item mtn refresh_inodeprints This command puts the current workspace into @ref{Inodeprints} mode, if it was not already, and forces a full inodeprints cache refresh. @@ -4450,6 +4553,9 @@ @section Workspace The use of @option{--execute} with this command is strongly recommended, though not required. +When running @command{pivot_root}, it is sometimes possible for address@hidden Collisions} to occur. + @end ftable @page