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