1.1 --- a/en/00book.tex	Thu Dec 28 16:45:56 2006 -0800
     1.2 +++ b/en/00book.tex	Fri Dec 29 17:54:14 2006 -0800
     1.3 @@ -41,6 +41,7 @@
     1.4  \include{tour-merge}
     1.5  \include{concepts}
     1.6  \include{daily}
     1.7 +\include{filenames}
     1.8  \include{undo}
     1.9  \include{hook}
    1.10  \include{template}

     2.1 --- a/en/99defs.tex	Thu Dec 28 16:45:56 2006 -0800
     2.2 +++ b/en/99defs.tex	Fri Dec 29 17:54:14 2006 -0800
     2.3 @@ -117,10 +117,13 @@
     2.4  \fi
     2.5  
     2.6  % Reference entry for a command.
     2.7 -\newcommand{\cmdref}[1]{\section{#1}\label{cmdref:#1}\index{\texttt{#1} command}``\texttt{hg #1}''}
     2.8 +\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}}
     2.9  
    2.10 -% Reference entry for a command option.
    2.11 -\newcommand{\optref}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    2.12 +% Reference entry for a command option with long and short forms.
    2.13 +\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}}
    2.14 +
    2.15 +% Reference entry for a command option with only long form.
    2.16 +\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}}
    2.17  
    2.18  %%% Local Variables: 
    2.19  %%% mode: latex

     3.1 --- a/en/Makefile	Thu Dec 28 16:45:56 2006 -0800
     3.2 +++ b/en/Makefile	Fri Dec 29 17:54:14 2006 -0800
     3.3 @@ -10,6 +10,7 @@
     3.4  	cmdref.tex \
     3.5  	concepts.tex \
     3.6  	daily.tex \
     3.7 +	filenames.tex \
     3.8  	hook.tex \
     3.9  	intro.tex \
    3.10  	mq.tex \
    3.11 @@ -51,10 +52,12 @@
    3.12  example-sources := \
    3.13  	backout \
    3.14  	bisect \
    3.15 +	cmdref \
    3.16  	daily.copy \
    3.17  	daily.files \
    3.18  	daily.rename \
    3.19  	daily.revert \
    3.20 +	filenames \
    3.21  	hook.msglen \
    3.22  	hook.simple \
    3.23  	hook.ws \

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/cmdref.py	Fri Dec 29 17:54:14 2006 -0800
     4.3 @@ -0,0 +1,156 @@
     4.4 +#!/usr/bin/env python
     4.5 +
     4.6 +import getopt
     4.7 +import itertools
     4.8 +import os
     4.9 +import re
    4.10 +import sys
    4.11 +
    4.12 +def usage(exitcode):
    4.13 +    print >> sys.stderr, ('usage: %s [-H|--hidden] hg_repo' % 
    4.14 +                          os.path.basename(sys.argv[0]))
    4.15 +    sys.exit(exitcode)
    4.16 +
    4.17 +try:
    4.18 +    opts, args = getopt.getopt(sys.argv[1:], 'AHh?', ['all', 'help', 'hidden'])
    4.19 +    opt_all = False
    4.20 +    opt_hidden = False
    4.21 +    for o, a in opts:
    4.22 +        if o in ('-h', '-?', '--help'):
    4.23 +            usage(0)
    4.24 +        if o in ('-A', '--all'):
    4.25 +            opt_all = True
    4.26 +        if o in ('-H', '--hidden'):
    4.27 +            opt_hidden = True
    4.28 +except getopt.GetoptError, err:
    4.29 +    print >> sys.stderr, 'error:', err
    4.30 +    usage(1)
    4.31 +
    4.32 +try:
    4.33 +    hg_repo, ltx_file = args
    4.34 +except ValueError:
    4.35 +    usage(1)
    4.36 +
    4.37 +if not os.path.isfile(os.path.join(hg_repo, 'mercurial', 'commands.py')):
    4.38 +    print >> sys.stderr, ('error: %r does not contain mercurial code' %
    4.39 +                          hg_repo)
    4.40 +    sys.exit(1)
    4.41 +
    4.42 +sys.path.insert(0, hg_repo)
    4.43 +
    4.44 +from mercurial import commands
    4.45 +
    4.46 +def get_commands():
    4.47 +    seen = {}
    4.48 +    for name, info in sorted(commands.table.iteritems()):
    4.49 +        aliases = name.split('|', 1)
    4.50 +        name = aliases.pop(0).lstrip('^')
    4.51 +        function, options, synopsis = info
    4.52 +        seen[name] = {}
    4.53 +        for shortopt, longopt, arg, desc in options:
    4.54 +            seen[name][longopt] = shortopt
    4.55 +    return seen
    4.56 +
    4.57 +def cmd_filter((name, aliases, options)):
    4.58 +    if opt_all:
    4.59 +        return True
    4.60 +    if opt_hidden:
    4.61 +        return name.startswith('debug')
    4.62 +    return not name.startswith('debug')
    4.63 +
    4.64 +def scan(ltx_file):
    4.65 +    cmdref_re = re.compile(r'^\\cmdref{(?P<cmd>\w+)}')
    4.66 +    optref_re = re.compile(r'^\\l?optref{(?P<cmd>\w+)}'
    4.67 +                           r'(?:{(?P<short>[^}])})?'
    4.68 +                           r'{(?P<long>[^}]+)}')
    4.69 +
    4.70 +    seen = {}
    4.71 +    locs = {}
    4.72 +    for lnum, line in enumerate(open(ltx_file)):
    4.73 +        m = cmdref_re.match(line)
    4.74 +        if m:
    4.75 +            d = m.groupdict()
    4.76 +            cmd = d['cmd']
    4.77 +            seen[cmd] = {}
    4.78 +            locs[cmd] = lnum + 1
    4.79 +            continue
    4.80 +        m = optref_re.match(line)
    4.81 +        if m:
    4.82 +            d = m.groupdict()
    4.83 +            seen[d['cmd']][d['long']] = d['short']
    4.84 +            continue
    4.85 +    return seen, locs
    4.86 +    
    4.87 +documented, locs = scan(ltx_file)
    4.88 +known = get_commands()
    4.89 +
    4.90 +doc_set = set(documented)
    4.91 +known_set = set(known)
    4.92 +
    4.93 +errors = 0
    4.94 +
    4.95 +for nonexistent in sorted(doc_set.difference(known_set)):
    4.96 +    print >> sys.stderr, ('%s:%d: %r command does not exist' %
    4.97 +                          (ltx_file, locs[nonexistent], nonexistent))
    4.98 +    errors += 1
    4.99 +
   4.100 +def optcmp(a, b):
   4.101 +    la, sa = a
   4.102 +    lb, sb = b
   4.103 +    sc = cmp(sa, sb)
   4.104 +    if sc:
   4.105 +        return sc
   4.106 +    return cmp(la, lb)
   4.107 +
   4.108 +for cmd in doc_set.intersection(known_set):
   4.109 +    doc_opts = documented[cmd]
   4.110 +    known_opts = known[cmd]
   4.111 +    
   4.112 +    do_set = set(doc_opts)
   4.113 +    ko_set = set(known_opts)
   4.114 +
   4.115 +    for nonexistent in sorted(do_set.difference(ko_set)):
   4.116 +        print >> sys.stderr, ('%s:%d: %r option to %r command does not exist' %
   4.117 +                              (ltx_file, locs[cmd], nonexistent, cmd))
   4.118 +        errors += 1
   4.119 +
   4.120 +    def mycmp(la, lb):
   4.121 +        sa = known_opts[la]
   4.122 +        sb = known_opts[lb]
   4.123 +        return optcmp((la, sa), (lb, sb))
   4.124 +
   4.125 +    for undocumented in sorted(ko_set.difference(do_set), cmp=mycmp):
   4.126 +        print >> sys.stderr, ('%s:%d: %r option to %r command not documented' %
   4.127 +                              (ltx_file, locs[cmd], undocumented, cmd))
   4.128 +        shortopt = known_opts[undocumented]
   4.129 +        if shortopt:
   4.130 +            print '\optref{%s}{%s}{%s}' % (cmd, shortopt, undocumented)
   4.131 +        else:
   4.132 +            print '\loptref{%s}{%s}' % (cmd, undocumented)
   4.133 +        errors += 1
   4.134 +    sys.stdout.flush()
   4.135 +
   4.136 +if errors:
   4.137 +    sys.exit(1)
   4.138 +
   4.139 +sorted_locs = sorted(locs.iteritems(), key=lambda x:x[1])
   4.140 +
   4.141 +def next_loc(cmd):
   4.142 +    for i, (name, loc) in enumerate(sorted_locs):
   4.143 +        if name >= cmd:
   4.144 +            return sorted_locs[i-1][1] + 1
   4.145 +    return loc
   4.146 +
   4.147 +for undocumented in sorted(known_set.difference(doc_set)):
   4.148 +    print >> sys.stderr, ('%s:%d: %r command not documented' %
   4.149 +                          (ltx_file, next_loc(undocumented), undocumented))
   4.150 +    print '\cmdref{%s}' % undocumented
   4.151 +    for longopt, shortopt in sorted(known[undocumented].items(), cmp=optcmp):
   4.152 +        if shortopt:
   4.153 +            print '\optref{%s}{%s}{%s}' % (undocumented, shortopt, longopt)
   4.154 +        else:
   4.155 +            print '\loptref{%s}{%s}' % (undocumented, longopt)
   4.156 +    sys.stdout.flush()
   4.157 +    errors += 1
   4.158 +
   4.159 +sys.exit(errors and 1 or 0)

     5.1 --- a/en/cmdref.tex	Thu Dec 28 16:45:56 2006 -0800
     5.2 +++ b/en/cmdref.tex	Fri Dec 29 17:54:14 2006 -0800
     5.3 @@ -1,17 +1,41 @@
     5.4  \chapter{Command reference}
     5.5  \label{cmdref}
     5.6  
     5.7 -\cmdref{diff}
     5.8 +\cmdref{add}{add files at the next commit}
     5.9 +\optref{add}{I}{include}
    5.10 +\optref{add}{X}{exclude}
    5.11 +\optref{add}{n}{dry-run}
    5.12 +
    5.13 +\cmdref{diff}{print changes in history or working directory}
    5.14  
    5.15  Show differences between revisions for the specified files or
    5.16  directories, using the unified diff format.  For a description of the
    5.17  unified diff format, see section~\ref{sec:mq:patch}.
    5.18  
    5.19 -\optref{diff}{-r}{--rev}
    5.20 +By default, this command does not print diffs for files that Mercurial
    5.21 +considers to contain binary data.  To control this behaviour, see the
    5.22 +\hgopt{diff}{-a} and \hgopt{diff}{--git} options.
    5.23  
    5.24 -Specify a revision to compare.
    5.25 +\subsection{Options}
    5.26  
    5.27 -\optref{diff}{-a}{--text}
    5.28 +\loptref{diff}{nodates}
    5.29 +
    5.30 +Omit date and time information when printing diff headers.
    5.31 +
    5.32 +\optref{diff}{B}{ignore-blank-lines}
    5.33 +
    5.34 +Do not print changes that only insert or delete blank lines.  A line
    5.35 +that contains only whitespace is not considered blank.
    5.36 +
    5.37 +\optref{diff}{I}{include}
    5.38 +
    5.39 +Exclude files and directories whose names match the given patterns.
    5.40 +
    5.41 +\optref{diff}{X}{exclude}
    5.42 +
    5.43 +Include files and directories whose names match the given patterns.
    5.44 +
    5.45 +\optref{diff}{a}{text}
    5.46  
    5.47  If this option is not specified, \hgcmd{diff} will refuse to print
    5.48  diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    5.49 @@ -19,18 +43,37 @@
    5.50  all of them.
    5.51  
    5.52  This option is useful for files that are ``mostly text'' but have a
    5.53 -few embedded NUL characters.  If you use it on files that are really
    5.54 -binary, its output will be incomprehensible.
    5.55 +few embedded NUL characters.  If you use it on files that contain a
    5.56 +lot of binary data, its output will be incomprehensible.
    5.57  
    5.58 -\subsection{Specifying revisions}
    5.59 +\optref{diff}{b}{ignore-space-change}
    5.60  
    5.61 -The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
    5.62 -specify the revisions to compare.
    5.63 +Do not print a line if the only change to that line is in the amount
    5.64 +of white space it contains.
    5.65 +
    5.66 +\optref{diff}{g}{git}
    5.67 +
    5.68 +Print \command{git}-compatible diffs.  XXX reference a format
    5.69 +description.
    5.70 +
    5.71 +\optref{diff}{p}{show-function}
    5.72 +
    5.73 +Display the name of the enclosing function in a hunk header, using a
    5.74 +simple heuristic.  This functionality is enabled by default, so the
    5.75 +\hgopt{diff}{-p} option has no effect unless you change the value of
    5.76 +the \rcitem{diff}{showfunc} config item, as in the following example.
    5.77 +\interaction{cmdref.diff-p}
    5.78 +
    5.79 +\optref{diff}{r}{rev}
    5.80 +
    5.81 +Specify one or more revisions to compare.  The \hgcmd{diff} command
    5.82 +accepts up to two \hgopt{diff}{-r} options to specify the revisions to
    5.83 +compare.
    5.84  
    5.85  \begin{enumerate}
    5.86  \setcounter{enumi}{0}
    5.87 -\item Display the differences between the parent of the working
    5.88 -  directory and the working directory.
    5.89 +\item Display the differences between the parent revision of the
    5.90 +  working directory and the working directory.
    5.91  \item Display the differences between the specified changeset and the
    5.92    working directory.
    5.93  \item Display the differences between the two specified changesets.
    5.94 @@ -53,7 +96,34 @@
    5.95  contents.  You cannot reverse the ordering in this way if you are
    5.96  diffing against the working directory.
    5.97  
    5.98 -\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
    5.99 +\optref{diff}{w}{ignore-all-space}
   5.100 +
   5.101 +\cmdref{version}{print version and copyright information}
   5.102 +
   5.103 +This command displays the version of Mercurial you are running, and
   5.104 +its copyright license.  There are four kinds of version string that
   5.105 +you may see.
   5.106 +\begin{itemize}
   5.107 +\item The string ``\texttt{unknown}''. This version of Mercurial was
   5.108 +  not built in a Mercurial repository, and cannot determine its own
   5.109 +  version.
   5.110 +\item A short numeric string, such as ``\texttt{1.1}''. This is a
   5.111 +  build of a revision of Mercurial that was identified by a specific
   5.112 +  tag in the repository where it was built.  (This doesn't necessarily
   5.113 +  mean that you're running an official release; someone else could
   5.114 +  have added that tag to any revision in the repository where they
   5.115 +  built Mercurial.)
   5.116 +\item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
   5.117 +  is a build of the given revision of Mercurial.
   5.118 +\item A hexadecimal string followed by a date, such as
   5.119 +  ``\texttt{875489e31abe+20070205}''.  This is a build of the given
   5.120 +  revision of Mercurial, where the build repository contained some
   5.121 +  local changes that had not been committed.
   5.122 +\end{itemize}
   5.123 +
   5.124 +\subsection{Tips and tricks}
   5.125 +
   5.126 +\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
   5.127    differ?}
   5.128  \label{cmdref:diff-vs-status}
   5.129  
   5.130 @@ -87,7 +157,7 @@
   5.131  \hgopt{diff}{-r} option.  There is no way to print diffs relative to
   5.132  both parents.
   5.133  
   5.134 -\subsection{Generating safe binary diffs}
   5.135 +\subsubsection{Generating safe binary diffs}
   5.136  
   5.137  If you use the \hgopt{diff}{-a} option to force Mercurial to print
   5.138  diffs of files that are either ``mostly text'' or contain lots of

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/cmdref	Fri Dec 29 17:54:14 2006 -0800
     6.3 @@ -0,0 +1,22 @@
     6.4 +#!/bin/bash
     6.5 +
     6.6 +hg init diff
     6.7 +cd diff
     6.8 +cat > myfile.c <<EOF
     6.9 +int myfunc()
    6.10 +{
    6.11 +    return 1;
    6.12 +}
    6.13 +EOF
    6.14 +hg ci -Ama
    6.15 +
    6.16 +sed -ie 's/return 1/return 10/' myfile.c
    6.17 +
    6.18 +#$ name: diff-p
    6.19 +
    6.20 +echo '[diff]' >> $HGRC
    6.21 +echo 'showfunc = False' >> $HGRC
    6.22 +
    6.23 +hg diff
    6.24 +
    6.25 +hg diff -p

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/examples/filenames	Fri Dec 29 17:54:14 2006 -0800
     7.3 @@ -0,0 +1,61 @@
     7.4 +#!/bin/bash
     7.5 +
     7.6 +hg init a
     7.7 +cd a
     7.8 +mkdir -p examples src/watcher
     7.9 +touch COPYING MANIFEST.in README setup.py
    7.10 +touch examples/performant.py examples/simple.py
    7.11 +touch src/main.py src/watcher/_watcher.c src/watcher/watcher.py src/xyzzy.txt
    7.12 +
    7.13 +#$ name: files
    7.14 +
    7.15 +hg add COPYING README examples/simple.py
    7.16 +
    7.17 +#$ name: dirs
    7.18 +
    7.19 +hg status src
    7.20 +
    7.21 +#$ name: wdir-subdir
    7.22 +
    7.23 +cd src
    7.24 +hg add -n
    7.25 +hg add -n .
    7.26 +
    7.27 +#$ name: wdir-relname
    7.28 +
    7.29 +hg status
    7.30 +hg status `hg root`
    7.31 +
    7.32 +#$ name: glob.star
    7.33 +
    7.34 +hg add 'glob:*.py'
    7.35 +
    7.36 +#$ name: glob.starstar
    7.37 +
    7.38 +cd ..
    7.39 +hg status 'glob:**.py'
    7.40 +
    7.41 +#$ name: glob.star-starstar
    7.42 +
    7.43 +hg status 'glob:*.py'
    7.44 +hg status 'glob:**.py'
    7.45 +
    7.46 +#$ name: glob.question
    7.47 +
    7.48 +hg status 'glob:**.?'
    7.49 +
    7.50 +#$ name: glob.range
    7.51 +
    7.52 +hg status 'glob:**[nr-t]'
    7.53 +
    7.54 +#$ name: glob.group
    7.55 +
    7.56 +hg status 'glob:*.{in,py}'
    7.57 +
    7.58 +#$ name: filter.include
    7.59 +
    7.60 +hg status -I '*.in'
    7.61 +
    7.62 +#$ name: filter.exclude
    7.63 +
    7.64 +hg status -X '**.py' src

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/filenames.tex	Fri Dec 29 17:54:14 2006 -0800
     8.3 @@ -0,0 +1,306 @@
     8.4 +\chapter{File names and pattern matching}
     8.5 +\label{chap:names}
     8.6 +
     8.7 +Mercurial provides mechanisms that let you work with file names in a
     8.8 +consistent and expressive way.
     8.9 +
    8.10 +\section{Simple file naming}
    8.11 +
    8.12 +Mercurial uses a unified piece of machinery ``under the hood'' to
    8.13 +handle file names.  Every command behaves uniformly with respect to
    8.14 +file names.  The way in which commands work with file names is as
    8.15 +follows.
    8.16 +
    8.17 +If you explicitly name real files on the command line, Mercurial works
    8.18 +with exactly those files, as you would expect.
    8.19 +\interaction{filenames.files}
    8.20 +
    8.21 +When you provide a directory name, Mercurial will interpret this as
    8.22 +``operate on every file in this directory and its subdirectories''.
    8.23 +Mercurial traverses the files and subdirectories in a directory in
    8.24 +alphabetical order.  When it encounters a subdirectory, it will
    8.25 +traverse that subdirectory before continuing with the current
    8.26 +directory.
    8.27 +\interaction{filenames.dirs}
    8.28 +
    8.29 +\section{Running commands without any file names}
    8.30 +
    8.31 +Mercurial's commands that work with file names have useful default
    8.32 +behaviours when you invoke them without providing any file names or
    8.33 +patterns.  What kind of behaviour you should expect depends on what
    8.34 +the command does.  Here are a few rules of thumb you can use to
    8.35 +predict what a command is likely to do if you don't give it any names
    8.36 +to work with.
    8.37 +\begin{itemize}
    8.38 +\item Most commands will operate on the entire working directory.
    8.39 +  This is what the \hgcmd{add} command does, for example.
    8.40 +\item If the command has effects that are difficult or impossible to
    8.41 +  reverse, it will force you to explicitly provide at least one name
    8.42 +  or pattern (see below).  This protects you from accidentally
    8.43 +  deleting files by running \hgcmd{remove} with no arguments, for
    8.44 +  example.
    8.45 +\end{itemize}
    8.46 +
    8.47 +It's easy to work around these default behaviours if they don't suit
    8.48 +you.  If a command normally operates on the whole working directory,
    8.49 +you can invoke it on just the current directory and its subdirectories
    8.50 +by giving it the name ``\dirname{.}''.
    8.51 +\interaction{filenames.wdir-subdir}
    8.52 +
    8.53 +Along the same lines, some commands normally print file names relative
    8.54 +to the root of the repository, even if you're invoking them from a
    8.55 +subdirectory.  Such a command will print file names relative to your
    8.56 +subdirectory if you give it explicit names.  Here, we're going to run
    8.57 +\hgcmd{status} from a subdirectory, and get it to operate on the
    8.58 +entire working directory while printing file names relative to our
    8.59 +subdirectory, by passing it the output of the \hgcmd{root} command.
    8.60 +\interaction{filenames.wdir-relname}
    8.61 +
    8.62 +\section{Telling you what's going on}
    8.63 +
    8.64 +The \hgcmd{add} example in the preceding section illustrates something
    8.65 +else that's helpful about Mercurial commands.  If a command operates
    8.66 +on a file that you didn't name explicitly on the command line, it will
    8.67 +usually print the name of the file, so that you will not be surprised
    8.68 +what's going on.
    8.69 +
    8.70 +The principle here is of \emph{least surprise}.  If you've exactly
    8.71 +named a file on the command line, there's no point in repeating it
    8.72 +back at you.  If Mercurial is acting on a file \emph{implicitly},
    8.73 +because you provided no names, or a directory, or a pattern (see
    8.74 +below), it's safest to tell you what it's doing.
    8.75 +
    8.76 +For commands that behave this way, you can silence them using the
    8.77 +\hggopt{-q} option.  You can also get them to print the name of every
    8.78 +file, even those you've named explicitly, using the \hggopt{-v}
    8.79 +option.
    8.80 +
    8.81 +\section{Using patterns to identify files}
    8.82 +
    8.83 +In addition to working with file and directory names, Mercurial lets
    8.84 +you use \emph{patterns} to identify files.  Mercurial's pattern
    8.85 +handling is expressive.
    8.86 +
    8.87 +On Unix-like systems (Linux, MacOS, etc.), the job of matching file
    8.88 +names to patterns normally falls to the shell.  On these systems, you
    8.89 +must explicitly tell Mercurial that a name is a pattern.  On Windows,
    8.90 +the shell does not expand patterns, so Mercurial will automatically
    8.91 +identify names that are patterns, and expand them for you.
    8.92 +
    8.93 +To provide a pattern in place of a regular name on the command line,
    8.94 +the mechanism is simple:
    8.95 +\begin{codesample2}
    8.96 +  syntax:patternbody
    8.97 +\end{codesample2}
    8.98 +That is, a pattern is identified by a short text string that says what
    8.99 +kind of pattern this is, followed by a colon, followed by the actual
   8.100 +pattern.
   8.101 +
   8.102 +Mercurial supports two kinds of pattern syntax.  The most frequently
   8.103 +used is called \texttt{glob}; this is the same kind of pattern
   8.104 +matching used by the Unix shell, and should be familiar to Windows
   8.105 +command prompt users, too.  
   8.106 +
   8.107 +When Mercurial does automatic pattern matching on Windows, it uses
   8.108 +\texttt{glob} syntax.  You can thus omit the ``\texttt{glob:}'' prefix
   8.109 +on Windows, but it's safe to use it, too.
   8.110 +
   8.111 +The \texttt{re} syntax is more powerful; it lets you specify patterns
   8.112 +using regular expressions, also known as regexps.
   8.113 +
   8.114 +By the way, in the examples that follow, notice that I'm careful to
   8.115 +wrap all of my patterns in quote characters, so that they won't get
   8.116 +expanded by the shell before Mercurial sees them.
   8.117 +
   8.118 +\subsection{Shell-style \texttt{glob} patterns}
   8.119 +
   8.120 +This is an overview of the kinds of patterns you can use when you're
   8.121 +matching on glob patterns.
   8.122 +
   8.123 +The ``\texttt{*}'' character matches any string, within a single
   8.124 +directory.
   8.125 +\interaction{filenames.glob.star}
   8.126 +
   8.127 +The ``\texttt{**}'' pattern matches any string, and crosses directory
   8.128 +boundaries.  It's not a standard Unix glob token, but it's accepted by
   8.129 +several popular Unix shells, and is very useful.
   8.130 +\interaction{filenames.glob.starstar}
   8.131 +
   8.132 +The ``\texttt{?}'' pattern matches any single character.
   8.133 +\interaction{filenames.glob.question}
   8.134 +
   8.135 +The ``\texttt{[}'' character begins a \emph{character class}.  This
   8.136 +matches any single character within the class.  The class ends with a
   8.137 +``\texttt{]}'' character.  A class may contain multiple \emph{range}s
   8.138 +of the form ``\texttt{a-f}'', which is shorthand for
   8.139 +``\texttt{abcdef}''.
   8.140 +\interaction{filenames.glob.range}
   8.141 +If the first character after the ``\texttt{[}'' in a character class
   8.142 +is a ``\texttt{!}'', it \emph{negates} the class, making it match any
   8.143 +single character not in the class.
   8.144 +
   8.145 +A ``\texttt{\{}'' begins a group of subpatterns, where the whole group
   8.146 +matches if any subpattern in the group matches.  The ``\texttt{,}''
   8.147 +character separates subpatterns, and ``\texttt{\}}'' ends the group.
   8.148 +\interaction{filenames.glob.group}
   8.149 +
   8.150 +\subsubsection{Watch out!}
   8.151 +
   8.152 +Don't forget that if you want to match a pattern in any directory, you
   8.153 +should not be using the ``\texttt{*}'' match-any token, as this will
   8.154 +only match within one directory.  Instead, use the ``\texttt{**}''
   8.155 +token.  This small example illustrates the difference between the two.
   8.156 +\interaction{filenames.glob.star-starstar}
   8.157 +
   8.158 +\subsection{Regular expression matching with \texttt{re} patterns}
   8.159 +
   8.160 +Mercurial accepts the same regular expression syntax as the Python
   8.161 +programming language (it uses Python's regexp engine internally).
   8.162 +This is based on the Perl language's regexp syntax, which is the most
   8.163 +popular dialect in use (it's also used in Java, for example).
   8.164 +
   8.165 +I won't discuss Mercurial's regexp dialect in any detail here, as
   8.166 +regexps are not often used.  Perl-style regexps are in any case
   8.167 +already exhaustively documented on a multitude of web sites, and in
   8.168 +many books.  Instead, I will focus here on a few things you should
   8.169 +know if you find yourself needing to use regexps with Mercurial.
   8.170 +
   8.171 +A regexp is matched against an entire file name, relative to the root
   8.172 +of the repository.  In other words, even if you're already in
   8.173 +subbdirectory \dirname{foo}, if you want to match files under this
   8.174 +directory, your pattern must start with ``\texttt{foo/}''.
   8.175 +
   8.176 +One thing to note, if you're familiar with Perl-style regexps, is that
   8.177 +Mercurial's are \emph{rooted}.  That is, a regexp starts matching
   8.178 +against the beginning of a string; it doesn't look for a match
   8.179 +anywhere within the string it.  To match anywhere in a string, start
   8.180 +your pattern with ``\texttt{.*}''.
   8.181 +
   8.182 +\section{Filtering files}
   8.183 +
   8.184 +Not only does Mercurial give you a variety of ways to specify files;
   8.185 +it lets you further winnow those files using \emph{filters}.  Commands
   8.186 +that work with file names accept two filtering options.
   8.187 +\begin{itemize}
   8.188 +\item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
   8.189 +  that file names must match in order to be processed.
   8.190 +\item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
   8.191 +  \emph{avoid} processing files, if they match this pattern.
   8.192 +\end{itemize}
   8.193 +You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
   8.194 +command line, and intermix them as you please.  Mercurial interprets
   8.195 +the patterns you provide using glob syntax by default (but you can use
   8.196 +regexps if you need to).
   8.197 +
   8.198 +You can read a \hggopt{-I} filter as ``process only the files that
   8.199 +match this filter''.
   8.200 +\interaction{filenames.filter.include}
   8.201 +The \hggopt{-X} filter is best read as ``process only the files that
   8.202 +don't match this pattern''.
   8.203 +\interaction{filenames.filter.exclude}
   8.204 +
   8.205 +\section{Ignoring unwanted files and directories}
   8.206 +
   8.207 +XXX.
   8.208 +
   8.209 +\section{Case sensitivity}
   8.210 +\label{sec:names:case}
   8.211 +
   8.212 +If you're working in a mixed development environment that contains
   8.213 +both Linux (or other Unix) systems and Macs or Windows systems, you
   8.214 +should keep in the back of your mind the knowledge that they treat the
   8.215 +case (``N'' versus ``n'') of file names in incompatible ways.  This is
   8.216 +not very likely to affect you, and it's easy to deal with if it does,
   8.217 +but it could surprise you if you don't know about it.
   8.218 +
   8.219 +Operating systems and filesystems differ in the way they handle the
   8.220 +\emph{case} of characters in file and directory names.  There are
   8.221 +three common ways to handle case in names.
   8.222 +\begin{itemize}
   8.223 +\item Completely case insensitive.  Uppercase and lowercase versions
   8.224 +  of a letter are treated as identical, both when creating a file and
   8.225 +  during subsequent accesses.  This is common on older DOS-based
   8.226 +  systems.
   8.227 +\item Case preserving, but insensitive.  When a file or directory is
   8.228 +  created, the case of its name is stored, and can be retrieved and
   8.229 +  displayed by the operating system.  When an existing file is being
   8.230 +  looked up, its case is ignored.  This is the standard arrangement on
   8.231 +  Windows and MacOS.  The names \filename{foo} and \filename{FoO}
   8.232 +  identify the same file.  This treatment of uppercase and lowercase
   8.233 +  letters as interchangeable is also referred to as \emph{case
   8.234 +    folding}.
   8.235 +\item Case sensitive.  The case of a name is significant at all times.
   8.236 +  The names \filename{foo} and {FoO} identify different files.  This
   8.237 +  is the way Linux and Unix systems normally work.
   8.238 +\end{itemize}
   8.239 +
   8.240 +On Unix-like systems, it is possible to have any or all of the above
   8.241 +ways of handling case in action at once.  For example, if you use a
   8.242 +USB thumb drive formatted with a FAT32 filesystem on a Linux system,
   8.243 +Linux will handle names on that filesystem in a case preserving, but
   8.244 +insensitive, way.
   8.245 +
   8.246 +\subsection{Safe, portable repository storage}
   8.247 +
   8.248 +Mercurial's repository storage mechanism is \emph{case safe}.  It
   8.249 +translates file names so that they can be safely stored on both case
   8.250 +sensitive and case insensitive filesystems.  This means that you can
   8.251 +use normal file copying tools to transfer a Mercurial repository onto,
   8.252 +for example, a USB thumb drive, and safely move that drive and
   8.253 +repository back and forth between a Mac, a PC running Windows, and a
   8.254 +Linux box.
   8.255 +
   8.256 +\subsection{Detecting case conflicts}
   8.257 +
   8.258 +When operating in the working directory, Mercurial honours the naming
   8.259 +policy of the filesystem where the working directory is located.  If
   8.260 +the filesystem is case preserving, but insensitive, Mercurial will
   8.261 +treat names that differ only in case as the same.
   8.262 +
   8.263 +An important aspect of this approach is that it is possible to commit
   8.264 +a changeset on a case sensitive (typically Linux or Unix) filesystem
   8.265 +that will cause trouble for users on case insensitive (usually Windows
   8.266 +and MacOS) users.  If a Linux user commits changes to two files, one
   8.267 +named \filename{myfile.c} and the other named \filename{MyFile.C},
   8.268 +they will be stored correctly in the repository.  And in the working
   8.269 +directories of other Linux users, they will be correctly represented
   8.270 +as separate files.
   8.271 +
   8.272 +If a Windows or Mac user pulls this change, they will not initially
   8.273 +have a problem, because Mercurial's repository storage mechanism is
   8.274 +case safe.  However, once they try to \hgcmd{update} the working
   8.275 +directory to that changeset, or \hgcmd{merge} with that changeset,
   8.276 +Mercurial will spot the conflict between the two file names that the
   8.277 +filesystem would treat as the same, and forbid the update or merge
   8.278 +from occurring.
   8.279 +
   8.280 +\subsection{Fixing a case conflict}
   8.281 +
   8.282 +If you are using Windows or a Mac in a mixed environment where some of
   8.283 +your collaborators are using Linux or Unix, and Mercurial reports a
   8.284 +case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
   8.285 +the procedure to fix the problem is simple.
   8.286 +
   8.287 +Just find a nearby Linux or Unix box, clone the problem repository
   8.288 +onto it, and use Mercurial's \hgcmd{rename} command to change the
   8.289 +names of any offending files or directories so that they will no
   8.290 +longer cause case folding conflicts.  Commit this change, \hgcmd{pull}
   8.291 +or \hgcmd{push} it across to your Windows or MacOS system, and
   8.292 +\hgcmd{update} to the revision with the non-conflicting names.
   8.293 +
   8.294 +The changeset with case-conflicting names will remain in your
   8.295 +project's history, and you still won't be able to \hgcmd{update} your
   8.296 +working directory to that changeset on a Windows or MacOS system, but
   8.297 +you can continue development unimpeded.
   8.298 +
   8.299 +\begin{note}
   8.300 +  Prior to version~0.9.3, Mercurial did not use a case safe repository
   8.301 +  storage mechanism, and did not detect case folding conflicts.  If
   8.302 +  you are using an older version of Mercurial on Windows or MacOS, I
   8.303 +  strongly recommend that you upgrade.
   8.304 +\end{note}
   8.305 +
   8.306 +%%% Local Variables: 
   8.307 +%%% mode: latex
   8.308 +%%% TeX-master: "00book"
   8.309 +%%% End: