hgbook

annotate es/filenames.tex @ 431:f809de31887a

find changesets by author, revision, files, or words in the commit message
more translation :D

added a term to the glossary
author jerojasro@localhost
date Sun Nov 30 18:41:51 2008 -0500 (2008-11-30)
parents 3afc654d70e5
children 5da084395a69
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
igor@402 158 A ``\texttt{\{}'' begins a group of subpatterns, where the whole group
igor@402 159 matches if any subpattern in the group matches. The ``\texttt{,}''
igor@402 160 character separates subpatterns, and ``\texttt{\}}'' ends the group.
igor@402 161 \interaction{filenames.glob.group}
igor@402 162
igor@402 163 \subsubsection{Watch out!}
igor@402 164
igor@402 165 Don't forget that if you want to match a pattern in any directory, you
igor@402 166 should not be using the ``\texttt{*}'' match-any token, as this will
igor@402 167 only match within one directory. Instead, use the ``\texttt{**}''
igor@402 168 token. This small example illustrates the difference between the two.
igor@402 169 \interaction{filenames.glob.star-starstar}
igor@402 170
igor@402 171 \subsection{Regular expression matching with \texttt{re} patterns}
igor@402 172
igor@402 173 Mercurial accepts the same regular expression syntax as the Python
igor@402 174 programming language (it uses Python's regexp engine internally).
igor@402 175 This is based on the Perl language's regexp syntax, which is the most
igor@402 176 popular dialect in use (it's also used in Java, for example).
igor@402 177
igor@402 178 I won't discuss Mercurial's regexp dialect in any detail here, as
igor@402 179 regexps are not often used. Perl-style regexps are in any case
igor@402 180 already exhaustively documented on a multitude of web sites, and in
igor@402 181 many books. Instead, I will focus here on a few things you should
igor@402 182 know if you find yourself needing to use regexps with Mercurial.
igor@402 183
igor@402 184 A regexp is matched against an entire file name, relative to the root
igor@402 185 of the repository. In other words, even if you're already in
igor@402 186 subbdirectory \dirname{foo}, if you want to match files under this
igor@402 187 directory, your pattern must start with ``\texttt{foo/}''.
igor@402 188
igor@402 189 One thing to note, if you're familiar with Perl-style regexps, is that
igor@402 190 Mercurial's are \emph{rooted}. That is, a regexp starts matching
igor@402 191 against the beginning of a string; it doesn't look for a match
igor@402 192 anywhere within the string. To match anywhere in a string, start
igor@402 193 your pattern with ``\texttt{.*}''.
igor@402 194
igor@402 195 \section{Filtering files}
igor@402 196
igor@402 197 Not only does Mercurial give you a variety of ways to specify files;
igor@402 198 it lets you further winnow those files using \emph{filters}. Commands
igor@402 199 that work with file names accept two filtering options.
igor@402 200 \begin{itemize}
igor@402 201 \item \hggopt{-I}, or \hggopt{--include}, lets you specify a pattern
igor@402 202 that file names must match in order to be processed.
igor@402 203 \item \hggopt{-X}, or \hggopt{--exclude}, gives you a way to
igor@402 204 \emph{avoid} processing files, if they match this pattern.
igor@402 205 \end{itemize}
igor@402 206 You can provide multiple \hggopt{-I} and \hggopt{-X} options on the
igor@402 207 command line, and intermix them as you please. Mercurial interprets
igor@402 208 the patterns you provide using glob syntax by default (but you can use
igor@402 209 regexps if you need to).
igor@402 210
igor@402 211 You can read a \hggopt{-I} filter as ``process only the files that
igor@402 212 match this filter''.
igor@402 213 \interaction{filenames.filter.include}
igor@402 214 The \hggopt{-X} filter is best read as ``process only the files that
igor@402 215 don't match this pattern''.
igor@402 216 \interaction{filenames.filter.exclude}
igor@402 217
igor@402 218 \section{Ignoring unwanted files and directories}
igor@402 219
igor@402 220 XXX.
igor@402 221
igor@402 222 \section{Case sensitivity}
igor@402 223 \label{sec:names:case}
igor@402 224
igor@402 225 If you're working in a mixed development environment that contains
igor@402 226 both Linux (or other Unix) systems and Macs or Windows systems, you
igor@402 227 should keep in the back of your mind the knowledge that they treat the
igor@402 228 case (``N'' versus ``n'') of file names in incompatible ways. This is
igor@402 229 not very likely to affect you, and it's easy to deal with if it does,
igor@402 230 but it could surprise you if you don't know about it.
igor@402 231
igor@402 232 Operating systems and filesystems differ in the way they handle the
igor@402 233 \emph{case} of characters in file and directory names. There are
igor@402 234 three common ways to handle case in names.
igor@402 235 \begin{itemize}
igor@402 236 \item Completely case insensitive. Uppercase and lowercase versions
igor@402 237 of a letter are treated as identical, both when creating a file and
igor@402 238 during subsequent accesses. This is common on older DOS-based
igor@402 239 systems.
igor@402 240 \item Case preserving, but insensitive. When a file or directory is
igor@402 241 created, the case of its name is stored, and can be retrieved and
igor@402 242 displayed by the operating system. When an existing file is being
igor@402 243 looked up, its case is ignored. This is the standard arrangement on
igor@402 244 Windows and MacOS. The names \filename{foo} and \filename{FoO}
igor@402 245 identify the same file. This treatment of uppercase and lowercase
igor@402 246 letters as interchangeable is also referred to as \emph{case
igor@402 247 folding}.
igor@402 248 \item Case sensitive. The case of a name is significant at all times.
igor@402 249 The names \filename{foo} and {FoO} identify different files. This
igor@402 250 is the way Linux and Unix systems normally work.
igor@402 251 \end{itemize}
igor@402 252
igor@402 253 On Unix-like systems, it is possible to have any or all of the above
igor@402 254 ways of handling case in action at once. For example, if you use a
igor@402 255 USB thumb drive formatted with a FAT32 filesystem on a Linux system,
igor@402 256 Linux will handle names on that filesystem in a case preserving, but
igor@402 257 insensitive, way.
igor@402 258
igor@402 259 \subsection{Safe, portable repository storage}
igor@402 260
igor@402 261 Mercurial's repository storage mechanism is \emph{case safe}. It
igor@402 262 translates file names so that they can be safely stored on both case
igor@402 263 sensitive and case insensitive filesystems. This means that you can
igor@402 264 use normal file copying tools to transfer a Mercurial repository onto,
igor@402 265 for example, a USB thumb drive, and safely move that drive and
igor@402 266 repository back and forth between a Mac, a PC running Windows, and a
igor@402 267 Linux box.
igor@402 268
igor@402 269 \subsection{Detecting case conflicts}
igor@402 270
igor@402 271 When operating in the working directory, Mercurial honours the naming
igor@402 272 policy of the filesystem where the working directory is located. If
igor@402 273 the filesystem is case preserving, but insensitive, Mercurial will
igor@402 274 treat names that differ only in case as the same.
igor@402 275
igor@402 276 An important aspect of this approach is that it is possible to commit
igor@402 277 a changeset on a case sensitive (typically Linux or Unix) filesystem
igor@402 278 that will cause trouble for users on case insensitive (usually Windows
igor@402 279 and MacOS) users. If a Linux user commits changes to two files, one
igor@402 280 named \filename{myfile.c} and the other named \filename{MyFile.C},
igor@402 281 they will be stored correctly in the repository. And in the working
igor@402 282 directories of other Linux users, they will be correctly represented
igor@402 283 as separate files.
igor@402 284
igor@402 285 If a Windows or Mac user pulls this change, they will not initially
igor@402 286 have a problem, because Mercurial's repository storage mechanism is
igor@402 287 case safe. However, once they try to \hgcmd{update} the working
igor@402 288 directory to that changeset, or \hgcmd{merge} with that changeset,
igor@402 289 Mercurial will spot the conflict between the two file names that the
igor@402 290 filesystem would treat as the same, and forbid the update or merge
igor@402 291 from occurring.
igor@402 292
igor@402 293 \subsection{Fixing a case conflict}
igor@402 294
igor@402 295 If you are using Windows or a Mac in a mixed environment where some of
igor@402 296 your collaborators are using Linux or Unix, and Mercurial reports a
igor@402 297 case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
igor@402 298 the procedure to fix the problem is simple.
igor@402 299
igor@402 300 Just find a nearby Linux or Unix box, clone the problem repository
igor@402 301 onto it, and use Mercurial's \hgcmd{rename} command to change the
igor@402 302 names of any offending files or directories so that they will no
igor@402 303 longer cause case folding conflicts. Commit this change, \hgcmd{pull}
igor@402 304 or \hgcmd{push} it across to your Windows or MacOS system, and
igor@402 305 \hgcmd{update} to the revision with the non-conflicting names.
igor@402 306
igor@402 307 The changeset with case-conflicting names will remain in your
igor@402 308 project's history, and you still won't be able to \hgcmd{update} your
igor@402 309 working directory to that changeset on a Windows or MacOS system, but
igor@402 310 you can continue development unimpeded.
igor@402 311
igor@402 312 \begin{note}
igor@402 313 Prior to version~0.9.3, Mercurial did not use a case safe repository
igor@402 314 storage mechanism, and did not detect case folding conflicts. If
igor@402 315 you are using an older version of Mercurial on Windows or MacOS, I
igor@402 316 strongly recommend that you upgrade.
igor@402 317 \end{note}
igor@402 318
igor@402 319 %%% Local Variables:
igor@402 320 %%% mode: latex
igor@402 321 %%% TeX-master: "00book"
igor@402 322 %%% End: