3.3 Restrictions

Several monotone commands accept optional pathname... arguments in order to establish a “restriction”. Restrictions are used to limit the files and directories these commands examine for changes when comparing the workspace to the revision it is based on. Restricting a command to a specified set of files or directories simply ignores changes to files or directories not included by the restriction.

The following commands all support restrictions using optional pathname... arguments:

• status
• diff
• revert
• commit
• list known
• list unknown
• list ignored
• list missing
• list changed
• log

Including either the old or new name of a renamed file or directory will cause both names to be included in a restriction. If in doubt, the status command can be used to “test” a set of pathnames to ensure that the expected files are included or excluded by a restriction.

Commands which support restrictions also support the --depth=n and --exclude=path options. The value n given to --depth specifies the maximum number of directories to descend. For example, n=0 disables recursion, n=1 means descend at most one directory below each specified path, and so on. The --depth value applies individually to each path specified on the command line. The value path given to --exclude specifies a path that should be excluded from the restriction. Multiple --exclude options may be specified to exclude several files or subdirectories.

The update command does not allow for updates to a restricted set of files, which may be slightly different than other version control systems. Partial updates don’t really make sense in monotone, as they would leave the workspace based on a revision that doesn’t exist in the database, starting an entirely new line of development.

In addition to including all of the explicitly specified paths and excluding all of the paths specified with --exclude options a restriction also implicitly includes the parent directories of all included paths. This is done to allow commands operating on newly added files to succeed. For example, if a new directory a is added and a file a/b is added to this directory restricting to exactly a/b will produce a meaningless state that doesn’t include the required parent directory a.

The implicit inclusion of required parent directories is done for all of the commands listed above with the exception of revert. This is done to allow reverting the addition of files in newly added or renamed directories without reverting the directories themselves. If the parent directories were implicitly included their addition or name changes would also be reverted.

Subdirectory restrictions

The restrictions facility also allows commands to operate from within a subdirectory of the workspace. By default, the entire workspace is always examined for changes. However, specifying an explicit . pathname to a command will restrict it to the current subdirectory. Note that this is quite different from other version control systems and may seem somewhat surprising.

The expectation is that requiring a single . to restrict to the current subdirectory should be simple to use. While the alternative, defaulting to restricting to the current subdirectory, would require a somewhat complicated ../../.. sequence to remove the restriction and operate on the whole tree.

This default was chosen because monotone versions whole project trees and generally expects to commit all changes in the workspace as a single atomic unit. Other version control systems often version individual files or directories and may not support atomic commits at all.

When working from within a subdirectory of the workspace all paths specified to monotone commands must be relative to the current subdirectory.

Finding a workspace

Monotone only stores a single _MTN directory at the root of a workspace. Because of this, a search is done to find the _MTN directory in case a command is executed from within a subdirectory of a workspace. Before a command is executed, the search for a workspace directory is done by traversing parent directories until an _MTN directory is found or the filesystem root is reached. Upon finding an _MTN directory, the _MTN/options file is read for default options. The --root option may be used to stop the search early, before reaching the root of the physical filesystem. The --no-workspace option may be used to prevent the search entirely.

Many monotone commands don’t require a workspace and will simply proceed with no default options if no _MTN directory is found. However, some monotone commands do require a workspace and will fail if no _MTN directory can be found.

The checkout, clone and setup commands create a new workspace and initialize a new _MTN/options file based on their current option settings.