/usr/share/doc/monotone/html/Restrictions.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>monotone documentation: Restrictions</title>

<meta name="description" content="monotone documentation: Restrictions">
<meta name="keywords" content="monotone documentation: Restrictions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="General-Index.html#General-Index" rel="index" title="General Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Advanced-Uses.html#Advanced-Uses" rel="up" title="Advanced Uses">
<link href="Scripting.html#Scripting" rel="next" title="Scripting">
<link href="Selectors.html#Selectors" rel="prev" title="Selectors">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="texinfo.css">


</head>

<body lang="en">
<a name="Restrictions"></a>
<div class="header">
<p>
Next: <a href="Scripting.html#Scripting" accesskey="n" rel="next">Scripting</a>, Previous: <a href="Selectors.html#Selectors" accesskey="p" rel="prev">Selectors</a>, Up: <a href="Advanced-Uses.html#Advanced-Uses" accesskey="u" rel="up">Advanced Uses</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Restrictions-1"></a>
<h3 class="section">3.3 Restrictions</h3>

<p>Several monotone commands accept optional <var>pathname...</var> arguments in
order to establish a &ldquo;restriction&rdquo;.  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.
</p>
<p>The following commands all support restrictions using optional
<var>pathname...</var> arguments:
</p>
<ul>
<li> <code>status</code>
</li><li> <code>diff</code>
</li><li> <code>revert</code>
</li><li> <code>commit</code>
</li><li> <code>list known</code>
</li><li> <code>list unknown</code>
</li><li> <code>list ignored</code>
</li><li> <code>list missing</code>
</li><li> <code>list changed</code>
</li><li> <code>log</code>
</li></ul>

<p>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
<code>status</code> command can be used to &ldquo;test&rdquo; a set of pathnames to
ensure that the expected files are included or excluded by a
restriction.
</p>
<p>Commands which support restrictions also support the
<samp>--depth=<var>n</var> </samp> and <samp>--exclude=<var>path</var></samp>
options. The value <var>n</var> given to <samp>--depth</samp> specifies the
maximum number of directories to descend. For example, <var>n</var>=0
disables recursion, <var>n</var>=1 means descend at most one directory
below each specified path, and so on.  The <samp>--depth</samp> value
applies individually to each path specified on the command line. The
value <var>path</var> given to <samp>--exclude</samp> specifies a path that
should be excluded from the restriction. Multiple <samp>--exclude</samp>
options may be specified to exclude several files or subdirectories.
</p>
<p>The <code>update</code> 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&rsquo;t really make sense in
monotone, as they would leave the workspace based on a revision that
doesn&rsquo;t exist in the database, starting an entirely new line of
development.
</p>
<p>In addition to including all of the explicitly specified paths and
excluding all of the paths specified with <samp>--exclude</samp> 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 <samp>a</samp> is
added and a file <samp>a/b</samp> is added to this directory restricting to
exactly <samp>a/b</samp> will produce a meaningless state that doesn&rsquo;t
include the required parent directory <samp>a</samp>.
</p>
<p>The implicit inclusion of required parent directories is done for all
of the commands listed above with the exception of
<code>revert</code>. 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.
</p>
<a name="Subdirectory-restrictions"></a>
<h3 class="heading">Subdirectory restrictions</h3>

<p>The restrictions facility also allows commands to operate from within
a subdirectory of the workspace.  By default, the <i>entire workspace</i>
is always examined for changes. However, specifying an explicit
<samp>.</samp>  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.
</p>
<p>The expectation is that requiring a single <samp>.</samp> 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 <samp>../../..</samp> sequence to remove the
restriction and operate on the whole tree.
</p>
<p>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.
</p>
<p>When working from within a subdirectory of the workspace all
paths specified to monotone commands must be relative to the current
subdirectory.
</p>
<a name="Finding-a-workspace"></a>
<h3 class="heading">Finding a workspace</h3>

<p>Monotone only stores a single <samp>_MTN</samp> directory at the root of a
workspace. Because of this, a search is done to find the <samp>_MTN</samp>
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
<samp>_MTN</samp> directory is found or the filesystem root is reached. Upon
finding an <samp>_MTN</samp> directory, the <samp>_MTN/options</samp> file is read for
default options. The <samp>--root</samp> option may be used to stop the
search early, before reaching the root of the physical filesystem. The
<samp>--no-workspace</samp> option may be used to prevent the search entirely.
</p>
<p>Many monotone commands don&rsquo;t require a workspace and will simply
proceed with no default options if no <samp>_MTN</samp> directory is found.
However, some monotone commands do require a workspace and will fail
if no <samp>_MTN</samp> directory can be found.
</p>
<p>The <code>checkout</code>, <code>clone</code> and <code>setup</code> commands
create a <i>new workspace</i> and initialize a new <samp>_MTN/options</samp>
file based on their current option settings.
</p>

<hr>
<div class="header">
<p>
Next: <a href="Scripting.html#Scripting" accesskey="n" rel="next">Scripting</a>, Previous: <a href="Selectors.html#Selectors" accesskey="p" rel="prev">Selectors</a>, Up: <a href="Advanced-Uses.html#Advanced-Uses" accesskey="u" rel="up">Advanced Uses</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="General-Index.html#General-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
monotone-doc 1.1-7 / usr / share / doc / monotone / html / Restrictions.html
