hgbook
diff en/ch07-filenames.xml @ 559:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Feb 18 00:22:09 2009 -0800 (2009-02-18) |
parents | en/ch07-filenames.tex@f72b7e6cbe90 |
children | 21c62e09b99f |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch07-filenames.xml Wed Feb 18 00:22:09 2009 -0800 1.3 @@ -0,0 +1,392 @@ 1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 + 1.6 +<chapter id="chap:names"> 1.7 + <title>File names and pattern matching</title> 1.8 + 1.9 + <para>Mercurial provides mechanisms that let you work with file 1.10 + names in a consistent and expressive way.</para> 1.11 + 1.12 + <sect1> 1.13 + <title>Simple file naming</title> 1.14 + 1.15 + <para>Mercurial uses a unified piece of machinery <quote>under the 1.16 + hood</quote> to handle file names. Every command behaves 1.17 + uniformly with respect to file names. The way in which commands 1.18 + work with file names is as follows.</para> 1.19 + 1.20 + <para>If you explicitly name real files on the command line, 1.21 + Mercurial works with exactly those files, as you would expect. 1.22 + <!-- &interaction.filenames.files; --></para> 1.23 + 1.24 + <para>When you provide a directory name, Mercurial will interpret 1.25 + this as <quote>operate on every file in this directory and its 1.26 + subdirectories</quote>. Mercurial traverses the files and 1.27 + subdirectories in a directory in alphabetical order. When it 1.28 + encounters a subdirectory, it will traverse that subdirectory 1.29 + before continuing with the current directory. <!-- 1.30 + &interaction.filenames.dirs; --></para> 1.31 + 1.32 + </sect1> 1.33 + <sect1> 1.34 + <title>Running commands without any file names</title> 1.35 + 1.36 + <para>Mercurial's commands that work with file names have useful 1.37 + default behaviours when you invoke them without providing any 1.38 + file names or patterns. What kind of behaviour you should 1.39 + expect depends on what the command does. Here are a few rules 1.40 + of thumb you can use to predict what a command is likely to do 1.41 + if you don't give it any names to work with.</para> 1.42 + <itemizedlist> 1.43 + <listitem><para>Most commands will operate on the entire working 1.44 + directory. This is what the <command role="hg-cmd">hg 1.45 + add</command> command does, for example.</para> 1.46 + </listitem> 1.47 + <listitem><para>If the command has effects that are difficult or 1.48 + impossible to reverse, it will force you to explicitly 1.49 + provide at least one name or pattern (see below). This 1.50 + protects you from accidentally deleting files by running 1.51 + <command role="hg-cmd">hg remove</command> with no 1.52 + arguments, for example.</para> 1.53 + </listitem></itemizedlist> 1.54 + 1.55 + <para>It's easy to work around these default behaviours if they 1.56 + don't suit you. If a command normally operates on the whole 1.57 + working directory, you can invoke it on just the current 1.58 + directory and its subdirectories by giving it the name 1.59 + <quote><filename class="directory">.</filename></quote>. <!-- 1.60 + &interaction.filenames.wdir-subdir; --></para> 1.61 + 1.62 + <para>Along the same lines, some commands normally print file 1.63 + names relative to the root of the repository, even if you're 1.64 + invoking them from a subdirectory. Such a command will print 1.65 + file names relative to your subdirectory if you give it explicit 1.66 + names. Here, we're going to run <command role="hg-cmd">hg 1.67 + status</command> from a subdirectory, and get it to operate on 1.68 + the entire working directory while printing file names relative 1.69 + to our subdirectory, by passing it the output of the <command 1.70 + role="hg-cmd">hg root</command> command. <!-- 1.71 + &interaction.filenames.wdir-relname; --></para> 1.72 + 1.73 + </sect1> 1.74 + <sect1> 1.75 + <title>Telling you what's going on</title> 1.76 + 1.77 + <para>The <command role="hg-cmd">hg add</command> example in the 1.78 + preceding section illustrates something else that's helpful 1.79 + about Mercurial commands. If a command operates on a file that 1.80 + you didn't name explicitly on the command line, it will usually 1.81 + print the name of the file, so that you will not be surprised 1.82 + what's going on.</para> 1.83 + 1.84 + <para>The principle here is of <emphasis>least 1.85 + surprise</emphasis>. If you've exactly named a file on the 1.86 + command line, there's no point in repeating it back at you. If 1.87 + Mercurial is acting on a file <emphasis>implicitly</emphasis>, 1.88 + because you provided no names, or a directory, or a pattern (see 1.89 + below), it's safest to tell you what it's doing.</para> 1.90 + 1.91 + <para>For commands that behave this way, you can silence them 1.92 + using the <option role="hg-opt-global">-q</option> option. You 1.93 + can also get them to print the name of every file, even those 1.94 + you've named explicitly, using the <option 1.95 + role="hg-opt-global">-v</option> option.</para> 1.96 + 1.97 + </sect1> 1.98 + <sect1> 1.99 + <title>Using patterns to identify files</title> 1.100 + 1.101 + <para>In addition to working with file and directory names, 1.102 + Mercurial lets you use <emphasis>patterns</emphasis> to identify 1.103 + files. Mercurial's pattern handling is expressive.</para> 1.104 + 1.105 + <para>On Unix-like systems (Linux, MacOS, etc.), the job of 1.106 + matching file names to patterns normally falls to the shell. On 1.107 + these systems, you must explicitly tell Mercurial that a name is 1.108 + a pattern. On Windows, the shell does not expand patterns, so 1.109 + Mercurial will automatically identify names that are patterns, 1.110 + and expand them for you.</para> 1.111 + 1.112 + <para>To provide a pattern in place of a regular name on the 1.113 + command line, the mechanism is simple:</para> 1.114 + <programlisting>syntax:patternbody</programlisting> 1.115 + <para>That is, a pattern is identified by a short text string that 1.116 + says what kind of pattern this is, followed by a colon, followed 1.117 + by the actual pattern.</para> 1.118 + 1.119 + <para>Mercurial supports two kinds of pattern syntax. The most 1.120 + frequently used is called <literal>glob</literal>; this is the 1.121 + same kind of pattern matching used by the Unix shell, and should 1.122 + be familiar to Windows command prompt users, too.</para> 1.123 + 1.124 + <para>When Mercurial does automatic pattern matching on Windows, 1.125 + it uses <literal>glob</literal> syntax. You can thus omit the 1.126 + <quote><literal>glob:</literal></quote> prefix on Windows, but 1.127 + it's safe to use it, too.</para> 1.128 + 1.129 + <para>The <literal>re</literal> syntax is more powerful; it lets 1.130 + you specify patterns using regular expressions, also known as 1.131 + regexps.</para> 1.132 + 1.133 + <para>By the way, in the examples that follow, notice that I'm 1.134 + careful to wrap all of my patterns in quote characters, so that 1.135 + they won't get expanded by the shell before Mercurial sees 1.136 + them.</para> 1.137 + 1.138 + <sect2> 1.139 + <title>Shell-style <literal>glob</literal> patterns</title> 1.140 + 1.141 + <para>This is an overview of the kinds of patterns you can use 1.142 + when you're matching on glob patterns.</para> 1.143 + 1.144 + <para>The <quote><literal>*</literal></quote> character matches 1.145 + any string, within a single directory. <!-- 1.146 + &interaction.filenames.glob.star; --></para> 1.147 + 1.148 + <para>The <quote><literal>**</literal></quote> pattern matches 1.149 + any string, and crosses directory boundaries. It's not a 1.150 + standard Unix glob token, but it's accepted by several popular 1.151 + Unix shells, and is very useful. <!-- 1.152 + &interaction.filenames.glob.starstar; --></para> 1.153 + 1.154 + <para>The <quote><literal>?</literal></quote> pattern matches 1.155 + any single character. <!-- 1.156 + &interaction.filenames.glob.question; --></para> 1.157 + 1.158 + <para>The <quote><literal>[</literal></quote> character begins a 1.159 + <emphasis>character class</emphasis>. This matches any single 1.160 + character within the class. The class ends with a 1.161 + <quote><literal>]</literal></quote> character. A class may 1.162 + contain multiple <emphasis>range</emphasis>s of the form 1.163 + <quote><literal>a-f</literal></quote>, which is shorthand for 1.164 + <quote><literal>abcdef</literal></quote>. <!-- 1.165 + &interaction.filenames.glob.range; --> If the first character 1.166 + after the <quote><literal>[</literal></quote> in a character 1.167 + class is a <quote><literal>!</literal></quote>, it 1.168 + <emphasis>negates</emphasis> the class, making it match any 1.169 + single character not in the class.</para> 1.170 + 1.171 + <para>A <quote><literal>{</literal></quote> begins a group of 1.172 + subpatterns, where the whole group matches if any subpattern 1.173 + in the group matches. The <quote><literal>,</literal></quote> 1.174 + character separates subpatterns, and <quote>\texttt{}}</quote> 1.175 + ends the group. <!-- &interaction.filenames.glob.group; 1.176 + --></para> 1.177 + 1.178 + <sect3> 1.179 + <title>Watch out!</title> 1.180 + 1.181 + <para>Don't forget that if you want to match a pattern in any 1.182 + directory, you should not be using the 1.183 + <quote><literal>*</literal></quote> match-any token, as this 1.184 + will only match within one directory. Instead, use the 1.185 + <quote><literal>**</literal></quote> token. This small 1.186 + example illustrates the difference between the two. <!-- 1.187 + &interaction.filenames.glob.star-starstar; --></para> 1.188 + 1.189 + </sect3> 1.190 + </sect2> 1.191 + <sect2> 1.192 + <title>Regular expression matching with <literal>re</literal> 1.193 + patterns</title> 1.194 + 1.195 + <para>Mercurial accepts the same regular expression syntax as 1.196 + the Python programming language (it uses Python's regexp 1.197 + engine internally). This is based on the Perl language's 1.198 + regexp syntax, which is the most popular dialect in use (it's 1.199 + also used in Java, for example).</para> 1.200 + 1.201 + <para>I won't discuss Mercurial's regexp dialect in any detail 1.202 + here, as regexps are not often used. Perl-style regexps are 1.203 + in any case already exhaustively documented on a multitude of 1.204 + web sites, and in many books. Instead, I will focus here on a 1.205 + few things you should know if you find yourself needing to use 1.206 + regexps with Mercurial.</para> 1.207 + 1.208 + <para>A regexp is matched against an entire file name, relative 1.209 + to the root of the repository. In other words, even if you're 1.210 + already in subbdirectory <filename 1.211 + class="directory">foo</filename>, if you want to match files 1.212 + under this directory, your pattern must start with 1.213 + <quote><literal>foo/</literal></quote>.</para> 1.214 + 1.215 + <para>One thing to note, if you're familiar with Perl-style 1.216 + regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 1.217 + That is, a regexp starts matching against the beginning of a 1.218 + string; it doesn't look for a match anywhere within the 1.219 + string. To match anywhere in a string, start your pattern 1.220 + with <quote><literal>.*</literal></quote>.</para> 1.221 + 1.222 + </sect2> 1.223 + </sect1> 1.224 + <sect1> 1.225 + <title>Filtering files</title> 1.226 + 1.227 + <para>Not only does Mercurial give you a variety of ways to 1.228 + specify files; it lets you further winnow those files using 1.229 + <emphasis>filters</emphasis>. Commands that work with file 1.230 + names accept two filtering options.</para> 1.231 + <itemizedlist> 1.232 + <listitem><para><option role="hg-opt-global">-I</option>, or 1.233 + <option role="hg-opt-global">--include</option>, lets you 1.234 + specify a pattern that file names must match in order to be 1.235 + processed.</para> 1.236 + </listitem> 1.237 + <listitem><para><option role="hg-opt-global">-X</option>, or 1.238 + <option role="hg-opt-global">--exclude</option>, gives you a 1.239 + way to <emphasis>avoid</emphasis> processing files, if they 1.240 + match this pattern.</para> 1.241 + </listitem></itemizedlist> 1.242 + <para>You can provide multiple <option 1.243 + role="hg-opt-global">-I</option> and <option 1.244 + role="hg-opt-global">-X</option> options on the command line, 1.245 + and intermix them as you please. Mercurial interprets the 1.246 + patterns you provide using glob syntax by default (but you can 1.247 + use regexps if you need to).</para> 1.248 + 1.249 + <para>You can read a <option role="hg-opt-global">-I</option> 1.250 + filter as <quote>process only the files that match this 1.251 + filter</quote>. <!-- &interaction.filenames.filter.include; 1.252 + --> The <option role="hg-opt-global">-X</option> filter is best 1.253 + read as <quote>process only the files that don't match this 1.254 + pattern</quote>. <!-- &interaction.filenames.filter.exclude; 1.255 + --></para> 1.256 + 1.257 + </sect1> 1.258 + <sect1> 1.259 + <title>Ignoring unwanted files and directories</title> 1.260 + 1.261 + <para>XXX.</para> 1.262 + 1.263 + </sect1> 1.264 + <sect1 id="sec:names:case"> 1.265 + <title>Case sensitivity</title> 1.266 + 1.267 + <para>If you're working in a mixed development environment that 1.268 + contains both Linux (or other Unix) systems and Macs or Windows 1.269 + systems, you should keep in the back of your mind the knowledge 1.270 + that they treat the case (<quote>N</quote> versus 1.271 + <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 1.273 + does, but it could surprise you if you don't know about 1.274 + it.</para> 1.275 + 1.276 + <para>Operating systems and filesystems differ in the way they 1.277 + handle the <emphasis>case</emphasis> of characters in file and 1.278 + directory names. There are three common ways to handle case in 1.279 + names.</para> 1.280 + <itemizedlist> 1.281 + <listitem><para>Completely case insensitive. Uppercase and 1.282 + lowercase versions of a letter are treated as identical, 1.283 + both when creating a file and during subsequent accesses. 1.284 + This is common on older DOS-based systems.</para> 1.285 + </listitem> 1.286 + <listitem><para>Case preserving, but insensitive. When a file 1.287 + or directory is created, the case of its name is stored, and 1.288 + can be retrieved and displayed by the operating system. 1.289 + When an existing file is being looked up, its case is 1.290 + ignored. This is the standard arrangement on Windows and 1.291 + MacOS. The names <filename>foo</filename> and 1.292 + <filename>FoO</filename> identify the same file. This 1.293 + treatment of uppercase and lowercase letters as 1.294 + interchangeable is also referred to as <emphasis>case 1.295 + folding</emphasis>.</para> 1.296 + </listitem> 1.297 + <listitem><para>Case sensitive. The case of a name is 1.298 + significant at all times. The names <filename>foo</filename> 1.299 + and {FoO} identify different files. This is the way Linux 1.300 + and Unix systems normally work.</para> 1.301 + </listitem></itemizedlist> 1.302 + 1.303 + <para>On Unix-like systems, it is possible to have any or all of 1.304 + the above ways of handling case in action at once. For example, 1.305 + if you use a USB thumb drive formatted with a FAT32 filesystem 1.306 + on a Linux system, Linux will handle names on that filesystem in 1.307 + a case preserving, but insensitive, way.</para> 1.308 + 1.309 + <sect2> 1.310 + <title>Safe, portable repository storage</title> 1.311 + 1.312 + <para>Mercurial's repository storage mechanism is <emphasis>case 1.313 + safe</emphasis>. It translates file names so that they can 1.314 + be safely stored on both case sensitive and case insensitive 1.315 + filesystems. This means that you can use normal file copying 1.316 + tools to transfer a Mercurial repository onto, for example, a 1.317 + USB thumb drive, and safely move that drive and repository 1.318 + back and forth between a Mac, a PC running Windows, and a 1.319 + Linux box.</para> 1.320 + 1.321 + </sect2> 1.322 + <sect2> 1.323 + <title>Detecting case conflicts</title> 1.324 + 1.325 + <para>When operating in the working directory, Mercurial honours 1.326 + the naming policy of the filesystem where the working 1.327 + directory is located. If the filesystem is case preserving, 1.328 + but insensitive, Mercurial will treat names that differ only 1.329 + in case as the same.</para> 1.330 + 1.331 + <para>An important aspect of this approach is that it is 1.332 + possible to commit a changeset on a case sensitive (typically 1.333 + Linux or Unix) filesystem that will cause trouble for users on 1.334 + case insensitive (usually Windows and MacOS) users. If a 1.335 + Linux user commits changes to two files, one named 1.336 + <filename>myfile.c</filename> and the other named 1.337 + <filename>MyFile.C</filename>, they will be stored correctly 1.338 + in the repository. And in the working directories of other 1.339 + Linux users, they will be correctly represented as separate 1.340 + files.</para> 1.341 + 1.342 + <para>If a Windows or Mac user pulls this change, they will not 1.343 + initially have a problem, because Mercurial's repository 1.344 + storage mechanism is case safe. However, once they try to 1.345 + <command role="hg-cmd">hg update</command> the working 1.346 + directory to that changeset, or <command role="hg-cmd">hg 1.347 + merge</command> with that changeset, Mercurial will spot the 1.348 + conflict between the two file names that the filesystem would 1.349 + treat as the same, and forbid the update or merge from 1.350 + occurring.</para> 1.351 + 1.352 + </sect2> 1.353 + <sect2> 1.354 + <title>Fixing a case conflict</title> 1.355 + 1.356 + <para>If you are using Windows or a Mac in a mixed environment 1.357 + where some of your collaborators are using Linux or Unix, and 1.358 + Mercurial reports a case folding conflict when you try to 1.359 + <command role="hg-cmd">hg update</command> or <command 1.360 + role="hg-cmd">hg merge</command>, the procedure to fix the 1.361 + problem is simple.</para> 1.362 + 1.363 + <para>Just find a nearby Linux or Unix box, clone the problem 1.364 + repository onto it, and use Mercurial's <command 1.365 + role="hg-cmd">hg rename</command> command to change the 1.366 + names of any offending files or directories so that they will 1.367 + no longer cause case folding conflicts. Commit this change, 1.368 + <command role="hg-cmd">hg pull</command> or <command 1.369 + role="hg-cmd">hg push</command> it across to your Windows or 1.370 + MacOS system, and <command role="hg-cmd">hg update</command> 1.371 + to the revision with the non-conflicting names.</para> 1.372 + 1.373 + <para>The changeset with case-conflicting names will remain in 1.374 + your project's history, and you still won't be able to 1.375 + <command role="hg-cmd">hg update</command> your working 1.376 + directory to that changeset on a Windows or MacOS system, but 1.377 + you can continue development unimpeded.</para> 1.378 + 1.379 + <note> 1.380 + <para> Prior to version 0.9.3, Mercurial did not use a case 1.381 + safe repository storage mechanism, and did not detect case 1.382 + folding conflicts. If you are using an older version of 1.383 + Mercurial on Windows or MacOS, I strongly recommend that you 1.384 + upgrade.</para> 1.385 + </note> 1.386 + 1.387 + </sect2> 1.388 + </sect1> 1.389 +</chapter> 1.390 + 1.391 +<!-- 1.392 +local variables: 1.393 +sgml-parent-document: ("00book.xml" "book" "chapter") 1.394 +end: 1.395 +-->