bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
dongsheng@625: <chapter id="chap.names">
bos@572:   <?dbhtml filename="file-names-and-pattern-matching.html"?>
bos@559:   <title>File names and pattern matching</title>
bos@559: 
bos@559:   <para>Mercurial provides mechanisms that let you work with file
bos@559:     names in a consistent and expressive way.</para>
bos@559: 
bos@559:   <sect1>
bos@559:     <title>Simple file naming</title>
bos@559: 
bos@559:     <para>Mercurial uses a unified piece of machinery <quote>under the
bos@559: 	hood</quote> to handle file names.  Every command behaves
bos@559:       uniformly with respect to file names.  The way in which commands
bos@559:       work with file names is as follows.</para>
bos@559: 
bos@559:     <para>If you explicitly name real files on the command line,
bos@559:       Mercurial works with exactly those files, as you would expect.
bos@567:       &interaction.filenames.files;</para>
bos@559: 
bos@559:     <para>When you provide a directory name, Mercurial will interpret
bos@559:       this as <quote>operate on every file in this directory and its
bos@559: 	subdirectories</quote>. Mercurial traverses the files and
bos@559:       subdirectories in a directory in alphabetical order.  When it
bos@559:       encounters a subdirectory, it will traverse that subdirectory
bos@567:       before continuing with the current directory.</para>
bos@567: 
bos@567:       &interaction.filenames.dirs;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Running commands without any file names</title>
bos@559: 
bos@559:     <para>Mercurial's commands that work with file names have useful
bos@559:       default behaviours when you invoke them without providing any
bos@559:       file names or patterns.  What kind of behaviour you should
bos@559:       expect depends on what the command does.  Here are a few rules
bos@559:       of thumb you can use to predict what a command is likely to do
bos@559:       if you don't give it any names to work with.</para>
bos@559:     <itemizedlist>
bos@559:       <listitem><para>Most commands will operate on the entire working
bos@559: 	  directory. This is what the <command role="hg-cmd">hg
bos@559: 	    add</command> command does, for example.</para>
bos@559:       </listitem>
bos@559:       <listitem><para>If the command has effects that are difficult or
bos@559: 	  impossible to reverse, it will force you to explicitly
bos@559: 	  provide at least one name or pattern (see below).  This
bos@559: 	  protects you from accidentally deleting files by running
bos@559: 	  <command role="hg-cmd">hg remove</command> with no
bos@559: 	  arguments, for example.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@559:     <para>It's easy to work around these default behaviours if they
bos@559:       don't suit you.  If a command normally operates on the whole
bos@559:       working directory, you can invoke it on just the current
bos@559:       directory and its subdirectories by giving it the name
bos@567:       <quote><filename class="directory">.</filename></quote>.</para>
bos@567: 
bos@567:     &interaction.filenames.wdir-subdir;
bos@559: 
bos@559:     <para>Along the same lines, some commands normally print file
bos@559:       names relative to the root of the repository, even if you're
bos@559:       invoking them from a subdirectory.  Such a command will print
bos@559:       file names relative to your subdirectory if you give it explicit
bos@559:       names.  Here, we're going to run <command role="hg-cmd">hg
bos@559: 	status</command> from a subdirectory, and get it to operate on
bos@559:       the entire working directory while printing file names relative
bos@559:       to our subdirectory, by passing it the output of the <command
bos@567: 	role="hg-cmd">hg root</command> command.</para>
bos@567: 
bos@567:       &interaction.filenames.wdir-relname;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Telling you what's going on</title>
bos@559: 
bos@559:     <para>The <command role="hg-cmd">hg add</command> example in the
bos@559:       preceding section illustrates something else that's helpful
bos@559:       about Mercurial commands.  If a command operates on a file that
bos@559:       you didn't name explicitly on the command line, it will usually
bos@559:       print the name of the file, so that you will not be surprised
bos@559:       what's going on.</para>
bos@559: 
bos@559:     <para>The principle here is of <emphasis>least
bos@559: 	surprise</emphasis>.  If you've exactly named a file on the
bos@559:       command line, there's no point in repeating it back at you.  If
bos@559:       Mercurial is acting on a file <emphasis>implicitly</emphasis>,
bos@559:       because you provided no names, or a directory, or a pattern (see
bos@559:       below), it's safest to tell you what it's doing.</para>
bos@559: 
bos@559:     <para>For commands that behave this way, you can silence them
bos@559:       using the <option role="hg-opt-global">-q</option> option.  You
bos@559:       can also get them to print the name of every file, even those
bos@559:       you've named explicitly, using the <option
bos@559: 	role="hg-opt-global">-v</option> option.</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Using patterns to identify files</title>
bos@559: 
bos@559:     <para>In addition to working with file and directory names,
bos@559:       Mercurial lets you use <emphasis>patterns</emphasis> to identify
bos@559:       files.  Mercurial's pattern handling is expressive.</para>
bos@559: 
bos@559:     <para>On Unix-like systems (Linux, MacOS, etc.), the job of
bos@559:       matching file names to patterns normally falls to the shell.  On
bos@559:       these systems, you must explicitly tell Mercurial that a name is
bos@559:       a pattern.  On Windows, the shell does not expand patterns, so
bos@559:       Mercurial will automatically identify names that are patterns,
bos@559:       and expand them for you.</para>
bos@559: 
bos@559:     <para>To provide a pattern in place of a regular name on the
bos@559:       command line, the mechanism is simple:</para>
bos@559:     <programlisting>syntax:patternbody</programlisting>
bos@559:     <para>That is, a pattern is identified by a short text string that
bos@559:       says what kind of pattern this is, followed by a colon, followed
bos@559:       by the actual pattern.</para>
bos@559: 
bos@559:     <para>Mercurial supports two kinds of pattern syntax.  The most
bos@559:       frequently used is called <literal>glob</literal>; this is the
bos@559:       same kind of pattern matching used by the Unix shell, and should
bos@559:       be familiar to Windows command prompt users, too.</para>
bos@559: 
bos@559:     <para>When Mercurial does automatic pattern matching on Windows,
bos@559:       it uses <literal>glob</literal> syntax.  You can thus omit the
bos@559:       <quote><literal>glob:</literal></quote> prefix on Windows, but
bos@559:       it's safe to use it, too.</para>
bos@559: 
bos@559:     <para>The <literal>re</literal> syntax is more powerful; it lets
bos@559:       you specify patterns using regular expressions, also known as
bos@559:       regexps.</para>
bos@559: 
bos@559:     <para>By the way, in the examples that follow, notice that I'm
bos@559:       careful to wrap all of my patterns in quote characters, so that
bos@559:       they won't get expanded by the shell before Mercurial sees
bos@559:       them.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Shell-style <literal>glob</literal> patterns</title>
bos@559: 
bos@559:       <para>This is an overview of the kinds of patterns you can use
bos@559: 	when you're matching on glob patterns.</para>
bos@559: 
bos@559:       <para>The <quote><literal>*</literal></quote> character matches
bos@567: 	any string, within a single directory.</para>
bos@567: 
bos@567:       &interaction.filenames.glob.star;
bos@559: 
bos@559:       <para>The <quote><literal>**</literal></quote> pattern matches
bos@559: 	any string, and crosses directory boundaries.  It's not a
bos@559: 	standard Unix glob token, but it's accepted by several popular
bos@567: 	Unix shells, and is very useful.</para>
bos@567: 
bos@567:       &interaction.filenames.glob.starstar;
bos@559: 
bos@559:       <para>The <quote><literal>?</literal></quote> pattern matches
bos@567: 	any single character.</para>
bos@567: 
bos@567:       &interaction.filenames.glob.question;
bos@559: 
bos@559:       <para>The <quote><literal>[</literal></quote> character begins a
bos@559: 	<emphasis>character class</emphasis>.  This matches any single
bos@559: 	character within the class.  The class ends with a
bos@559: 	<quote><literal>]</literal></quote> character.  A class may
bos@559: 	contain multiple <emphasis>range</emphasis>s of the form
bos@559: 	<quote><literal>a-f</literal></quote>, which is shorthand for
bos@567: 	<quote><literal>abcdef</literal></quote>.</para>
bos@567: 
bos@567: 	&interaction.filenames.glob.range;
bos@567: 
bos@567:       <para>If the first character after the
bos@567: 	<quote><literal>[</literal></quote> in a character class is a
bos@567: 	<quote><literal>!</literal></quote>, it
bos@559: 	<emphasis>negates</emphasis> the class, making it match any
bos@559: 	single character not in the class.</para>
bos@559: 
bos@559:       <para>A <quote><literal>{</literal></quote> begins a group of
bos@559: 	subpatterns, where the whole group matches if any subpattern
bos@559: 	in the group matches.  The <quote><literal>,</literal></quote>
bos@567: 	character separates subpatterns, and
bos@567: 	<quote><literal>}</literal></quote> ends the group.</para>
bos@567: 
bos@567:       &interaction.filenames.glob.group;
bos@559: 
bos@559:       <sect3>
bos@559: 	<title>Watch out!</title>
bos@559: 
bos@559: 	<para>Don't forget that if you want to match a pattern in any
bos@559: 	  directory, you should not be using the
bos@559: 	  <quote><literal>*</literal></quote> match-any token, as this
bos@559: 	  will only match within one directory.  Instead, use the
bos@559: 	  <quote><literal>**</literal></quote> token.  This small
bos@567: 	  example illustrates the difference between the two.</para>
bos@567: 
bos@567: 	  &interaction.filenames.glob.star-starstar;
bos@559: 
bos@559:       </sect3>
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Regular expression matching with <literal>re</literal>
bos@559: 	patterns</title>
bos@559: 
bos@559:       <para>Mercurial accepts the same regular expression syntax as
bos@559: 	the Python programming language (it uses Python's regexp
bos@559: 	engine internally). This is based on the Perl language's
bos@559: 	regexp syntax, which is the most popular dialect in use (it's
bos@559: 	also used in Java, for example).</para>
bos@559: 
bos@559:       <para>I won't discuss Mercurial's regexp dialect in any detail
bos@559: 	here, as regexps are not often used.  Perl-style regexps are
bos@559: 	in any case already exhaustively documented on a multitude of
bos@559: 	web sites, and in many books.  Instead, I will focus here on a
bos@559: 	few things you should know if you find yourself needing to use
bos@559: 	regexps with Mercurial.</para>
bos@559: 
bos@559:       <para>A regexp is matched against an entire file name, relative
bos@559: 	to the root of the repository.  In other words, even if you're
bos@559: 	already in subbdirectory <filename
bos@559: 	  class="directory">foo</filename>, if you want to match files
bos@559: 	under this directory, your pattern must start with
bos@559: 	<quote><literal>foo/</literal></quote>.</para>
bos@559: 
bos@559:       <para>One thing to note, if you're familiar with Perl-style
bos@559: 	regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
bos@559: 	That is, a regexp starts matching against the beginning of a
bos@559: 	string; it doesn't look for a match anywhere within the
bos@559: 	string.  To match anywhere in a string, start your pattern
bos@559: 	with <quote><literal>.*</literal></quote>.</para>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Filtering files</title>
bos@559: 
bos@559:     <para>Not only does Mercurial give you a variety of ways to
bos@559:       specify files; it lets you further winnow those files using
bos@559:       <emphasis>filters</emphasis>.  Commands that work with file
bos@559:       names accept two filtering options.</para>
bos@559:     <itemizedlist>
bos@559:       <listitem><para><option role="hg-opt-global">-I</option>, or
bos@559: 	  <option role="hg-opt-global">--include</option>, lets you
bos@559: 	  specify a pattern that file names must match in order to be
bos@559: 	  processed.</para>
bos@559:       </listitem>
bos@559:       <listitem><para><option role="hg-opt-global">-X</option>, or
bos@559: 	  <option role="hg-opt-global">--exclude</option>, gives you a
bos@559: 	  way to <emphasis>avoid</emphasis> processing files, if they
bos@559: 	  match this pattern.</para>
bos@559:       </listitem></itemizedlist>
bos@559:     <para>You can provide multiple <option
bos@559: 	role="hg-opt-global">-I</option> and <option
bos@559: 	role="hg-opt-global">-X</option> options on the command line,
bos@559:       and intermix them as you please.  Mercurial interprets the
bos@559:       patterns you provide using glob syntax by default (but you can
bos@559:       use regexps if you need to).</para>
bos@559: 
bos@559:     <para>You can read a <option role="hg-opt-global">-I</option>
bos@559:       filter as <quote>process only the files that match this
bos@567: 	filter</quote>.</para>
bos@567: 
bos@567:     &interaction.filenames.filter.include;
bos@567: 
bos@567:     <para>The <option role="hg-opt-global">-X</option> filter is best
bos@559:       read as <quote>process only the files that don't match this
bos@567: 	pattern</quote>.</para>
bos@567: 
bos@567:     &interaction.filenames.filter.exclude;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Ignoring unwanted files and directories</title>
bos@559: 
bos@559:     <para>XXX.</para>
bos@559: 
bos@559:   </sect1>
dongsheng@625:   <sect1 id="sec.names.case">
bos@559:     <title>Case sensitivity</title>
bos@559: 
bos@559:     <para>If you're working in a mixed development environment that
bos@559:       contains both Linux (or other Unix) systems and Macs or Windows
bos@559:       systems, you should keep in the back of your mind the knowledge
bos@559:       that they treat the case (<quote>N</quote> versus
bos@559:       <quote>n</quote>) of file names in incompatible ways.  This is
bos@559:       not very likely to affect you, and it's easy to deal with if it
bos@559:       does, but it could surprise you if you don't know about
bos@559:       it.</para>
bos@559: 
bos@559:     <para>Operating systems and filesystems differ in the way they
bos@559:       handle the <emphasis>case</emphasis> of characters in file and
bos@559:       directory names.  There are three common ways to handle case in
bos@559:       names.</para>
bos@559:     <itemizedlist>
bos@559:       <listitem><para>Completely case insensitive.  Uppercase and
bos@559: 	  lowercase versions of a letter are treated as identical,
bos@559: 	  both when creating a file and during subsequent accesses.
bos@559: 	  This is common on older DOS-based systems.</para>
bos@559:       </listitem>
bos@559:       <listitem><para>Case preserving, but insensitive.  When a file
bos@559: 	  or directory is created, the case of its name is stored, and
bos@559: 	  can be retrieved and displayed by the operating system.
bos@559: 	  When an existing file is being looked up, its case is
bos@559: 	  ignored.  This is the standard arrangement on Windows and
bos@559: 	  MacOS.  The names <filename>foo</filename> and
bos@559: 	  <filename>FoO</filename> identify the same file.  This
bos@559: 	  treatment of uppercase and lowercase letters as
bos@559: 	  interchangeable is also referred to as <emphasis>case
bos@559: 	    folding</emphasis>.</para>
bos@559:       </listitem>
bos@559:       <listitem><para>Case sensitive.  The case of a name is
bos@559: 	  significant at all times. The names <filename>foo</filename>
bos@559: 	  and {FoO} identify different files.  This is the way Linux
bos@559: 	  and Unix systems normally work.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@559:     <para>On Unix-like systems, it is possible to have any or all of
bos@559:       the above ways of handling case in action at once.  For example,
bos@559:       if you use a USB thumb drive formatted with a FAT32 filesystem
bos@559:       on a Linux system, Linux will handle names on that filesystem in
bos@559:       a case preserving, but insensitive, way.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Safe, portable repository storage</title>
bos@559: 
bos@559:       <para>Mercurial's repository storage mechanism is <emphasis>case
bos@559: 	  safe</emphasis>.  It translates file names so that they can
bos@559: 	be safely stored on both case sensitive and case insensitive
bos@559: 	filesystems.  This means that you can use normal file copying
bos@559: 	tools to transfer a Mercurial repository onto, for example, a
bos@559: 	USB thumb drive, and safely move that drive and repository
bos@559: 	back and forth between a Mac, a PC running Windows, and a
bos@559: 	Linux box.</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Detecting case conflicts</title>
bos@559: 
bos@559:       <para>When operating in the working directory, Mercurial honours
bos@559: 	the naming policy of the filesystem where the working
bos@559: 	directory is located.  If the filesystem is case preserving,
bos@559: 	but insensitive, Mercurial will treat names that differ only
bos@559: 	in case as the same.</para>
bos@559: 
bos@559:       <para>An important aspect of this approach is that it is
bos@559: 	possible to commit a changeset on a case sensitive (typically
bos@559: 	Linux or Unix) filesystem that will cause trouble for users on
bos@559: 	case insensitive (usually Windows and MacOS) users.  If a
bos@559: 	Linux user commits changes to two files, one named
bos@559: 	<filename>myfile.c</filename> and the other named
bos@559: 	<filename>MyFile.C</filename>, they will be stored correctly
bos@559: 	in the repository.  And in the working directories of other
bos@559: 	Linux users, they will be correctly represented as separate
bos@559: 	files.</para>
bos@559: 
bos@559:       <para>If a Windows or Mac user pulls this change, they will not
bos@559: 	initially have a problem, because Mercurial's repository
bos@559: 	storage mechanism is case safe.  However, once they try to
bos@559: 	<command role="hg-cmd">hg update</command> the working
bos@559: 	directory to that changeset, or <command role="hg-cmd">hg
bos@559: 	  merge</command> with that changeset, Mercurial will spot the
bos@559: 	conflict between the two file names that the filesystem would
bos@559: 	treat as the same, and forbid the update or merge from
bos@559: 	occurring.</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Fixing a case conflict</title>
bos@559: 
bos@559:       <para>If you are using Windows or a Mac in a mixed environment
bos@559: 	where some of your collaborators are using Linux or Unix, and
bos@559: 	Mercurial reports a case folding conflict when you try to
bos@559: 	<command role="hg-cmd">hg update</command> or <command
bos@559: 	  role="hg-cmd">hg merge</command>, the procedure to fix the
bos@559: 	problem is simple.</para>
bos@559: 
bos@559:       <para>Just find a nearby Linux or Unix box, clone the problem
bos@559: 	repository onto it, and use Mercurial's <command
bos@559: 	  role="hg-cmd">hg rename</command> command to change the
bos@559: 	names of any offending files or directories so that they will
bos@559: 	no longer cause case folding conflicts.  Commit this change,
bos@559: 	<command role="hg-cmd">hg pull</command> or <command
bos@559: 	  role="hg-cmd">hg push</command> it across to your Windows or
bos@559: 	MacOS system, and <command role="hg-cmd">hg update</command>
bos@559: 	to the revision with the non-conflicting names.</para>
bos@559: 
bos@559:       <para>The changeset with case-conflicting names will remain in
bos@559: 	your project's history, and you still won't be able to
bos@559: 	<command role="hg-cmd">hg update</command> your working
bos@559: 	directory to that changeset on a Windows or MacOS system, but
bos@559: 	you can continue development unimpeded.</para>
bos@559: 
bos@559:       <note>
bos@559: 	<para>  Prior to version 0.9.3, Mercurial did not use a case
bos@559: 	  safe repository storage mechanism, and did not detect case
bos@559: 	  folding conflicts.  If you are using an older version of
bos@559: 	  Mercurial on Windows or MacOS, I strongly recommend that you
bos@559: 	  upgrade.</para>
bos@559:       </note>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559: </chapter>
bos@559: 
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559: end:
bos@559: -->