hgbook

annotate es/filenames.tex @ 441:4e0684e824e1

find changesets by author, revision, files, or words in the commit message
translated up to the tutorial on using hooks
author jerojasro@abu.no-ip.org
date Mon Dec 08 11:16:54 2008 -0500 (2008-12-08)
parents 7d3e036025fb
children b8b121ed7551
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
jerojasro@434 196 Un detalle a tener en cuenta es que, si le son familiares las
jerojasro@434 197 expresiones regulares al estilo Perl, las de Mercurial están
jerojasro@434 198 \emph{enraízadas}. Esto es, que la asociación de una expresión se hace
jerojasro@434 199 desde el inicio de la cadena; no se buscan coincidencias dentro de la
jerojasro@434 200 cadena. Para buscar coincidencias en cualquier sitio dentro de una
jerojasro@434 201 cadena, empiece su patrón con un ``\texttt{.*}''.
jerojasro@434 202
jerojasro@434 203 \section{Filtrado de archivos}
jerojasro@434 204
jerojasro@434 205 Mercurial no sólo le provee una variedad de formas para especificar
jerojasro@434 206 ficheros; le permite limitar aún más dichos ficheros mediante el uso
jerojasro@434 207 de \emph{filtros}. Los comandos que operan con nombres de fichero
jerojasro@434 208 aceptan dos opciones de filtrado.
igor@402 209 \begin{itemize}
jerojasro@434 210 \item \hggopt{-I}, o \hggopt{--include}, le permite especificar un
jerojasro@434 211 patrón con el que deben coincidir los ficheros para ser
jerojasro@434 212 procesados.
jerojasro@434 213 \item \hggopt{-X}, o \hggopt{--exclude}, le brinda una manera de
jerojasro@434 214 \emph{evitar} procesar ficheros, si coinciden con este patrón.
igor@402 215 \end{itemize}
jerojasro@434 216 Usted puede pasar múltiples veces las opciones \hggopt{-I} y
jerojasro@434 217 \hggopt{-X} en la línea de comandos, e intercalarlos como desee.
jerojasro@434 218 Por defecto, Mercurial interpreta los patrones que usted pase usando
jerojasro@434 219 la sintaxis glob (pero usted puede usar expresiones regulares si lo
jerojasro@434 220 necesita).
jerojasro@434 221
jerojasro@434 222 El filtro \hggopt{-I} puede verse como un ``procese todos los ficheros
jerojasro@434 223 que coincidan con este filtro''.
igor@402 224 \interaction{filenames.filter.include}
jerojasro@434 225 El filtro \hggopt{-X} puede verse como ``procese únicamente los
jerojasro@434 226 ficheros que no coincidan con este patrón''.
igor@402 227 \interaction{filenames.filter.exclude}
igor@402 228
jerojasro@434 229 \section{Ignorar ficheros y directorios no deseados}
igor@402 230
igor@402 231 XXX.
igor@402 232
igor@402 233 \section{Case sensitivity}
igor@402 234 \label{sec:names:case}
igor@402 235
jerojasro@434 236 Si usted está trabajando en un ambiente de desarrollo mixto que
jerojasro@434 237 contiene tanto sistemas Linux (u otro Unix) y sistemas Mac o Windows,
jerojasro@434 238 debería tener en mente el hecho de que ellos tratan
jerojasro@434 239 %TODO FIXME seguir desde aqui, no tengo idea de como traducir case
jerojasro@434 240 %sensitivity
igor@402 241 case (``N'' versus ``n'') of file names in incompatible ways. This is
igor@402 242 not very likely to affect you, and it's easy to deal with if it does,
igor@402 243 but it could surprise you if you don't know about it.
igor@402 244
igor@402 245 Operating systems and filesystems differ in the way they handle the
igor@402 246 \emph{case} of characters in file and directory names. There are
igor@402 247 three common ways to handle case in names.
igor@402 248 \begin{itemize}
igor@402 249 \item Completely case insensitive. Uppercase and lowercase versions
igor@402 250 of a letter are treated as identical, both when creating a file and
igor@402 251 during subsequent accesses. This is common on older DOS-based
igor@402 252 systems.
igor@402 253 \item Case preserving, but insensitive. When a file or directory is
igor@402 254 created, the case of its name is stored, and can be retrieved and
igor@402 255 displayed by the operating system. When an existing file is being
igor@402 256 looked up, its case is ignored. This is the standard arrangement on
igor@402 257 Windows and MacOS. The names \filename{foo} and \filename{FoO}
igor@402 258 identify the same file. This treatment of uppercase and lowercase
igor@402 259 letters as interchangeable is also referred to as \emph{case
igor@402 260 folding}.
igor@402 261 \item Case sensitive. The case of a name is significant at all times.
igor@402 262 The names \filename{foo} and {FoO} identify different files. This
igor@402 263 is the way Linux and Unix systems normally work.
igor@402 264 \end{itemize}
igor@402 265
igor@402 266 On Unix-like systems, it is possible to have any or all of the above
igor@402 267 ways of handling case in action at once. For example, if you use a
igor@402 268 USB thumb drive formatted with a FAT32 filesystem on a Linux system,
igor@402 269 Linux will handle names on that filesystem in a case preserving, but
igor@402 270 insensitive, way.
igor@402 271
jerojasro@434 272 \subsection{Almacenamiento portable y seguro de repositorios}
jerojasro@434 273
jerojasro@434 274 El mecanismo de almacenamiento de los repositorios en Mercurial es
jerojasro@434 275 %TODO aarrrgh, más case!!!
jerojasro@434 276 \emph{robusto frente a case sensitivity/insensitivity}. Los nombres de
jerojasro@434 277 fichero son traducidos para que puedan ser almacenados de manera
jerojasro@434 278 %TODO GRRRRR
jerojasro@434 279 segura tanto en sistemas case sensitive o case insensitive. Esto
jerojasro@434 280 significa que usted puede usar herramientas normales de copia de
jerojasro@434 281 ficheros para transferir un repositorio Mercurial a, por ejemplo, una
jerojasro@434 282 memoria USB, y trasladar de manera segura la memoria y el repositorio
jerojasro@434 283 de ida y vuelta entre un Mac, un PC ejecutando Windows, y un sistema
jerojasro@434 284 Linux
jerojasro@434 285
jerojasro@434 286 \subsection{Detección de conflictos de mayúsculas/minúsculas}
jerojasro@434 287 %TODO FIXME continuar aca, me niego a seguir traduciendo esto de
jerojasro@434 288 %momento
igor@402 289
igor@402 290 When operating in the working directory, Mercurial honours the naming
igor@402 291 policy of the filesystem where the working directory is located. If
igor@402 292 the filesystem is case preserving, but insensitive, Mercurial will
igor@402 293 treat names that differ only in case as the same.
igor@402 294
igor@402 295 An important aspect of this approach is that it is possible to commit
igor@402 296 a changeset on a case sensitive (typically Linux or Unix) filesystem
igor@402 297 that will cause trouble for users on case insensitive (usually Windows
igor@402 298 and MacOS) users. If a Linux user commits changes to two files, one
igor@402 299 named \filename{myfile.c} and the other named \filename{MyFile.C},
igor@402 300 they will be stored correctly in the repository. And in the working
igor@402 301 directories of other Linux users, they will be correctly represented
igor@402 302 as separate files.
igor@402 303
igor@402 304 If a Windows or Mac user pulls this change, they will not initially
igor@402 305 have a problem, because Mercurial's repository storage mechanism is
igor@402 306 case safe. However, once they try to \hgcmd{update} the working
igor@402 307 directory to that changeset, or \hgcmd{merge} with that changeset,
igor@402 308 Mercurial will spot the conflict between the two file names that the
igor@402 309 filesystem would treat as the same, and forbid the update or merge
igor@402 310 from occurring.
igor@402 311
igor@402 312 \subsection{Fixing a case conflict}
igor@402 313
igor@402 314 If you are using Windows or a Mac in a mixed environment where some of
igor@402 315 your collaborators are using Linux or Unix, and Mercurial reports a
igor@402 316 case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
igor@402 317 the procedure to fix the problem is simple.
igor@402 318
igor@402 319 Just find a nearby Linux or Unix box, clone the problem repository
igor@402 320 onto it, and use Mercurial's \hgcmd{rename} command to change the
igor@402 321 names of any offending files or directories so that they will no
igor@402 322 longer cause case folding conflicts. Commit this change, \hgcmd{pull}
igor@402 323 or \hgcmd{push} it across to your Windows or MacOS system, and
igor@402 324 \hgcmd{update} to the revision with the non-conflicting names.
igor@402 325
igor@402 326 The changeset with case-conflicting names will remain in your
igor@402 327 project's history, and you still won't be able to \hgcmd{update} your
igor@402 328 working directory to that changeset on a Windows or MacOS system, but
igor@402 329 you can continue development unimpeded.
igor@402 330
igor@402 331 \begin{note}
igor@402 332 Prior to version~0.9.3, Mercurial did not use a case safe repository
igor@402 333 storage mechanism, and did not detect case folding conflicts. If
igor@402 334 you are using an older version of Mercurial on Windows or MacOS, I
igor@402 335 strongly recommend that you upgrade.
igor@402 336 \end{note}
igor@402 337
igor@402 338 %%% Local Variables:
igor@402 339 %%% mode: latex
igor@402 340 %%% TeX-master: "00book"
igor@402 341 %%% End: