1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch07-filenames.xml	Fri Sep 04 18:24:06 2009 +0200
     1.3 @@ -0,0 +1,388 @@
     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 +</programlisting>
   1.118 +<para>That is, a pattern is identified by a short text string that says what
   1.119 +kind of pattern this is, followed by a colon, followed by the actual
   1.120 +pattern.
   1.121 +</para>
   1.122 +
   1.123 +<para>Mercurial supports two kinds of pattern syntax.  The most frequently
   1.124 +used is called <literal>glob</literal>; this is the same kind of pattern
   1.125 +matching used by the Unix shell, and should be familiar to Windows
   1.126 +command prompt users, too.
   1.127 +</para>
   1.128 +
   1.129 +<para>When Mercurial does automatic pattern matching on Windows, it uses
   1.130 +<literal>glob</literal> syntax.  You can thus omit the <quote><literal>glob:</literal></quote> prefix
   1.131 +on Windows, but it's safe to use it, too.
   1.132 +</para>
   1.133 +
   1.134 +<para>The <literal>re</literal> syntax is more powerful; it lets you specify patterns
   1.135 +using regular expressions, also known as regexps.
   1.136 +</para>
   1.137 +
   1.138 +<para>By the way, in the examples that follow, notice that I'm careful to
   1.139 +wrap all of my patterns in quote characters, so that they won't get
   1.140 +expanded by the shell before Mercurial sees them.
   1.141 +</para>
   1.142 +
   1.143 +<sect2>
   1.144 +<title>Shell-style <literal>glob</literal> patterns</title>
   1.145 +
   1.146 +<para>This is an overview of the kinds of patterns you can use when you're
   1.147 +matching on glob patterns.
   1.148 +</para>
   1.149 +
   1.150 +<para>The <quote><literal>*</literal></quote> character matches any string, within a single
   1.151 +directory.
   1.152 +<!-- &interaction.filenames.glob.star; -->
   1.153 +</para>
   1.154 +
   1.155 +<para>The <quote><literal>**</literal></quote> pattern matches any string, and crosses directory
   1.156 +boundaries.  It's not a standard Unix glob token, but it's accepted by
   1.157 +several popular Unix shells, and is very useful.
   1.158 +<!-- &interaction.filenames.glob.starstar; -->
   1.159 +</para>
   1.160 +
   1.161 +<para>The <quote><literal>?</literal></quote> pattern matches any single character.
   1.162 +<!-- &interaction.filenames.glob.question; -->
   1.163 +</para>
   1.164 +
   1.165 +<para>The <quote><literal>[</literal></quote> character begins a <emphasis>character class</emphasis>.  This
   1.166 +matches any single character within the class.  The class ends with a
   1.167 +<quote><literal>]</literal></quote> character.  A class may contain multiple <emphasis>range</emphasis>s
   1.168 +of the form <quote><literal>a-f</literal></quote>, which is shorthand for
   1.169 +<quote><literal>abcdef</literal></quote>.
   1.170 +<!-- &interaction.filenames.glob.range; -->
   1.171 +If the first character after the <quote><literal>[</literal></quote> in a character class
   1.172 +is a <quote><literal>!</literal></quote>, it <emphasis>negates</emphasis> the class, making it match any
   1.173 +single character not in the class.
   1.174 +</para>
   1.175 +
   1.176 +<para>A <quote><literal>{</literal></quote> begins a group of subpatterns, where the whole group
   1.177 +matches if any subpattern in the group matches.  The <quote><literal>,</literal></quote>
   1.178 +character separates subpatterns, and <quote>\texttt{}}</quote> ends the group.
   1.179 +<!-- &interaction.filenames.glob.group; -->
   1.180 +</para>
   1.181 +
   1.182 +<sect3>
   1.183 +<title>Watch out!</title>
   1.184 +
   1.185 +<para>Don't forget that if you want to match a pattern in any directory, you
   1.186 +should not be using the <quote><literal>*</literal></quote> match-any token, as this will
   1.187 +only match within one directory.  Instead, use the <quote><literal>**</literal></quote>
   1.188 +token.  This small example illustrates the difference between the two.
   1.189 +<!-- &interaction.filenames.glob.star-starstar; -->
   1.190 +</para>
   1.191 +
   1.192 +</sect3>
   1.193 +</sect2>
   1.194 +<sect2>
   1.195 +<title>Regular expression matching with <literal>re</literal> patterns</title>
   1.196 +
   1.197 +<para>Mercurial accepts the same regular expression syntax as the Python
   1.198 +programming language (it uses Python's regexp engine internally).
   1.199 +This is based on the Perl language's regexp syntax, which is the most
   1.200 +popular dialect in use (it's also used in Java, for example).
   1.201 +</para>
   1.202 +
   1.203 +<para>I won't discuss Mercurial's regexp dialect in any detail here, as
   1.204 +regexps are not often used.  Perl-style regexps are in any case
   1.205 +already exhaustively documented on a multitude of web sites, and in
   1.206 +many books.  Instead, I will focus here on a few things you should
   1.207 +know if you find yourself needing to use regexps with Mercurial.
   1.208 +</para>
   1.209 +
   1.210 +<para>A regexp is matched against an entire file name, relative to the root
   1.211 +of the repository.  In other words, even if you're already in
   1.212 +subbdirectory <filename class="directory">foo</filename>, if you want to match files under this
   1.213 +directory, your pattern must start with <quote><literal>foo/</literal></quote>.
   1.214 +</para>
   1.215 +
   1.216 +<para>One thing to note, if you're familiar with Perl-style regexps, is that
   1.217 +Mercurial's are <emphasis>rooted</emphasis>.  That is, a regexp starts matching
   1.218 +against the beginning of a string; it doesn't look for a match
   1.219 +anywhere within the string.  To match anywhere in a string, start
   1.220 +your pattern with <quote><literal>.*</literal></quote>.
   1.221 +</para>
   1.222 +
   1.223 +</sect2>
   1.224 +</sect1>
   1.225 +<sect1>
   1.226 +<title>Filtering files</title>
   1.227 +
   1.228 +<para>Not only does Mercurial give you a variety of ways to specify files;
   1.229 +it lets you further winnow those files using <emphasis>filters</emphasis>.  Commands
   1.230 +that work with file names accept two filtering options.
   1.231 +</para>
   1.232 +<itemizedlist>
   1.233 +<listitem><para><option role="hg-opt-global">-I</option>, or <option role="hg-opt-global">--include</option>, lets you specify a pattern
   1.234 +  that file names must match in order to be processed.
   1.235 +</para>
   1.236 +</listitem>
   1.237 +<listitem><para><option role="hg-opt-global">-X</option>, or <option role="hg-opt-global">--exclude</option>, gives you a way to
   1.238 +  <emphasis>avoid</emphasis> processing files, if they match this pattern.
   1.239 +</para>
   1.240 +</listitem></itemizedlist>
   1.241 +<para>You can provide multiple <option role="hg-opt-global">-I</option> and <option role="hg-opt-global">-X</option> options on the
   1.242 +command line, and intermix them as you please.  Mercurial interprets
   1.243 +the patterns you provide using glob syntax by default (but you can use
   1.244 +regexps if you need to).
   1.245 +</para>
   1.246 +
   1.247 +<para>You can read a <option role="hg-opt-global">-I</option> filter as <quote>process only the files that
   1.248 +match this filter</quote>.
   1.249 +<!-- &interaction.filenames.filter.include; -->
   1.250 +The <option role="hg-opt-global">-X</option> filter is best read as <quote>process only the files that
   1.251 +don't match this pattern</quote>.
   1.252 +<!-- &interaction.filenames.filter.exclude; -->
   1.253 +</para>
   1.254 +
   1.255 +</sect1>
   1.256 +<sect1>
   1.257 +<title>Ignoring unwanted files and directories</title>
   1.258 +
   1.259 +<para>XXX.
   1.260 +</para>
   1.261 +
   1.262 +</sect1>
   1.263 +<sect1>
   1.264 +<title>Case sensitivity</title>
   1.265 +<para>\label{sec:names:case}
   1.266 +</para>
   1.267 +
   1.268 +<para>If you're working in a mixed development environment that contains
   1.269 +both Linux (or other Unix) systems and Macs or Windows systems, you
   1.270 +should keep in the back of your mind the knowledge that they treat the
   1.271 +case (<quote>N</quote> versus <quote>n</quote>) of file names in incompatible ways.  This is
   1.272 +not very likely to affect you, and it's easy to deal with if it does,
   1.273 +but it could surprise you if you don't know about it.
   1.274 +</para>
   1.275 +
   1.276 +<para>Operating systems and filesystems differ in the way they handle the
   1.277 +<emphasis>case</emphasis> of characters in file and directory names.  There are
   1.278 +three common ways to handle case in names.
   1.279 +</para>
   1.280 +<itemizedlist>
   1.281 +<listitem><para>Completely case insensitive.  Uppercase and lowercase versions
   1.282 +  of a letter are treated as identical, both when creating a file and
   1.283 +  during subsequent accesses.  This is common on older DOS-based
   1.284 +  systems.
   1.285 +</para>
   1.286 +</listitem>
   1.287 +<listitem><para>Case preserving, but insensitive.  When a file or directory is
   1.288 +  created, the case of its name is stored, and can be retrieved and
   1.289 +  displayed by the operating system.  When an existing file is being
   1.290 +  looked up, its case is ignored.  This is the standard arrangement on
   1.291 +  Windows and MacOS.  The names <filename>foo</filename> and <filename>FoO</filename>
   1.292 +  identify the same file.  This treatment of uppercase and lowercase
   1.293 +  letters as interchangeable is also referred to as \emph{case
   1.294 +    folding}.
   1.295 +</para>
   1.296 +</listitem>
   1.297 +<listitem><para>Case sensitive.  The case of a name is significant at all times.
   1.298 +  The names <filename>foo</filename> and {FoO} identify different files.  This
   1.299 +  is the way Linux and Unix systems normally work.
   1.300 +</para>
   1.301 +</listitem></itemizedlist>
   1.302 +
   1.303 +<para>On Unix-like systems, it is possible to have any or all of the above
   1.304 +ways of handling case in action at once.  For example, if you use a
   1.305 +USB thumb drive formatted with a FAT32 filesystem on a Linux system,
   1.306 +Linux will handle names on that filesystem in a case preserving, but
   1.307 +insensitive, way.
   1.308 +</para>
   1.309 +
   1.310 +<sect2>
   1.311 +<title>Safe, portable repository storage</title>
   1.312 +
   1.313 +<para>Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>.  It
   1.314 +translates file names so that they can be safely stored on both case
   1.315 +sensitive and case insensitive filesystems.  This means that you can
   1.316 +use normal file copying tools to transfer a Mercurial repository onto,
   1.317 +for example, a USB thumb drive, and safely move that drive and
   1.318 +repository back and forth between a Mac, a PC running Windows, and a
   1.319 +Linux box.
   1.320 +</para>
   1.321 +
   1.322 +</sect2>
   1.323 +<sect2>
   1.324 +<title>Detecting case conflicts</title>
   1.325 +
   1.326 +<para>When operating in the working directory, Mercurial honours the naming
   1.327 +policy of the filesystem where the working directory is located.  If
   1.328 +the filesystem is case preserving, but insensitive, Mercurial will
   1.329 +treat names that differ only in case as the same.
   1.330 +</para>
   1.331 +
   1.332 +<para>An important aspect of this approach is that it is possible to commit
   1.333 +a changeset on a case sensitive (typically Linux or Unix) filesystem
   1.334 +that will cause trouble for users on case insensitive (usually Windows
   1.335 +and MacOS) users.  If a Linux user commits changes to two files, one
   1.336 +named <filename>myfile.c</filename> and the other named <filename>MyFile.C</filename>,
   1.337 +they will be stored correctly in the repository.  And in the working
   1.338 +directories of other Linux users, they will be correctly represented
   1.339 +as separate files.
   1.340 +</para>
   1.341 +
   1.342 +<para>If a Windows or Mac user pulls this change, they will not initially
   1.343 +have a problem, because Mercurial's repository storage mechanism is
   1.344 +case safe.  However, once they try to <command role="hg-cmd">hg update</command> the working
   1.345 +directory to that changeset, or <command role="hg-cmd">hg merge</command> with that changeset,
   1.346 +Mercurial will spot the conflict between the two file names that the
   1.347 +filesystem would treat as the same, and forbid the update or merge
   1.348 +from occurring.
   1.349 +</para>
   1.350 +
   1.351 +</sect2>
   1.352 +<sect2>
   1.353 +<title>Fixing a case conflict</title>
   1.354 +
   1.355 +<para>If you are using Windows or a Mac in a mixed environment where some of
   1.356 +your collaborators are using Linux or Unix, and Mercurial reports a
   1.357 +case folding conflict when you try to <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg merge</command>,
   1.358 +the procedure to fix the problem is simple.
   1.359 +</para>
   1.360 +
   1.361 +<para>Just find a nearby Linux or Unix box, clone the problem repository
   1.362 +onto it, and use Mercurial's <command role="hg-cmd">hg rename</command> command to change the
   1.363 +names of any offending files or directories so that they will no
   1.364 +longer cause case folding conflicts.  Commit this change, <command role="hg-cmd">hg pull</command>
   1.365 +or <command role="hg-cmd">hg push</command> it across to your Windows or MacOS system, and
   1.366 +<command role="hg-cmd">hg update</command> to the revision with the non-conflicting names.
   1.367 +</para>
   1.368 +
   1.369 +<para>The changeset with case-conflicting names will remain in your
   1.370 +project's history, and you still won't be able to <command role="hg-cmd">hg update</command> your
   1.371 +working directory to that changeset on a Windows or MacOS system, but
   1.372 +you can continue development unimpeded.
   1.373 +</para>
   1.374 +
   1.375 +<note>
   1.376 +<para>  Prior to version 0.9.3, Mercurial did not use a case safe repository
   1.377 +  storage mechanism, and did not detect case folding conflicts.  If
   1.378 +  you are using an older version of Mercurial on Windows or MacOS, I
   1.379 +  strongly recommend that you upgrade.
   1.380 +</para>
   1.381 +</note>
   1.382 +
   1.383 +</sect2>
   1.384 +</sect1>
   1.385 +</chapter>
   1.386 +
   1.387 +<!--
   1.388 +local variables: 
   1.389 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.390 +end:
   1.391 +-->
   1.392 \ No newline at end of file