1.1 --- a/fr/ch07-filenames.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch07-filenames.xml	Wed Apr 21 17:09:42 2010 +0200
     1.3 @@ -1,388 +1,451 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>File names and pattern matching</title>
     1.8 -<para>\label{chap:names}</para>
     1.9 -
    1.10 -<para>Mercurial provides mechanisms that let you work with file names in a
    1.11 -consistent and expressive way.</para>
    1.12 -
    1.13 -<sect1>
    1.14 -<title>Simple file naming</title>
    1.15 -
    1.16 -<para>Mercurial uses a unified piece of machinery <quote>under the hood</quote> to
    1.17 -handle file names.  Every command behaves uniformly with respect to
    1.18 -file names.  The way in which commands work with file names is as
    1.19 -follows.</para>
    1.20 -
    1.21 -<para>If you explicitly name real files on the command line, Mercurial works
    1.22 -with exactly those files, as you would expect.
    1.23 -<!-- &interaction.filenames.files; --></para>
    1.24 -
    1.25 -<para>When you provide a directory name, Mercurial will interpret this as
    1.26 -<quote>operate on every file in this directory and its subdirectories</quote>.
    1.27 -Mercurial traverses the files and subdirectories in a directory in
    1.28 -alphabetical order.  When it encounters a subdirectory, it will
    1.29 -traverse that subdirectory before continuing with the current
    1.30 -directory.
    1.31 -<!-- &interaction.filenames.dirs; --></para>
    1.32 -
    1.33 -</sect1>
    1.34 -<sect1>
    1.35 -<title>Running commands without any file names</title>
    1.36 -
    1.37 -<para>Mercurial's commands that work with file names have useful default
    1.38 -behaviours when you invoke them without providing any file names or
    1.39 -patterns.  What kind of behaviour you should expect depends on what
    1.40 -the command does.  Here are a few rules of thumb you can use to
    1.41 -predict what a command is likely to do if you don't give it any names
    1.42 -to work with.</para>
    1.43 -<itemizedlist>
    1.44 -<listitem><para>Most commands will operate on the entire working directory.
    1.45 -  This is what the <command role="hg-cmd">hg add</command> command does, for example.</para>
    1.46 -</listitem>
    1.47 -<listitem><para>If the command has effects that are difficult or impossible to
    1.48 -  reverse, it will force you to explicitly provide at least one name
    1.49 -  or pattern (see below).  This protects you from accidentally
    1.50 -  deleting files by running <command role="hg-cmd">hg remove</command> with no arguments, for
    1.51 -  example.</para>
    1.52 -</listitem></itemizedlist>
    1.53 -
    1.54 -<para>It's easy to work around these default behaviours if they don't suit
    1.55 -you.  If a command normally operates on the whole working directory,
    1.56 -you can invoke it on just the current directory and its subdirectories
    1.57 -by giving it the name <quote><filename class="directory">.</filename></quote>.
    1.58 -<!-- &interaction.filenames.wdir-subdir; -->
    1.59 -</para>
    1.60 -
    1.61 -<para>Along the same lines, some commands normally print file names relative
    1.62 -to the root of the repository, even if you're invoking them from a
    1.63 -subdirectory.  Such a command will print file names relative to your
    1.64 -subdirectory if you give it explicit names.  Here, we're going to run
    1.65 -<command role="hg-cmd">hg status</command> from a subdirectory, and get it to operate on the
    1.66 -entire working directory while printing file names relative to our
    1.67 -subdirectory, by passing it the output of the <command role="hg-cmd">hg root</command> command.
    1.68 -<!-- &interaction.filenames.wdir-relname; -->
    1.69 -</para>
    1.70 -
    1.71 -</sect1>
    1.72 -<sect1>
    1.73 -<title>Telling you what's going on</title>
    1.74 -
    1.75 -<para>The <command role="hg-cmd">hg add</command> example in the preceding section illustrates something
    1.76 -else that's helpful about Mercurial commands.  If a command operates
    1.77 -on a file that you didn't name explicitly on the command line, it will
    1.78 -usually print the name of the file, so that you will not be surprised
    1.79 -what's going on.
    1.80 -</para>
    1.81 -
    1.82 -<para>The principle here is of <emphasis>least surprise</emphasis>.  If you've exactly
    1.83 -named a file on the command line, there's no point in repeating it
    1.84 -back at you.  If Mercurial is acting on a file <emphasis>implicitly</emphasis>,
    1.85 -because you provided no names, or a directory, or a pattern (see
    1.86 -below), it's safest to tell you what it's doing.
    1.87 -</para>
    1.88 -
    1.89 -<para>For commands that behave this way, you can silence them using the
    1.90 -<option role="hg-opt-global">-q</option> option.  You can also get them to print the name of every
    1.91 -file, even those you've named explicitly, using the <option role="hg-opt-global">-v</option>
    1.92 -option.
    1.93 -</para>
    1.94 -
    1.95 -</sect1>
    1.96 -<sect1>
    1.97 -<title>Using patterns to identify files</title>
    1.98 -
    1.99 -<para>In addition to working with file and directory names, Mercurial lets
   1.100 -you use <emphasis>patterns</emphasis> to identify files.  Mercurial's pattern
   1.101 -handling is expressive.
   1.102 -</para>
   1.103 -
   1.104 -<para>On Unix-like systems (Linux, MacOS, etc.), the job of matching file
   1.105 -names to patterns normally falls to the shell.  On these systems, you
   1.106 -must explicitly tell Mercurial that a name is a pattern.  On Windows,
   1.107 -the shell does not expand patterns, so Mercurial will automatically
   1.108 -identify names that are patterns, and expand them for you.
   1.109 -</para>
   1.110 -
   1.111 -<para>To provide a pattern in place of a regular name on the command line,
   1.112 -the mechanism is simple:
   1.113 -</para>
   1.114 -<programlisting>
   1.115 -<para>  syntax:patternbody
   1.116 -</para>
   1.117 +<chapter id="chap:names">
   1.118 +  <?dbhtml filename="file-names-and-pattern-matching.html"?>
   1.119 +  <title>File names and pattern matching</title>
   1.120 +
   1.121 +  <para id="x_543">Mercurial provides mechanisms that let you work with file
   1.122 +    names in a consistent and expressive way.</para>
   1.123 +
   1.124 +  <sect1>
   1.125 +    <title>Simple file naming</title>
   1.126 +
   1.127 +    <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the
   1.128 +	hood</quote> to handle file names.  Every command behaves
   1.129 +      uniformly with respect to file names.  The way in which commands
   1.130 +      work with file names is as follows.</para>
   1.131 +
   1.132 +    <para id="x_545">If you explicitly name real files on the command line,
   1.133 +      Mercurial works with exactly those files, as you would expect.
   1.134 +      &interaction.filenames.files;</para>
   1.135 +
   1.136 +    <para id="x_546">When you provide a directory name, Mercurial will interpret
   1.137 +      this as <quote>operate on every file in this directory and its
   1.138 +	subdirectories</quote>. Mercurial traverses the files and
   1.139 +      subdirectories in a directory in alphabetical order.  When it
   1.140 +      encounters a subdirectory, it will traverse that subdirectory
   1.141 +      before continuing with the current directory.</para>
   1.142 +
   1.143 +      &interaction.filenames.dirs;
   1.144 +  </sect1>
   1.145 +
   1.146 +  <sect1>
   1.147 +    <title>Running commands without any file names</title>
   1.148 +
   1.149 +    <para id="x_547">Mercurial's commands that work with file names have useful
   1.150 +      default behaviors when you invoke them without providing any
   1.151 +      file names or patterns.  What kind of behavior you should
   1.152 +      expect depends on what the command does.  Here are a few rules
   1.153 +      of thumb you can use to predict what a command is likely to do
   1.154 +      if you don't give it any names to work with.</para>
   1.155 +    <itemizedlist>
   1.156 +      <listitem><para id="x_548">Most commands will operate on the entire working
   1.157 +	  directory. This is what the <command role="hg-cmd">hg
   1.158 +	    add</command> command does, for example.</para>
   1.159 +      </listitem>
   1.160 +      <listitem><para id="x_549">If the command has effects that are difficult or
   1.161 +	  impossible to reverse, it will force you to explicitly
   1.162 +	  provide at least one name or pattern (see below).  This
   1.163 +	  protects you from accidentally deleting files by running
   1.164 +	  <command role="hg-cmd">hg remove</command> with no
   1.165 +	  arguments, for example.</para>
   1.166 +      </listitem></itemizedlist>
   1.167 +
   1.168 +    <para id="x_54a">It's easy to work around these default behaviors if they
   1.169 +      don't suit you.  If a command normally operates on the whole
   1.170 +      working directory, you can invoke it on just the current
   1.171 +      directory and its subdirectories by giving it the name
   1.172 +      <quote><filename class="directory">.</filename></quote>.</para>
   1.173 +
   1.174 +    &interaction.filenames.wdir-subdir;
   1.175 +
   1.176 +    <para id="x_54b">Along the same lines, some commands normally print file
   1.177 +      names relative to the root of the repository, even if you're
   1.178 +      invoking them from a subdirectory.  Such a command will print
   1.179 +      file names relative to your subdirectory if you give it explicit
   1.180 +      names.  Here, we're going to run <command role="hg-cmd">hg
   1.181 +	status</command> from a subdirectory, and get it to operate on
   1.182 +      the entire working directory while printing file names relative
   1.183 +      to our subdirectory, by passing it the output of the <command
   1.184 +	role="hg-cmd">hg root</command> command.</para>
   1.185 +
   1.186 +      &interaction.filenames.wdir-relname;
   1.187 +  </sect1>
   1.188 +
   1.189 +  <sect1>
   1.190 +    <title>Telling you what's going on</title>
   1.191 +
   1.192 +    <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the
   1.193 +      preceding section illustrates something else that's helpful
   1.194 +      about Mercurial commands.  If a command operates on a file that
   1.195 +      you didn't name explicitly on the command line, it will usually
   1.196 +      print the name of the file, so that you will not be surprised
   1.197 +      what's going on.</para>
   1.198 +
   1.199 +    <para id="x_54d">The principle here is of <emphasis>least
   1.200 +	surprise</emphasis>.  If you've exactly named a file on the
   1.201 +      command line, there's no point in repeating it back at you.  If
   1.202 +      Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
   1.203 +      because you provided no names, or a directory, or a pattern (see
   1.204 +      below), it is safest to tell you what files it's operating on.</para>
   1.205 +
   1.206 +    <para id="x_54e">For commands that behave this way, you can silence them
   1.207 +      using the <option role="hg-opt-global">-q</option> option.  You
   1.208 +      can also get them to print the name of every file, even those
   1.209 +      you've named explicitly, using the <option
   1.210 +	role="hg-opt-global">-v</option> option.</para>
   1.211 +  </sect1>
   1.212 +
   1.213 +  <sect1>
   1.214 +    <title>Using patterns to identify files</title>
   1.215 +
   1.216 +    <para id="x_54f">In addition to working with file and directory names,
   1.217 +      Mercurial lets you use <emphasis>patterns</emphasis> to identify
   1.218 +      files.  Mercurial's pattern handling is expressive.</para>
   1.219 +
   1.220 +    <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of
   1.221 +      matching file names to patterns normally falls to the shell.  On
   1.222 +      these systems, you must explicitly tell Mercurial that a name is
   1.223 +      a pattern.  On Windows, the shell does not expand patterns, so
   1.224 +      Mercurial will automatically identify names that are patterns,
   1.225 +      and expand them for you.</para>
   1.226 +
   1.227 +    <para id="x_551">To provide a pattern in place of a regular name on the
   1.228 +      command line, the mechanism is simple:</para>
   1.229 +    <programlisting>syntax:patternbody</programlisting>
   1.230 +    <para id="x_552">That is, a pattern is identified by a short text string that
   1.231 +      says what kind of pattern this is, followed by a colon, followed
   1.232 +      by the actual pattern.</para>
   1.233 +
   1.234 +    <para id="x_553">Mercurial supports two kinds of pattern syntax.  The most
   1.235 +      frequently used is called <literal>glob</literal>; this is the
   1.236 +      same kind of pattern matching used by the Unix shell, and should
   1.237 +      be familiar to Windows command prompt users, too.</para>
   1.238 +
   1.239 +    <para id="x_554">When Mercurial does automatic pattern matching on Windows,
   1.240 +      it uses <literal>glob</literal> syntax.  You can thus omit the
   1.241 +      <quote><literal>glob:</literal></quote> prefix on Windows, but
   1.242 +      it's safe to use it, too.</para>
   1.243 +
   1.244 +    <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets
   1.245 +      you specify patterns using regular expressions, also known as
   1.246 +      regexps.</para>
   1.247 +
   1.248 +    <para id="x_556">By the way, in the examples that follow, notice that I'm
   1.249 +      careful to wrap all of my patterns in quote characters, so that
   1.250 +      they won't get expanded by the shell before Mercurial sees
   1.251 +      them.</para>
   1.252 +
   1.253 +    <sect2>
   1.254 +      <title>Shell-style <literal>glob</literal> patterns</title>
   1.255 +
   1.256 +      <para id="x_557">This is an overview of the kinds of patterns you can use
   1.257 +	when you're matching on glob patterns.</para>
   1.258 +
   1.259 +      <para id="x_558">The <quote><literal>*</literal></quote> character matches
   1.260 +	any string, within a single directory.</para>
   1.261 +
   1.262 +      &interaction.filenames.glob.star;
   1.263 +
   1.264 +      <para id="x_559">The <quote><literal>**</literal></quote> pattern matches
   1.265 +	any string, and crosses directory boundaries.  It's not a
   1.266 +	standard Unix glob token, but it's accepted by several popular
   1.267 +	Unix shells, and is very useful.</para>
   1.268 +
   1.269 +      &interaction.filenames.glob.starstar;
   1.270 +
   1.271 +      <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches
   1.272 +	any single character.</para>
   1.273 +
   1.274 +      &interaction.filenames.glob.question;
   1.275 +
   1.276 +      <para id="x_55b">The <quote><literal>[</literal></quote> character begins a
   1.277 +	<emphasis>character class</emphasis>.  This matches any single
   1.278 +	character within the class.  The class ends with a
   1.279 +	<quote><literal>]</literal></quote> character.  A class may
   1.280 +	contain multiple <emphasis>range</emphasis>s of the form
   1.281 +	<quote><literal>a-f</literal></quote>, which is shorthand for
   1.282 +	<quote><literal>abcdef</literal></quote>.</para>
   1.283 +
   1.284 +	&interaction.filenames.glob.range;
   1.285 +
   1.286 +      <para id="x_55c">If the first character after the
   1.287 +	<quote><literal>[</literal></quote> in a character class is a
   1.288 +	<quote><literal>!</literal></quote>, it
   1.289 +	<emphasis>negates</emphasis> the class, making it match any
   1.290 +	single character not in the class.</para>
   1.291 +
   1.292 +      <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of
   1.293 +	subpatterns, where the whole group matches if any subpattern
   1.294 +	in the group matches.  The <quote><literal>,</literal></quote>
   1.295 +	character separates subpatterns, and
   1.296 +	<quote><literal>}</literal></quote> ends the group.</para>
   1.297 +
   1.298 +      &interaction.filenames.glob.group;
   1.299 +
   1.300 +      <sect3>
   1.301 +	<title>Watch out!</title>
   1.302 +
   1.303 +	<para id="x_55e">Don't forget that if you want to match a pattern in any
   1.304 +	  directory, you should not be using the
   1.305 +	  <quote><literal>*</literal></quote> match-any token, as this
   1.306 +	  will only match within one directory.  Instead, use the
   1.307 +	  <quote><literal>**</literal></quote> token.  This small
   1.308 +	  example illustrates the difference between the two.</para>
   1.309 +
   1.310 +	  &interaction.filenames.glob.star-starstar;
   1.311 +      </sect3>
   1.312 +    </sect2>
   1.313 +
   1.314 +    <sect2>
   1.315 +      <title>Regular expression matching with <literal>re</literal>
   1.316 +	patterns</title>
   1.317 +
   1.318 +      <para id="x_55f">Mercurial accepts the same regular expression syntax as
   1.319 +	the Python programming language (it uses Python's regexp
   1.320 +	engine internally). This is based on the Perl language's
   1.321 +	regexp syntax, which is the most popular dialect in use (it's
   1.322 +	also used in Java, for example).</para>
   1.323 +
   1.324 +      <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail
   1.325 +	here, as regexps are not often used.  Perl-style regexps are
   1.326 +	in any case already exhaustively documented on a multitude of
   1.327 +	web sites, and in many books.  Instead, I will focus here on a
   1.328 +	few things you should know if you find yourself needing to use
   1.329 +	regexps with Mercurial.</para>
   1.330 +
   1.331 +      <para id="x_561">A regexp is matched against an entire file name, relative
   1.332 +	to the root of the repository.  In other words, even if you're
   1.333 +	already in subbdirectory <filename
   1.334 +	  class="directory">foo</filename>, if you want to match files
   1.335 +	under this directory, your pattern must start with
   1.336 +	<quote><literal>foo/</literal></quote>.</para>
   1.337 +
   1.338 +      <para id="x_562">One thing to note, if you're familiar with Perl-style
   1.339 +	regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
   1.340 +	That is, a regexp starts matching against the beginning of a
   1.341 +	string; it doesn't look for a match anywhere within the
   1.342 +	string.  To match anywhere in a string, start your pattern
   1.343 +	with <quote><literal>.*</literal></quote>.</para>
   1.344 +    </sect2>
   1.345 +  </sect1>
   1.346 +
   1.347 +  <sect1>
   1.348 +    <title>Filtering files</title>
   1.349 +
   1.350 +    <para id="x_563">Not only does Mercurial give you a variety of ways to
   1.351 +      specify files; it lets you further winnow those files using
   1.352 +      <emphasis>filters</emphasis>.  Commands that work with file
   1.353 +      names accept two filtering options.</para>
   1.354 +    <itemizedlist>
   1.355 +      <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or
   1.356 +	  <option role="hg-opt-global">--include</option>, lets you
   1.357 +	  specify a pattern that file names must match in order to be
   1.358 +	  processed.</para>
   1.359 +      </listitem>
   1.360 +      <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or
   1.361 +	  <option role="hg-opt-global">--exclude</option>, gives you a
   1.362 +	  way to <emphasis>avoid</emphasis> processing files, if they
   1.363 +	  match this pattern.</para>
   1.364 +      </listitem></itemizedlist>
   1.365 +    <para id="x_566">You can provide multiple <option
   1.366 +	role="hg-opt-global">-I</option> and <option
   1.367 +	role="hg-opt-global">-X</option> options on the command line,
   1.368 +      and intermix them as you please.  Mercurial interprets the
   1.369 +      patterns you provide using glob syntax by default (but you can
   1.370 +      use regexps if you need to).</para>
   1.371 +
   1.372 +    <para id="x_567">You can read a <option role="hg-opt-global">-I</option>
   1.373 +      filter as <quote>process only the files that match this
   1.374 +	filter</quote>.</para>
   1.375 +
   1.376 +    &interaction.filenames.filter.include;
   1.377 +
   1.378 +    <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best
   1.379 +      read as <quote>process only the files that don't match this
   1.380 +	pattern</quote>.</para>
   1.381 +
   1.382 +    &interaction.filenames.filter.exclude;
   1.383 +  </sect1>
   1.384 +
   1.385 +  <sect1>
   1.386 +    <title>Permanently ignoring unwanted files and directories</title>
   1.387 +
   1.388 +    <para id="x_569">When you create a new repository, the chances are
   1.389 +      that over time it will grow to contain files that ought to
   1.390 +      <emphasis>not</emphasis> be managed by Mercurial, but which you
   1.391 +      don't want to see listed every time you run <command>hg
   1.392 +	status</command>.  For instance, <quote>build products</quote>
   1.393 +      are files that are created as part of a build but which should
   1.394 +      not be managed by a revision control system.  The most common
   1.395 +      build products are output files produced by software tools such
   1.396 +      as compilers.  As another example, many text editors litter a
   1.397 +      directory with lock files, temporary working files, and backup
   1.398 +      files, which it also makes no sense to manage.</para>
   1.399 +
   1.400 +    <para id="x_6b4">To have Mercurial permanently ignore such files, create a
   1.401 +      file named <filename>.hgignore</filename> in the root of your
   1.402 +      repository.  You <emphasis>should</emphasis> <command>hg
   1.403 +      add</command> this file so that it gets tracked with the rest of
   1.404 +      your repository contents, since your collaborators will probably
   1.405 +      find it useful too.</para>
   1.406 +
   1.407 +    <para id="x_6b5">By default, the <filename>.hgignore</filename> file should
   1.408 +      contain a list of regular expressions, one per line.  Empty
   1.409 +      lines are skipped. Most people prefer to describe the files they
   1.410 +      want to ignore using the <quote>glob</quote> syntax that we
   1.411 +      described above, so a typical <filename>.hgignore</filename>
   1.412 +      file will start with this directive:</para>
   1.413 +
   1.414 +    <programlisting>syntax: glob</programlisting>
   1.415 +
   1.416 +    <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
   1.417 +      glob patterns, not regular expressions.</para>
   1.418 +
   1.419 +    <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename>
   1.420 +      file.</para>
   1.421 +
   1.422 +    <programlisting>syntax: glob
   1.423 +# This line is a comment, and will be skipped.
   1.424 +# Empty lines are skipped too.
   1.425 +
   1.426 +# Backup files left behind by the Emacs editor.
   1.427 +*~
   1.428 +
   1.429 +# Lock files used by the Emacs editor.
   1.430 +# Notice that the "#" character is quoted with a backslash.
   1.431 +# This prevents it from being interpreted as starting a comment.
   1.432 +.\#*
   1.433 +
   1.434 +# Temporary files used by the vim editor.
   1.435 +.*.swp
   1.436 +
   1.437 +# A hidden file created by the Mac OS X Finder.
   1.438 +.DS_Store
   1.439  </programlisting>
   1.440 -<para>That is, a pattern is identified by a short text string that says what
   1.441 -kind of pattern this is, followed by a colon, followed by the actual
   1.442 -pattern.
   1.443 -</para>
   1.444 -
   1.445 -<para>Mercurial supports two kinds of pattern syntax.  The most frequently
   1.446 -used is called <literal>glob</literal>; this is the same kind of pattern
   1.447 -matching used by the Unix shell, and should be familiar to Windows
   1.448 -command prompt users, too.
   1.449 -</para>
   1.450 -
   1.451 -<para>When Mercurial does automatic pattern matching on Windows, it uses
   1.452 -<literal>glob</literal> syntax.  You can thus omit the <quote><literal>glob:</literal></quote> prefix
   1.453 -on Windows, but it's safe to use it, too.
   1.454 -</para>
   1.455 -
   1.456 -<para>The <literal>re</literal> syntax is more powerful; it lets you specify patterns
   1.457 -using regular expressions, also known as regexps.
   1.458 -</para>
   1.459 -
   1.460 -<para>By the way, in the examples that follow, notice that I'm careful to
   1.461 -wrap all of my patterns in quote characters, so that they won't get
   1.462 -expanded by the shell before Mercurial sees them.
   1.463 -</para>
   1.464 -
   1.465 -<sect2>
   1.466 -<title>Shell-style <literal>glob</literal> patterns</title>
   1.467 -
   1.468 -<para>This is an overview of the kinds of patterns you can use when you're
   1.469 -matching on glob patterns.
   1.470 -</para>
   1.471 -
   1.472 -<para>The <quote><literal>*</literal></quote> character matches any string, within a single
   1.473 -directory.
   1.474 -<!-- &interaction.filenames.glob.star; -->
   1.475 -</para>
   1.476 -
   1.477 -<para>The <quote><literal>**</literal></quote> pattern matches any string, and crosses directory
   1.478 -boundaries.  It's not a standard Unix glob token, but it's accepted by
   1.479 -several popular Unix shells, and is very useful.
   1.480 -<!-- &interaction.filenames.glob.starstar; -->
   1.481 -</para>
   1.482 -
   1.483 -<para>The <quote><literal>?</literal></quote> pattern matches any single character.
   1.484 -<!-- &interaction.filenames.glob.question; -->
   1.485 -</para>
   1.486 -
   1.487 -<para>The <quote><literal>[</literal></quote> character begins a <emphasis>character class</emphasis>.  This
   1.488 -matches any single character within the class.  The class ends with a
   1.489 -<quote><literal>]</literal></quote> character.  A class may contain multiple <emphasis>range</emphasis>s
   1.490 -of the form <quote><literal>a-f</literal></quote>, which is shorthand for
   1.491 -<quote><literal>abcdef</literal></quote>.
   1.492 -<!-- &interaction.filenames.glob.range; -->
   1.493 -If the first character after the <quote><literal>[</literal></quote> in a character class
   1.494 -is a <quote><literal>!</literal></quote>, it <emphasis>negates</emphasis> the class, making it match any
   1.495 -single character not in the class.
   1.496 -</para>
   1.497 -
   1.498 -<para>A <quote><literal>{</literal></quote> begins a group of subpatterns, where the whole group
   1.499 -matches if any subpattern in the group matches.  The <quote><literal>,</literal></quote>
   1.500 -character separates subpatterns, and <quote>\texttt{}}</quote> ends the group.
   1.501 -<!-- &interaction.filenames.glob.group; -->
   1.502 -</para>
   1.503 -
   1.504 -<sect3>
   1.505 -<title>Watch out!</title>
   1.506 -
   1.507 -<para>Don't forget that if you want to match a pattern in any directory, you
   1.508 -should not be using the <quote><literal>*</literal></quote> match-any token, as this will
   1.509 -only match within one directory.  Instead, use the <quote><literal>**</literal></quote>
   1.510 -token.  This small example illustrates the difference between the two.
   1.511 -<!-- &interaction.filenames.glob.star-starstar; -->
   1.512 -</para>
   1.513 -
   1.514 -</sect3>
   1.515 -</sect2>
   1.516 -<sect2>
   1.517 -<title>Regular expression matching with <literal>re</literal> patterns</title>
   1.518 -
   1.519 -<para>Mercurial accepts the same regular expression syntax as the Python
   1.520 -programming language (it uses Python's regexp engine internally).
   1.521 -This is based on the Perl language's regexp syntax, which is the most
   1.522 -popular dialect in use (it's also used in Java, for example).
   1.523 -</para>
   1.524 -
   1.525 -<para>I won't discuss Mercurial's regexp dialect in any detail here, as
   1.526 -regexps are not often used.  Perl-style regexps are in any case
   1.527 -already exhaustively documented on a multitude of web sites, and in
   1.528 -many books.  Instead, I will focus here on a few things you should
   1.529 -know if you find yourself needing to use regexps with Mercurial.
   1.530 -</para>
   1.531 -
   1.532 -<para>A regexp is matched against an entire file name, relative to the root
   1.533 -of the repository.  In other words, even if you're already in
   1.534 -subbdirectory <filename class="directory">foo</filename>, if you want to match files under this
   1.535 -directory, your pattern must start with <quote><literal>foo/</literal></quote>.
   1.536 -</para>
   1.537 -
   1.538 -<para>One thing to note, if you're familiar with Perl-style regexps, is that
   1.539 -Mercurial's are <emphasis>rooted</emphasis>.  That is, a regexp starts matching
   1.540 -against the beginning of a string; it doesn't look for a match
   1.541 -anywhere within the string.  To match anywhere in a string, start
   1.542 -your pattern with <quote><literal>.*</literal></quote>.
   1.543 -</para>
   1.544 -
   1.545 -</sect2>
   1.546 -</sect1>
   1.547 -<sect1>
   1.548 -<title>Filtering files</title>
   1.549 -
   1.550 -<para>Not only does Mercurial give you a variety of ways to specify files;
   1.551 -it lets you further winnow those files using <emphasis>filters</emphasis>.  Commands
   1.552 -that work with file names accept two filtering options.
   1.553 -</para>
   1.554 -<itemizedlist>
   1.555 -<listitem><para><option role="hg-opt-global">-I</option>, or <option role="hg-opt-global">--include</option>, lets you specify a pattern
   1.556 -  that file names must match in order to be processed.
   1.557 -</para>
   1.558 -</listitem>
   1.559 -<listitem><para><option role="hg-opt-global">-X</option>, or <option role="hg-opt-global">--exclude</option>, gives you a way to
   1.560 -  <emphasis>avoid</emphasis> processing files, if they match this pattern.
   1.561 -</para>
   1.562 -</listitem></itemizedlist>
   1.563 -<para>You can provide multiple <option role="hg-opt-global">-I</option> and <option role="hg-opt-global">-X</option> options on the
   1.564 -command line, and intermix them as you please.  Mercurial interprets
   1.565 -the patterns you provide using glob syntax by default (but you can use
   1.566 -regexps if you need to).
   1.567 -</para>
   1.568 -
   1.569 -<para>You can read a <option role="hg-opt-global">-I</option> filter as <quote>process only the files that
   1.570 -match this filter</quote>.
   1.571 -<!-- &interaction.filenames.filter.include; -->
   1.572 -The <option role="hg-opt-global">-X</option> filter is best read as <quote>process only the files that
   1.573 -don't match this pattern</quote>.
   1.574 -<!-- &interaction.filenames.filter.exclude; -->
   1.575 -</para>
   1.576 -
   1.577 -</sect1>
   1.578 -<sect1>
   1.579 -<title>Ignoring unwanted files and directories</title>
   1.580 -
   1.581 -<para>XXX.
   1.582 -</para>
   1.583 -
   1.584 -</sect1>
   1.585 -<sect1>
   1.586 -<title>Case sensitivity</title>
   1.587 -<para>\label{sec:names:case}
   1.588 -</para>
   1.589 -
   1.590 -<para>If you're working in a mixed development environment that contains
   1.591 -both Linux (or other Unix) systems and Macs or Windows systems, you
   1.592 -should keep in the back of your mind the knowledge that they treat the
   1.593 -case (<quote>N</quote> versus <quote>n</quote>) of file names in incompatible ways.  This is
   1.594 -not very likely to affect you, and it's easy to deal with if it does,
   1.595 -but it could surprise you if you don't know about it.
   1.596 -</para>
   1.597 -
   1.598 -<para>Operating systems and filesystems differ in the way they handle the
   1.599 -<emphasis>case</emphasis> of characters in file and directory names.  There are
   1.600 -three common ways to handle case in names.
   1.601 -</para>
   1.602 -<itemizedlist>
   1.603 -<listitem><para>Completely case insensitive.  Uppercase and lowercase versions
   1.604 -  of a letter are treated as identical, both when creating a file and
   1.605 -  during subsequent accesses.  This is common on older DOS-based
   1.606 -  systems.
   1.607 -</para>
   1.608 -</listitem>
   1.609 -<listitem><para>Case preserving, but insensitive.  When a file or directory is
   1.610 -  created, the case of its name is stored, and can be retrieved and
   1.611 -  displayed by the operating system.  When an existing file is being
   1.612 -  looked up, its case is ignored.  This is the standard arrangement on
   1.613 -  Windows and MacOS.  The names <filename>foo</filename> and <filename>FoO</filename>
   1.614 -  identify the same file.  This treatment of uppercase and lowercase
   1.615 -  letters as interchangeable is also referred to as \emph{case
   1.616 -    folding}.
   1.617 -</para>
   1.618 -</listitem>
   1.619 -<listitem><para>Case sensitive.  The case of a name is significant at all times.
   1.620 -  The names <filename>foo</filename> and {FoO} identify different files.  This
   1.621 -  is the way Linux and Unix systems normally work.
   1.622 -</para>
   1.623 -</listitem></itemizedlist>
   1.624 -
   1.625 -<para>On Unix-like systems, it is possible to have any or all of the above
   1.626 -ways of handling case in action at once.  For example, if you use a
   1.627 -USB thumb drive formatted with a FAT32 filesystem on a Linux system,
   1.628 -Linux will handle names on that filesystem in a case preserving, but
   1.629 -insensitive, way.
   1.630 -</para>
   1.631 -
   1.632 -<sect2>
   1.633 -<title>Safe, portable repository storage</title>
   1.634 -
   1.635 -<para>Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>.  It
   1.636 -translates file names so that they can be safely stored on both case
   1.637 -sensitive and case insensitive filesystems.  This means that you can
   1.638 -use normal file copying tools to transfer a Mercurial repository onto,
   1.639 -for example, a USB thumb drive, and safely move that drive and
   1.640 -repository back and forth between a Mac, a PC running Windows, and a
   1.641 -Linux box.
   1.642 -</para>
   1.643 -
   1.644 -</sect2>
   1.645 -<sect2>
   1.646 -<title>Detecting case conflicts</title>
   1.647 -
   1.648 -<para>When operating in the working directory, Mercurial honours the naming
   1.649 -policy of the filesystem where the working directory is located.  If
   1.650 -the filesystem is case preserving, but insensitive, Mercurial will
   1.651 -treat names that differ only in case as the same.
   1.652 -</para>
   1.653 -
   1.654 -<para>An important aspect of this approach is that it is possible to commit
   1.655 -a changeset on a case sensitive (typically Linux or Unix) filesystem
   1.656 -that will cause trouble for users on case insensitive (usually Windows
   1.657 -and MacOS) users.  If a Linux user commits changes to two files, one
   1.658 -named <filename>myfile.c</filename> and the other named <filename>MyFile.C</filename>,
   1.659 -they will be stored correctly in the repository.  And in the working
   1.660 -directories of other Linux users, they will be correctly represented
   1.661 -as separate files.
   1.662 -</para>
   1.663 -
   1.664 -<para>If a Windows or Mac user pulls this change, they will not initially
   1.665 -have a problem, because Mercurial's repository storage mechanism is
   1.666 -case safe.  However, once they try to <command role="hg-cmd">hg update</command> the working
   1.667 -directory to that changeset, or <command role="hg-cmd">hg merge</command> with that changeset,
   1.668 -Mercurial will spot the conflict between the two file names that the
   1.669 -filesystem would treat as the same, and forbid the update or merge
   1.670 -from occurring.
   1.671 -</para>
   1.672 -
   1.673 -</sect2>
   1.674 -<sect2>
   1.675 -<title>Fixing a case conflict</title>
   1.676 -
   1.677 -<para>If you are using Windows or a Mac in a mixed environment where some of
   1.678 -your collaborators are using Linux or Unix, and Mercurial reports a
   1.679 -case folding conflict when you try to <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg merge</command>,
   1.680 -the procedure to fix the problem is simple.
   1.681 -</para>
   1.682 -
   1.683 -<para>Just find a nearby Linux or Unix box, clone the problem repository
   1.684 -onto it, and use Mercurial's <command role="hg-cmd">hg rename</command> command to change the
   1.685 -names of any offending files or directories so that they will no
   1.686 -longer cause case folding conflicts.  Commit this change, <command role="hg-cmd">hg pull</command>
   1.687 -or <command role="hg-cmd">hg push</command> it across to your Windows or MacOS system, and
   1.688 -<command role="hg-cmd">hg update</command> to the revision with the non-conflicting names.
   1.689 -</para>
   1.690 -
   1.691 -<para>The changeset with case-conflicting names will remain in your
   1.692 -project's history, and you still won't be able to <command role="hg-cmd">hg update</command> your
   1.693 -working directory to that changeset on a Windows or MacOS system, but
   1.694 -you can continue development unimpeded.
   1.695 -</para>
   1.696 -
   1.697 -<note>
   1.698 -<para>  Prior to version 0.9.3, Mercurial did not use a case safe repository
   1.699 -  storage mechanism, and did not detect case folding conflicts.  If
   1.700 -  you are using an older version of Mercurial on Windows or MacOS, I
   1.701 -  strongly recommend that you upgrade.
   1.702 -</para>
   1.703 -</note>
   1.704 -
   1.705 -</sect2>
   1.706 -</sect1>
   1.707 +  </sect1>
   1.708 +
   1.709 +  <sect1 id="sec:names:case">
   1.710 +    <title>Case sensitivity</title>
   1.711 +
   1.712 +    <para id="x_56a">If you're working in a mixed development environment that
   1.713 +      contains both Linux (or other Unix) systems and Macs or Windows
   1.714 +      systems, you should keep in the back of your mind the knowledge
   1.715 +      that they treat the case (<quote>N</quote> versus
   1.716 +      <quote>n</quote>) of file names in incompatible ways.  This is
   1.717 +      not very likely to affect you, and it's easy to deal with if it
   1.718 +      does, but it could surprise you if you don't know about
   1.719 +      it.</para>
   1.720 +
   1.721 +    <para id="x_56b">Operating systems and filesystems differ in the way they
   1.722 +      handle the <emphasis>case</emphasis> of characters in file and
   1.723 +      directory names.  There are three common ways to handle case in
   1.724 +      names.</para>
   1.725 +    <itemizedlist>
   1.726 +      <listitem><para id="x_56c">Completely case insensitive.  Uppercase and
   1.727 +	  lowercase versions of a letter are treated as identical,
   1.728 +	  both when creating a file and during subsequent accesses.
   1.729 +	  This is common on older DOS-based systems.</para>
   1.730 +      </listitem>
   1.731 +      <listitem><para id="x_56d">Case preserving, but insensitive.  When a file
   1.732 +	  or directory is created, the case of its name is stored, and
   1.733 +	  can be retrieved and displayed by the operating system.
   1.734 +	  When an existing file is being looked up, its case is
   1.735 +	  ignored.  This is the standard arrangement on Windows and
   1.736 +	  MacOS.  The names <filename>foo</filename> and
   1.737 +	  <filename>FoO</filename> identify the same file.  This
   1.738 +	  treatment of uppercase and lowercase letters as
   1.739 +	  interchangeable is also referred to as <emphasis>case
   1.740 +	    folding</emphasis>.</para>
   1.741 +      </listitem>
   1.742 +      <listitem><para id="x_56e">Case sensitive.  The case of a name
   1.743 +	  is significant at all times. The names
   1.744 +	  <filename>foo</filename> and <filename>FoO</filename>
   1.745 +	  identify different files.  This is the way Linux and Unix
   1.746 +	  systems normally work.</para>
   1.747 +      </listitem></itemizedlist>
   1.748 +
   1.749 +    <para id="x_56f">On Unix-like systems, it is possible to have any or all of
   1.750 +      the above ways of handling case in action at once.  For example,
   1.751 +      if you use a USB thumb drive formatted with a FAT32 filesystem
   1.752 +      on a Linux system, Linux will handle names on that filesystem in
   1.753 +      a case preserving, but insensitive, way.</para>
   1.754 +
   1.755 +    <sect2>
   1.756 +      <title>Safe, portable repository storage</title>
   1.757 +
   1.758 +      <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case
   1.759 +	  safe</emphasis>.  It translates file names so that they can
   1.760 +	be safely stored on both case sensitive and case insensitive
   1.761 +	filesystems.  This means that you can use normal file copying
   1.762 +	tools to transfer a Mercurial repository onto, for example, a
   1.763 +	USB thumb drive, and safely move that drive and repository
   1.764 +	back and forth between a Mac, a PC running Windows, and a
   1.765 +	Linux box.</para>
   1.766 +
   1.767 +    </sect2>
   1.768 +    <sect2>
   1.769 +      <title>Detecting case conflicts</title>
   1.770 +
   1.771 +      <para id="x_571">When operating in the working directory, Mercurial honours
   1.772 +	the naming policy of the filesystem where the working
   1.773 +	directory is located.  If the filesystem is case preserving,
   1.774 +	but insensitive, Mercurial will treat names that differ only
   1.775 +	in case as the same.</para>
   1.776 +
   1.777 +      <para id="x_572">An important aspect of this approach is that it is
   1.778 +	possible to commit a changeset on a case sensitive (typically
   1.779 +	Linux or Unix) filesystem that will cause trouble for users on
   1.780 +	case insensitive (usually Windows and MacOS) users.  If a
   1.781 +	Linux user commits changes to two files, one named
   1.782 +	<filename>myfile.c</filename> and the other named
   1.783 +	<filename>MyFile.C</filename>, they will be stored correctly
   1.784 +	in the repository.  And in the working directories of other
   1.785 +	Linux users, they will be correctly represented as separate
   1.786 +	files.</para>
   1.787 +
   1.788 +      <para id="x_573">If a Windows or Mac user pulls this change, they will not
   1.789 +	initially have a problem, because Mercurial's repository
   1.790 +	storage mechanism is case safe.  However, once they try to
   1.791 +	<command role="hg-cmd">hg update</command> the working
   1.792 +	directory to that changeset, or <command role="hg-cmd">hg
   1.793 +	  merge</command> with that changeset, Mercurial will spot the
   1.794 +	conflict between the two file names that the filesystem would
   1.795 +	treat as the same, and forbid the update or merge from
   1.796 +	occurring.</para>
   1.797 +    </sect2>
   1.798 +
   1.799 +    <sect2>
   1.800 +      <title>Fixing a case conflict</title>
   1.801 +
   1.802 +      <para id="x_574">If you are using Windows or a Mac in a mixed environment
   1.803 +	where some of your collaborators are using Linux or Unix, and
   1.804 +	Mercurial reports a case folding conflict when you try to
   1.805 +	<command role="hg-cmd">hg update</command> or <command
   1.806 +	  role="hg-cmd">hg merge</command>, the procedure to fix the
   1.807 +	problem is simple.</para>
   1.808 +
   1.809 +      <para id="x_575">Just find a nearby Linux or Unix box, clone the problem
   1.810 +	repository onto it, and use Mercurial's <command
   1.811 +	  role="hg-cmd">hg rename</command> command to change the
   1.812 +	names of any offending files or directories so that they will
   1.813 +	no longer cause case folding conflicts.  Commit this change,
   1.814 +	<command role="hg-cmd">hg pull</command> or <command
   1.815 +	  role="hg-cmd">hg push</command> it across to your Windows or
   1.816 +	MacOS system, and <command role="hg-cmd">hg update</command>
   1.817 +	to the revision with the non-conflicting names.</para>
   1.818 +
   1.819 +      <para id="x_576">The changeset with case-conflicting names will remain in
   1.820 +	your project's history, and you still won't be able to
   1.821 +	<command role="hg-cmd">hg update</command> your working
   1.822 +	directory to that changeset on a Windows or MacOS system, but
   1.823 +	you can continue development unimpeded.</para>
   1.824 +    </sect2>
   1.825 +  </sect1>
   1.826  </chapter>
   1.827  
   1.828  <!--
   1.829  local variables: 
   1.830  sgml-parent-document: ("00book.xml" "book" "chapter")
   1.831  end:
   1.832 --->
   1.833 \ No newline at end of file
   1.834 +-->