hgbook
diff fr/ch07-filenames.xml @ 1004:0298bccbb8ee
french small corrections, gestion de révisions au lieu de gestion de sources ou gestion de versions.
author | Wilk |
---|---|
date | Sun Sep 13 14:08:00 2009 +0200 (2009-09-13) |
parents | 6b680d569bb4 f0110009e946 |
children |
line diff
1.1 --- a/fr/ch07-filenames.xml Sun Aug 16 04:58:01 2009 +0200 1.2 +++ b/fr/ch07-filenames.xml Sun Sep 13 14:08:00 2009 +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 +-->