hgbook
view es/filenames.tex @ 430:3afc654d70e5
translated some paragraphs. yawn sleepy
| author | jerojasro@localhost |
|---|---|
| date | Sat Nov 29 23:48:11 2008 -0500 (2008-11-29) |
| parents | b05e35d641e4 |
| children | f809de31887a |
line source
1 \chapter{File names and pattern matching}
2 \label{chap:names}
4 Mercurial provee mecanismos que le permiten trabajar con nombres de
5 ficheros en una manera consistente y expresiva.
7 \section{Nombrado de ficheros simple}
9 % TODO traducción literal de "under the hood". revisar
10 Mercurial usa un mecanismo unificado ``bajo el capó'' para manejar
11 nombres de ficheros. Cada comando se comporta de manera uniforme con
12 respecto a los nombres de fichero. La manera en que los comandos
13 operan con nombres de fichero es la siguiente.
15 Si usted especifica explícitamente nombres reales de ficheros en la
16 línea de comandos, Mercurial opera únicamente sobre dichos ficheros,
17 como usted esperaría.
18 \interaction{filenames.files}
20 Cuando usted provee el nombre de un directorio, Mercurial interpreta
21 eso como ``opere en cada fichero en este directorio y sus
22 subdirectorios''. Mercurial va por todos los ficheros y subdirectorios
23 de un directorio en orden alfabético. Cuando encuentra un
24 subdirectorio, lo recorrerá antes de continuar con el directorio
25 actual.
26 \interaction{filenames.dirs}
28 \section{Ejecución de comandos sin ningún nombre de fichero}
30 Los comandos de Mercurial que trabajan con nombres de fichero tienen
31 comportamientos por defecto adecuados cuando son utilizados sin pasar
32 ningún patrón o nombre de fichero. El tipo de comportamiento depende
33 de lo que haga el comando. Aquí presento unas cuantas
34 patterns. What kind of behaviour you should expect depends on what
35 the command does. Here are a few rules of thumb you can use to
36 predict what a command is likely to do if you don't give it any names
37 to work with.
38 \begin{itemize}
39 \item Most commands will operate on the entire working directory.
40 This is what the \hgcmd{add} command does, for example.
41 \item If the command has effects that are difficult or impossible to
42 reverse, it will force you to explicitly provide at least one name
43 or pattern (see below). This protects you from accidentally
44 deleting files by running \hgcmd{remove} with no arguments, for
45 example.
46 \end{itemize}
48 It's easy to work around these default behaviours if they don't suit
49 you. If a command normally operates on the whole working directory,
50 you can invoke it on just the current directory and its subdirectories
51 by giving it the name ``\dirname{.}''.
52 \interaction{filenames.wdir-subdir}
54 Along the same lines, some commands normally print file names relative
55 to the root of the repository, even if you're invoking them from a
56 subdirectory. Such a command will print file names relative to your
57 subdirectory if you give it explicit names. Here, we're going to run
58 \hgcmd{status} from a subdirectory, and get it to operate on the
59 entire working directory while printing file names relative to our
60 subdirectory, by passing it the output of the \hgcmd{root} command.
61 \interaction{filenames.wdir-relname}
63 \section{Telling you what's going on}
65 The \hgcmd{add} example in the preceding section illustrates something
66 else that's helpful about Mercurial commands. If a command operates
67 on a file that you didn't name explicitly on the command line, it will
68 usually print the name of the file, so that you will not be surprised
69 what's going on.
71 The principle here is of \emph{least surprise}. If you've exactly
72 named a file on the command line, there's no point in repeating it
73 back at you. If Mercurial is acting on a file \emph{implicitly},
74 because you provided no names, or a directory, or a pattern (see
75 below), it's safest to tell you what it's doing.
77 For commands that behave this way, you can silence them using the
78 \hggopt{-q} option. You can also get them to print the name of every
79 file, even those you've named explicitly, using the \hggopt{-v}
80 option.
82 \section{Using patterns to identify files}
84 In addition to working with file and directory names, Mercurial lets
85 you use \emph{patterns} to identify files. Mercurial's pattern
86 handling is expressive.
88 On Unix-like systems (Linux, MacOS, etc.), the job of matching file
89 names to patterns normally falls to the shell. On these systems, you
90 must explicitly tell Mercurial that a name is a pattern. On Windows,
91 the shell does not expand patterns, so Mercurial will automatically
92 identify names that are patterns, and expand them for you.
94 To provide a pattern in place of a regular name on the command line,
95 the mechanism is simple:
96 \begin{codesample2}
97 syntax:patternbody
98 \end{codesample2}
99 That is, a pattern is identified by a short text string that says what
100 kind of pattern this is, followed by a colon, followed by the actual
101 pattern.
103 Mercurial supports two kinds of pattern syntax. The most frequently
104 used is called \texttt{glob}; this is the same kind of pattern
105 matching used by the Unix shell, and should be familiar to Windows
106 command prompt users, too.
108 When Mercurial does automatic pattern matching on Windows, it uses
109 \texttt{glob} syntax. You can thus omit the ``\texttt{glob:}'' prefix
110 on Windows, but it's safe to use it, too.
112 The \texttt{re} syntax is more powerful; it lets you specify patterns
113 using regular expressions, also known as regexps.
115 By the way, in the examples that follow, notice that I'm careful to
116 wrap all of my patterns in quote characters, so that they won't get
117 expanded by the shell before Mercurial sees them.
119 \subsection{Shell-style \texttt{glob} patterns}
121 This is an overview of the kinds of patterns you can use when you're
122 matching on glob patterns.
124 The ``\texttt{*}'' character matches any string, within a single
125 directory.
126 \interaction{filenames.glob.star}
128 The ``\texttt{**}'' pattern matches any string, and crosses directory
129 boundaries. It's not a standard Unix glob token, but it's accepted by
130 several popular Unix shells, and is very useful.
131 \interaction{filenames.glob.starstar}
133 The ``\texttt{?}'' pattern matches any single character.
134 \interaction{filenames.glob.question}
136 The ``\texttt{[}'' character begins a \emph{character class}. This
137 matches any single character within the class. The class ends with a
138 ``\texttt{]}'' character. A class may contain multiple \emph{range}s
139 of the form ``\texttt{a-f}'', which is shorthand for
140 ``\texttt{abcdef}''.
141 \interaction{filenames.glob.range}
142 If the first character after the ``\texttt{[}'' in a character class
143 is a ``\texttt{!}'', it \emph{negates} the class, making it match any
144 single character not in the class.
146 A ``\texttt{\{}'' begins a group of subpatterns, where the whole group
147 matches if any subpattern in the group matches. The ``\texttt{,}''
148 character separates subpatterns, and ``\texttt{\}}'' ends the group.
149 \interaction{filenames.glob.group}
151 \subsubsection{Watch out!}
153 Don't forget that if you want to match a pattern in any directory, you
154 should not be using the ``\texttt{*}'' match-any token, as this will
155 only match within one directory. Instead, use the ``\texttt{**}''
156 token. This small example illustrates the difference between the two.
157 \interaction{filenames.glob.star-starstar}
159 \subsection{Regular expression matching with \texttt{re} patterns}
161 Mercurial accepts the same regular expression syntax as the Python
162 programming language (it uses Python's regexp engine internally).
163 This is based on the Perl language's regexp syntax, which is the most
164 popular dialect in use (it's also used in Java, for example).
166 I won't discuss Mercurial's regexp dialect in any detail here, as
167 regexps are not often used. Perl-style regexps are in any case
168 already exhaustively documented on a multitude of web sites, and in
169 many books. Instead, I will focus here on a few things you should
170 know if you find yourself needing to use regexps with Mercurial.
172 A regexp is matched against an entire file name, relative to the root
173 of the repository. In other words, even if you're already in
174 subbdirectory \dirname{foo}, if you want to match files under this
175 directory, your pattern must start with ``\texttt{foo/}''.
177 One thing to note, if you're familiar with Perl-style regexps, is that
178 Mercurial's are \emph{rooted}. That is, a regexp starts matching
179 against the beginning of a string; it doesn't look for a match
180 anywhere within the string. To match anywhere in a string, start
181 your pattern with ``\texttt{.*}''.
183 \section{Filtering files}
185 Not only does Mercurial give you a variety of ways to specify files;
186 it lets you further winnow those files using \emph{filters}. Commands
187 that work with file names accept two filtering options.
188 \begin{itemize}
189 \item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
190 that file names must match in order to be processed.
191 \item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
192 \emph{avoid} processing files, if they match this pattern.
193 \end{itemize}
194 You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
195 command line, and intermix them as you please. Mercurial interprets
196 the patterns you provide using glob syntax by default (but you can use
197 regexps if you need to).
199 You can read a \hggopt{-I} filter as ``process only the files that
200 match this filter''.
201 \interaction{filenames.filter.include}
202 The \hggopt{-X} filter is best read as ``process only the files that
203 don't match this pattern''.
204 \interaction{filenames.filter.exclude}
206 \section{Ignoring unwanted files and directories}
208 XXX.
210 \section{Case sensitivity}
211 \label{sec:names:case}
213 If you're working in a mixed development environment that contains
214 both Linux (or other Unix) systems and Macs or Windows systems, you
215 should keep in the back of your mind the knowledge that they treat the
216 case (``N'' versus ``n'') of file names in incompatible ways. This is
217 not very likely to affect you, and it's easy to deal with if it does,
218 but it could surprise you if you don't know about it.
220 Operating systems and filesystems differ in the way they handle the
221 \emph{case} of characters in file and directory names. There are
222 three common ways to handle case in names.
223 \begin{itemize}
224 \item Completely case insensitive. Uppercase and lowercase versions
225 of a letter are treated as identical, both when creating a file and
226 during subsequent accesses. This is common on older DOS-based
227 systems.
228 \item Case preserving, but insensitive. When a file or directory is
229 created, the case of its name is stored, and can be retrieved and
230 displayed by the operating system. When an existing file is being
231 looked up, its case is ignored. This is the standard arrangement on
232 Windows and MacOS. The names \filename{foo} and \filename{FoO}
233 identify the same file. This treatment of uppercase and lowercase
234 letters as interchangeable is also referred to as \emph{case
235 folding}.
236 \item Case sensitive. The case of a name is significant at all times.
237 The names \filename{foo} and {FoO} identify different files. This
238 is the way Linux and Unix systems normally work.
239 \end{itemize}
241 On Unix-like systems, it is possible to have any or all of the above
242 ways of handling case in action at once. For example, if you use a
243 USB thumb drive formatted with a FAT32 filesystem on a Linux system,
244 Linux will handle names on that filesystem in a case preserving, but
245 insensitive, way.
247 \subsection{Safe, portable repository storage}
249 Mercurial's repository storage mechanism is \emph{case safe}. It
250 translates file names so that they can be safely stored on both case
251 sensitive and case insensitive filesystems. This means that you can
252 use normal file copying tools to transfer a Mercurial repository onto,
253 for example, a USB thumb drive, and safely move that drive and
254 repository back and forth between a Mac, a PC running Windows, and a
255 Linux box.
257 \subsection{Detecting case conflicts}
259 When operating in the working directory, Mercurial honours the naming
260 policy of the filesystem where the working directory is located. If
261 the filesystem is case preserving, but insensitive, Mercurial will
262 treat names that differ only in case as the same.
264 An important aspect of this approach is that it is possible to commit
265 a changeset on a case sensitive (typically Linux or Unix) filesystem
266 that will cause trouble for users on case insensitive (usually Windows
267 and MacOS) users. If a Linux user commits changes to two files, one
268 named \filename{myfile.c} and the other named \filename{MyFile.C},
269 they will be stored correctly in the repository. And in the working
270 directories of other Linux users, they will be correctly represented
271 as separate files.
273 If a Windows or Mac user pulls this change, they will not initially
274 have a problem, because Mercurial's repository storage mechanism is
275 case safe. However, once they try to \hgcmd{update} the working
276 directory to that changeset, or \hgcmd{merge} with that changeset,
277 Mercurial will spot the conflict between the two file names that the
278 filesystem would treat as the same, and forbid the update or merge
279 from occurring.
281 \subsection{Fixing a case conflict}
283 If you are using Windows or a Mac in a mixed environment where some of
284 your collaborators are using Linux or Unix, and Mercurial reports a
285 case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
286 the procedure to fix the problem is simple.
288 Just find a nearby Linux or Unix box, clone the problem repository
289 onto it, and use Mercurial's \hgcmd{rename} command to change the
290 names of any offending files or directories so that they will no
291 longer cause case folding conflicts. Commit this change, \hgcmd{pull}
292 or \hgcmd{push} it across to your Windows or MacOS system, and
293 \hgcmd{update} to the revision with the non-conflicting names.
295 The changeset with case-conflicting names will remain in your
296 project's history, and you still won't be able to \hgcmd{update} your
297 working directory to that changeset on a Windows or MacOS system, but
298 you can continue development unimpeded.
300 \begin{note}
301 Prior to version~0.9.3, Mercurial did not use a case safe repository
302 storage mechanism, and did not detect case folding conflicts. If
303 you are using an older version of Mercurial on Windows or MacOS, I
304 strongly recommend that you upgrade.
305 \end{note}
307 %%% Local Variables:
308 %%% mode: latex
309 %%% TeX-master: "00book"
310 %%% End: