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