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