rev |
line source |
igor@402
|
1 \chapter{File names and pattern matching}
|
igor@402
|
2 \label{chap:names}
|
igor@402
|
3
|
jerojasro@430
|
4 Mercurial provee mecanismos que le permiten trabajar con nombres de
|
jerojasro@430
|
5 ficheros en una manera consistente y expresiva.
|
jerojasro@430
|
6
|
jerojasro@430
|
7 \section{Nombrado de ficheros simple}
|
jerojasro@430
|
8
|
jerojasro@430
|
9 % TODO traducción literal de "under the hood". revisar
|
jerojasro@430
|
10 Mercurial usa un mecanismo unificado ``bajo el capó'' para manejar
|
jerojasro@430
|
11 nombres de ficheros. Cada comando se comporta de manera uniforme con
|
jerojasro@430
|
12 respecto a los nombres de fichero. La manera en que los comandos
|
jerojasro@430
|
13 operan con nombres de fichero es la siguiente.
|
jerojasro@430
|
14
|
jerojasro@430
|
15 Si usted especifica explícitamente nombres reales de ficheros en la
|
jerojasro@430
|
16 línea de comandos, Mercurial opera únicamente sobre dichos ficheros,
|
jerojasro@430
|
17 como usted esperaría.
|
igor@402
|
18 \interaction{filenames.files}
|
igor@402
|
19
|
jerojasro@430
|
20 Cuando usted provee el nombre de un directorio, Mercurial interpreta
|
jerojasro@430
|
21 eso como ``opere en cada fichero en este directorio y sus
|
jerojasro@430
|
22 subdirectorios''. Mercurial va por todos los ficheros y subdirectorios
|
jerojasro@430
|
23 de un directorio en orden alfabético. Cuando encuentra un
|
jerojasro@430
|
24 subdirectorio, lo recorrerá antes de continuar con el directorio
|
jerojasro@430
|
25 actual.
|
igor@402
|
26 \interaction{filenames.dirs}
|
igor@402
|
27
|
jerojasro@430
|
28 \section{Ejecución de comandos sin ningún nombre de fichero}
|
jerojasro@430
|
29
|
jerojasro@430
|
30 Los comandos de Mercurial que trabajan con nombres de fichero tienen
|
jerojasro@430
|
31 comportamientos por defecto adecuados cuando son utilizados sin pasar
|
jerojasro@430
|
32 ningún patrón o nombre de fichero. El tipo de comportamiento depende
|
jerojasro@431
|
33 de lo que haga el comando. Aquí presento unas cuantas reglas generales
|
jerojasro@431
|
34 que usted puede usar para que es lo que probablemente hará un comando
|
jerojasro@431
|
35 si usted no le pasa ningún nombre de fichero con el cual trabajar.
|
igor@402
|
36 \begin{itemize}
|
jerojasro@431
|
37 \item Muchos comandos operarán sobre el directorio de trabajo
|
jerojasro@431
|
38 completo. Por ejemplo, esto es lo que hace el comando
|
jerojasro@431
|
39 \hgcmd{add},
|
jerojasro@431
|
40 \item Si el comando tiene efectos difíciles o incluso imposibles de
|
jerojasro@431
|
41 revertir, se le obligará a usted a proveer explícitamente al menos
|
jerojasro@431
|
42 % TODO revisar ese "lo proteje a usted"
|
jerojasro@431
|
43 un nombre o patrón (ver más abajo). Esto lo proteje a usted de,
|
jerojasro@431
|
44 por ejemplo, borrar ficheros accidentalmente al ejecutar
|
jerojasro@431
|
45 \hgcmd{remove} sin ningún argumento.
|
igor@402
|
46 \end{itemize}
|
igor@402
|
47
|
jerojasro@431
|
48
|
jerojasro@431
|
49 Es fácil evitar este comportamiento por defecto, si no es el adecuado
|
jerojasro@431
|
50 para usted. Si un comando opera normalmente en todo el directorio de
|
jerojasro@431
|
51 trabajo, usted puede llamarlo para que trabaje sólo en el directorio
|
jerojasro@431
|
52 actual y sus subdirectorio pasándole el nombre ``\dirname{.}''.
|
igor@402
|
53 \interaction{filenames.wdir-subdir}
|
igor@402
|
54
|
jerojasro@431
|
55 Siguiendo la misma línea, algunos comandos normalmente imprimen las
|
jerojasro@431
|
56 rutas de ficheros con respecto a la raíz del repositorio, aún si usted
|
jerojasro@431
|
57 los llama dentro de un subdirectorio. Dichos comandos imprimirán las
|
jerojasro@431
|
58 rutas de los ficheros respecto al directorio en que usted se encuentra
|
jerojasro@431
|
59 si se les pasan nombres explícitos. Vamos a ejecutar el comando
|
jerojasro@431
|
60 \hgcmd{status} desde un subdirectorio, y a hacer que opere en el
|
jerojasro@431
|
61 directorio de trabajo completo, a la vez que todas las rutas de
|
jerojasro@431
|
62 ficheros se imprimen respecto a nuestro subdirectorio, pasándole la
|
jerojasro@431
|
63 salida del comando \hgcmd{root}.
|
igor@402
|
64 \interaction{filenames.wdir-relname}
|
igor@402
|
65
|
jerojasro@431
|
66 \section{Reportar que está pasando}
|
jerojasro@431
|
67
|
jerojasro@431
|
68 El ejemplo con el comando \hgcmd{add} en la sección anterior ilustra
|
jerojasro@431
|
69 algo más que es útil acerca de los comandos de Mercurial. Si un
|
jerojasro@431
|
70 comando opera en un fichero que usted no pasó explícitamente en la
|
jerojasro@431
|
71 línea de comandos, usualmente se imprimirá el nombre del fichero, para
|
jerojasro@431
|
72 que usted no sea sorprendido por lo que sucede.
|
jerojasro@431
|
73
|
jerojasro@431
|
74 Esto es el principio de \emph{mínima sorpresa}. Si usted se ha
|
jerojasro@431
|
75 referido explícitamente a un fichero en la línea de comandos, no tiene
|
jerojasro@431
|
76 mucho sentido repetir esto de vuelta a usted. Si Mercurial está
|
jerojasro@431
|
77 actuando en un fichero \emph{implícitamente}, porque usted no pasó
|
jerojasro@431
|
78 nombres, ni directorios, ni patrones (ver más abajo), lo más seguro es
|
jerojasro@431
|
79 decirle a usted qué se está haciendo.
|
jerojasro@431
|
80
|
jerojasro@431
|
81 Usted puede silenciar a los comandos que se comportan de esta manera
|
jerojasro@431
|
82 usando la opción \hggopt{-q}. También puede hacer que impriman el
|
jerojasro@431
|
83 nombre de cada fichero, aún aquellos que usted indicó explícitamente,
|
jerojasro@431
|
84 usando la opción \hggopt{-v}.
|
jerojasro@431
|
85
|
jerojasro@431
|
86 \section{Uso de patrones para identificar ficheros}
|
jerojasro@431
|
87
|
jerojasro@431
|
88 Además de trabajar con nombres de ficheros y directorios, Mercurial le
|
jerojasro@431
|
89 permite usar \emph{patrones} para identificar ficheros. El manejo de
|
jerojasro@431
|
90 patrones de Mercurial es expresivo.
|
jerojasro@431
|
91
|
jerojasro@431
|
92 En sistemas tipo Unix (Linux, MacOS, etc.), el trabajo de asociar
|
jerojasro@431
|
93 patrones con nombres de ficheros recae sobre el intérprete de comandos.
|
jerojasro@431
|
94 En estos sistemas, usted debe indicarle explícitamente a Mercurial que
|
jerojasro@431
|
95 el nombre que se le pasa es un patrón. En Windows, el intérprete no
|
jerojasro@431
|
96 expande los patrones, así que Mercurial identificará automáticamente
|
jerojasro@431
|
97 los nombres que son patrones, y hará la expansión necesaria.
|
jerojasro@431
|
98
|
jerojasro@431
|
99 Para pasar un patrón en vez de un nombre normal en la línea de
|
jerojasro@431
|
100 comandos, el mecanismo es simple:
|
igor@402
|
101 \begin{codesample2}
|
igor@402
|
102 syntax:patternbody
|
igor@402
|
103 \end{codesample2}
|
jerojasro@431
|
104 Un patrón es identificado por una cadena de texto corta que indica qué
|
jerojasro@431
|
105 tipo de patrón es, seguido por un dos puntos, seguido por el patrón en
|
jerojasro@431
|
106 sí.
|
jerojasro@431
|
107
|
jerojasro@431
|
108 Mercurial soporta dos tipos de sintaxis para patrones. La que se usa
|
jerojasro@431
|
109 con más frecuencia se denomina \texttt{glob}\ndt{Grupo, colección,
|
jerojasro@431
|
110 aglomeración.}; es el mismo tipo de asociación de patrones usado por
|
jerojasro@431
|
111 el intérprete de Unix, y también debería ser familiar para los
|
jerojasro@431
|
112 usuarios de la línea de comandos de Windows.
|
jerojasro@431
|
113
|
jerojasro@431
|
114 Cuando Mercurial hace asociación automática de patrones en Windows,
|
jerojasro@431
|
115 usa la sintaxis \texttt{glob}. Por esto, usted puede omitir el
|
jerojasro@431
|
116 prefijo ``\texttt{glob:}'' en Windows, pero también es seguro usarlo.
|
jerojasro@431
|
117
|
jerojasro@431
|
118 La sintaxis \texttt{re}\ndt{Expresiones regulares.} es más poderosa;
|
jerojasro@431
|
119 le permite especificar patrones usando expresiones regulares, también
|
jerojasro@431
|
120 conocidas como regexps.
|
jerojasro@431
|
121
|
jerojasro@431
|
122 A propósito, en los ejemplos siguientes, por favor note que yo tengo
|
jerojasro@431
|
123 el cuidado de rodear todos mis patrones con comillas sencillas, para
|
jerojasro@431
|
124 que no sean expandidos por el intérprete antes de que Mercurial pueda
|
jerojasro@431
|
125 verlos.
|
jerojasro@431
|
126
|
jerojasro@431
|
127 \subsection{Patrones \texttt{glob} estilo intérprete}
|
jerojasro@431
|
128
|
jerojasro@431
|
129 Este es un vistazo general de los tipos de patrones que usted puede
|
jerojasro@431
|
130 usar cuando está usando asociación con patrone glob.
|
jerojasro@431
|
131
|
jerojasro@431
|
132 La secuencia ``\texttt{*}'' se asocia con cualquier cadena, dentro de
|
jerojasro@431
|
133 un único directorio.
|
igor@402
|
134 \interaction{filenames.glob.star}
|
igor@402
|
135
|
jerojasro@431
|
136 La secuencia ``\texttt{**}'' se asocia con cualquier cadena, y cruza los
|
jerojasro@431
|
137 % TODO token
|
jerojasro@431
|
138 límites de los directorios. No es una elemento estándar de los tokens
|
jerojasro@431
|
139 de glob de Unix, pero es aceptado por varios intérpretes Unix
|
jerojasro@431
|
140 populares, y es muy útil.
|
igor@402
|
141 \interaction{filenames.glob.starstar}
|
igor@402
|
142
|
jerojasro@431
|
143 La secuencia ``\texttt{?}'' se asocia con cualquier caracter sencillo.
|
igor@402
|
144 \interaction{filenames.glob.question}
|
igor@402
|
145
|
jerojasro@431
|
146 El caracter ``\texttt{[}'' marca el inicio de una \emph{clase de
|
jerojasro@431
|
147 caracteres}. Ella se asocia con cualquier caracter sencillo dentro de
|
jerojasro@431
|
148 la clase. La clase se finaliza con un caracter ``\texttt{]}''. Una
|
jerojasro@431
|
149 clase puede contener múltiples \emph{rango}s de la forma
|
jerojasro@431
|
150 ``\texttt{a-f}'', que en este caso es una abreviación para
|
igor@402
|
151 ``\texttt{abcdef}''.
|
igor@402
|
152 \interaction{filenames.glob.range}
|
jerojasro@431
|
153 Si el primer caracter en aparecer después de ``\texttt{[}'' en la
|
jerojasro@431
|
154 clase de caracteres es un ``\texttt{!}'', se \emph{niega} la clase,
|
jerojasro@431
|
155 haciendo que se asocie con cualquier caracter sencillo que no se
|
jerojasro@431
|
156 encuentre en la clase.
|
igor@402
|
157
|
jerojasro@432
|
158 Un ``\texttt{\{}'' marca el inicio de un grupo de subpatrones, en
|
jerojasro@432
|
159 donde todo el grupo es asociado si cualquier subpatrón en el grupo
|
jerojasro@432
|
160 puede ser asociado. El caracter ``\texttt{,}'' separa los subpatrones,
|
jerojasro@432
|
161 y el ``\texttt{\}}'' finaliza el grupo.
|
igor@402
|
162 \interaction{filenames.glob.group}
|
igor@402
|
163
|
jerojasro@432
|
164 \subsubsection{Cuidado!}
|
jerojasro@432
|
165
|
jerojasro@432
|
166 No olvide que si usted desea asocia un patrón con cualquier
|
jerojasro@432
|
167 directorio, no debería usar el elemento para asociar con cualquier
|
jerojasro@432
|
168 cadena ``\texttt{*}'', ya que éste sólo generará asociaciones dentro
|
jerojasro@432
|
169 de un solo directorio. En vez de eso, use el caracter para asociar con
|
jerojasro@432
|
170 cualquier cadena ``\texttt{**}''. Este pequeño ejemplo ilustra la
|
jerojasro@432
|
171 diferencia entre los dos.
|
igor@402
|
172 \interaction{filenames.glob.star-starstar}
|
igor@402
|
173
|
jerojasro@432
|
174 \subsection{Asociación con patrones de expresiones regulares \texttt{re}}
|
igor@402
|
175
|
jerojasro@433
|
176 Mercurial acepta la misma sintaxis para expresiones regulares del
|
jerojasro@433
|
177 lenguaje de programación Python (internamente se usa el motor de
|
jerojasro@433
|
178 expresiones regulares de Python). Esta sintaxis está basada en la
|
jerojasro@433
|
179 misma del lenguaje Perl, que es el dialecto más popular en uso
|
jerojasro@433
|
180 (por ejemplo, también se usa en Java).
|
jerojasro@433
|
181
|
jerojasro@433
|
182 No discutiré el dialecto de expresiones regulares de Mercurial en
|
jerojasro@433
|
183 detalle aquí, ya que las mismas no son usadas frecuentemente. Las
|
jerojasro@433
|
184 expresiones regulares al estilo Perl se encuentran documentadas
|
jerojasro@433
|
185 exhaustivamente en una multitud de sitios web, y en muchos libros.
|
jerojasro@433
|
186 En vez de eso, me enfocaré en unas cuantas cosas que usted debería
|
jerojasro@433
|
187 conocer si tiene la necesidad de usar expresiones regulares en
|
jerojasro@433
|
188 Mercurial.
|
jerojasro@433
|
189
|
jerojasro@433
|
190 Una expresión regular es comparada contra un nombre de fichero
|
jerojasro@433
|
191 completo, relativo a la raíz del repositorio. En otras palabras, aún
|
jerojasro@433
|
192 si usted se encuentra en un subdirectorio \dirname{foo}, si desea
|
jerojasro@433
|
193 asociar ficheros en este directorio, su patrón debe empezar con
|
jerojasro@433
|
194 ``\texttt{foo/}''.
|
igor@402
|
195
|
igor@402
|
196 One thing to note, if you're familiar with Perl-style regexps, is that
|
igor@402
|
197 Mercurial's are \emph{rooted}. That is, a regexp starts matching
|
igor@402
|
198 against the beginning of a string; it doesn't look for a match
|
igor@402
|
199 anywhere within the string. To match anywhere in a string, start
|
igor@402
|
200 your pattern with ``\texttt{.*}''.
|
igor@402
|
201
|
igor@402
|
202 \section{Filtering files}
|
igor@402
|
203
|
igor@402
|
204 Not only does Mercurial give you a variety of ways to specify files;
|
igor@402
|
205 it lets you further winnow those files using \emph{filters}. Commands
|
igor@402
|
206 that work with file names accept two filtering options.
|
igor@402
|
207 \begin{itemize}
|
igor@402
|
208 \item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
|
igor@402
|
209 that file names must match in order to be processed.
|
igor@402
|
210 \item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
|
igor@402
|
211 \emph{avoid} processing files, if they match this pattern.
|
igor@402
|
212 \end{itemize}
|
igor@402
|
213 You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
|
igor@402
|
214 command line, and intermix them as you please. Mercurial interprets
|
igor@402
|
215 the patterns you provide using glob syntax by default (but you can use
|
igor@402
|
216 regexps if you need to).
|
igor@402
|
217
|
igor@402
|
218 You can read a \hggopt{-I} filter as ``process only the files that
|
igor@402
|
219 match this filter''.
|
igor@402
|
220 \interaction{filenames.filter.include}
|
igor@402
|
221 The \hggopt{-X} filter is best read as ``process only the files that
|
igor@402
|
222 don't match this pattern''.
|
igor@402
|
223 \interaction{filenames.filter.exclude}
|
igor@402
|
224
|
igor@402
|
225 \section{Ignoring unwanted files and directories}
|
igor@402
|
226
|
igor@402
|
227 XXX.
|
igor@402
|
228
|
igor@402
|
229 \section{Case sensitivity}
|
igor@402
|
230 \label{sec:names:case}
|
igor@402
|
231
|
igor@402
|
232 If you're working in a mixed development environment that contains
|
igor@402
|
233 both Linux (or other Unix) systems and Macs or Windows systems, you
|
igor@402
|
234 should keep in the back of your mind the knowledge that they treat the
|
igor@402
|
235 case (``N'' versus ``n'') of file names in incompatible ways. This is
|
igor@402
|
236 not very likely to affect you, and it's easy to deal with if it does,
|
igor@402
|
237 but it could surprise you if you don't know about it.
|
igor@402
|
238
|
igor@402
|
239 Operating systems and filesystems differ in the way they handle the
|
igor@402
|
240 \emph{case} of characters in file and directory names. There are
|
igor@402
|
241 three common ways to handle case in names.
|
igor@402
|
242 \begin{itemize}
|
igor@402
|
243 \item Completely case insensitive. Uppercase and lowercase versions
|
igor@402
|
244 of a letter are treated as identical, both when creating a file and
|
igor@402
|
245 during subsequent accesses. This is common on older DOS-based
|
igor@402
|
246 systems.
|
igor@402
|
247 \item Case preserving, but insensitive. When a file or directory is
|
igor@402
|
248 created, the case of its name is stored, and can be retrieved and
|
igor@402
|
249 displayed by the operating system. When an existing file is being
|
igor@402
|
250 looked up, its case is ignored. This is the standard arrangement on
|
igor@402
|
251 Windows and MacOS. The names \filename{foo} and \filename{FoO}
|
igor@402
|
252 identify the same file. This treatment of uppercase and lowercase
|
igor@402
|
253 letters as interchangeable is also referred to as \emph{case
|
igor@402
|
254 folding}.
|
igor@402
|
255 \item Case sensitive. The case of a name is significant at all times.
|
igor@402
|
256 The names \filename{foo} and {FoO} identify different files. This
|
igor@402
|
257 is the way Linux and Unix systems normally work.
|
igor@402
|
258 \end{itemize}
|
igor@402
|
259
|
igor@402
|
260 On Unix-like systems, it is possible to have any or all of the above
|
igor@402
|
261 ways of handling case in action at once. For example, if you use a
|
igor@402
|
262 USB thumb drive formatted with a FAT32 filesystem on a Linux system,
|
igor@402
|
263 Linux will handle names on that filesystem in a case preserving, but
|
igor@402
|
264 insensitive, way.
|
igor@402
|
265
|
igor@402
|
266 \subsection{Safe, portable repository storage}
|
igor@402
|
267
|
igor@402
|
268 Mercurial's repository storage mechanism is \emph{case safe}. It
|
igor@402
|
269 translates file names so that they can be safely stored on both case
|
igor@402
|
270 sensitive and case insensitive filesystems. This means that you can
|
igor@402
|
271 use normal file copying tools to transfer a Mercurial repository onto,
|
igor@402
|
272 for example, a USB thumb drive, and safely move that drive and
|
igor@402
|
273 repository back and forth between a Mac, a PC running Windows, and a
|
igor@402
|
274 Linux box.
|
igor@402
|
275
|
igor@402
|
276 \subsection{Detecting case conflicts}
|
igor@402
|
277
|
igor@402
|
278 When operating in the working directory, Mercurial honours the naming
|
igor@402
|
279 policy of the filesystem where the working directory is located. If
|
igor@402
|
280 the filesystem is case preserving, but insensitive, Mercurial will
|
igor@402
|
281 treat names that differ only in case as the same.
|
igor@402
|
282
|
igor@402
|
283 An important aspect of this approach is that it is possible to commit
|
igor@402
|
284 a changeset on a case sensitive (typically Linux or Unix) filesystem
|
igor@402
|
285 that will cause trouble for users on case insensitive (usually Windows
|
igor@402
|
286 and MacOS) users. If a Linux user commits changes to two files, one
|
igor@402
|
287 named \filename{myfile.c} and the other named \filename{MyFile.C},
|
igor@402
|
288 they will be stored correctly in the repository. And in the working
|
igor@402
|
289 directories of other Linux users, they will be correctly represented
|
igor@402
|
290 as separate files.
|
igor@402
|
291
|
igor@402
|
292 If a Windows or Mac user pulls this change, they will not initially
|
igor@402
|
293 have a problem, because Mercurial's repository storage mechanism is
|
igor@402
|
294 case safe. However, once they try to \hgcmd{update} the working
|
igor@402
|
295 directory to that changeset, or \hgcmd{merge} with that changeset,
|
igor@402
|
296 Mercurial will spot the conflict between the two file names that the
|
igor@402
|
297 filesystem would treat as the same, and forbid the update or merge
|
igor@402
|
298 from occurring.
|
igor@402
|
299
|
igor@402
|
300 \subsection{Fixing a case conflict}
|
igor@402
|
301
|
igor@402
|
302 If you are using Windows or a Mac in a mixed environment where some of
|
igor@402
|
303 your collaborators are using Linux or Unix, and Mercurial reports a
|
igor@402
|
304 case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
|
igor@402
|
305 the procedure to fix the problem is simple.
|
igor@402
|
306
|
igor@402
|
307 Just find a nearby Linux or Unix box, clone the problem repository
|
igor@402
|
308 onto it, and use Mercurial's \hgcmd{rename} command to change the
|
igor@402
|
309 names of any offending files or directories so that they will no
|
igor@402
|
310 longer cause case folding conflicts. Commit this change, \hgcmd{pull}
|
igor@402
|
311 or \hgcmd{push} it across to your Windows or MacOS system, and
|
igor@402
|
312 \hgcmd{update} to the revision with the non-conflicting names.
|
igor@402
|
313
|
igor@402
|
314 The changeset with case-conflicting names will remain in your
|
igor@402
|
315 project's history, and you still won't be able to \hgcmd{update} your
|
igor@402
|
316 working directory to that changeset on a Windows or MacOS system, but
|
igor@402
|
317 you can continue development unimpeded.
|
igor@402
|
318
|
igor@402
|
319 \begin{note}
|
igor@402
|
320 Prior to version~0.9.3, Mercurial did not use a case safe repository
|
igor@402
|
321 storage mechanism, and did not detect case folding conflicts. If
|
igor@402
|
322 you are using an older version of Mercurial on Windows or MacOS, I
|
igor@402
|
323 strongly recommend that you upgrade.
|
igor@402
|
324 \end{note}
|
igor@402
|
325
|
igor@402
|
326 %%% Local Variables:
|
igor@402
|
327 %%% mode: latex
|
igor@402
|
328 %%% TeX-master: "00book"
|
igor@402
|
329 %%% End:
|