igor@402: \chapter{File names and pattern matching}
igor@402: \label{chap:names}
igor@402: 
jerojasro@430: Mercurial provee mecanismos que le permiten trabajar con nombres de
jerojasro@430: ficheros en una manera consistente y expresiva.
jerojasro@430: 
jerojasro@430: \section{Nombrado de ficheros simple}
jerojasro@430: 
jerojasro@430: % TODO traducción literal de "under the hood". revisar
jerojasro@430: Mercurial usa un mecanismo unificado ``bajo el capó'' para manejar
jerojasro@430: nombres de ficheros. Cada comando se comporta de manera uniforme con
jerojasro@430: respecto a los nombres de fichero. La manera en que los comandos
jerojasro@430: operan con nombres de fichero es la siguiente.
jerojasro@430: 
jerojasro@430: Si usted especifica explícitamente nombres reales de ficheros en la
jerojasro@430: línea de comandos, Mercurial opera únicamente sobre dichos ficheros,
jerojasro@430: como usted esperaría.
igor@402: \interaction{filenames.files}
igor@402: 
jerojasro@430: Cuando usted provee el nombre de un directorio, Mercurial interpreta
jerojasro@430: eso como ``opere en cada fichero en este directorio y sus
jerojasro@430: subdirectorios''. Mercurial va por todos los ficheros y subdirectorios
jerojasro@430: de un directorio en orden alfabético. Cuando encuentra un
jerojasro@430: subdirectorio, lo recorrerá antes de continuar con el directorio
jerojasro@430: actual.
igor@402: \interaction{filenames.dirs}
igor@402: 
jerojasro@430: \section{Ejecución de comandos sin ningún nombre de fichero}
jerojasro@430: 
jerojasro@430: Los comandos de Mercurial que trabajan con nombres de fichero tienen
jerojasro@430: comportamientos por defecto adecuados cuando son utilizados sin pasar
jerojasro@430: ningún patrón o nombre de fichero. El tipo de comportamiento depende
jerojasro@431: de lo que haga el comando. Aquí presento unas cuantas reglas generales
jerojasro@431: que usted puede usar para que es lo que probablemente hará un comando
jerojasro@431: si usted no le pasa ningún nombre de fichero con el cual trabajar.
igor@402: \begin{itemize}
jerojasro@431: \item Muchos comandos operarán sobre el directorio de trabajo
jerojasro@431:     completo. Por ejemplo, esto es lo que hace el comando
jerojasro@431:     \hgcmd{add},
jerojasro@431: \item Si el comando tiene efectos difíciles o incluso imposibles de
jerojasro@431:     revertir, se le obligará a usted a proveer explícitamente al menos
jerojasro@431:     % TODO revisar ese "lo proteje a usted"
jerojasro@431:     un nombre o patrón (ver más abajo). Esto lo proteje a usted de,
jerojasro@431:     por ejemplo, borrar ficheros accidentalmente al ejecutar
jerojasro@431:     \hgcmd{remove} sin ningún argumento.
igor@402: \end{itemize}
igor@402: 
jerojasro@431: 
jerojasro@431: Es fácil evitar este comportamiento por defecto, si no es el adecuado
jerojasro@431: para usted. Si un comando opera normalmente en todo el directorio de
jerojasro@431: trabajo, usted puede llamarlo para que trabaje sólo en el directorio
jerojasro@431: actual y sus subdirectorio pasándole el nombre ``\dirname{.}''.
igor@402: \interaction{filenames.wdir-subdir}
igor@402: 
jerojasro@431: Siguiendo la misma línea, algunos comandos normalmente imprimen las
jerojasro@431: rutas de ficheros con respecto a la raíz del repositorio, aún si usted
jerojasro@431: los llama dentro de un subdirectorio. Dichos comandos imprimirán las
jerojasro@431: rutas de los ficheros respecto al directorio en que usted se encuentra
jerojasro@431: si se les pasan nombres explícitos. Vamos a ejecutar el comando
jerojasro@431: \hgcmd{status} desde un subdirectorio, y a hacer que opere en el
jerojasro@431: directorio de trabajo completo, a la vez que todas las rutas de
jerojasro@431: ficheros se imprimen respecto a nuestro subdirectorio, pasándole la
jerojasro@431: salida del comando \hgcmd{root}.
igor@402: \interaction{filenames.wdir-relname}
igor@402: 
jerojasro@431: \section{Reportar que está pasando}
jerojasro@431: 
jerojasro@431: El ejemplo con el comando \hgcmd{add} en la sección anterior ilustra
jerojasro@431: algo más que es útil acerca de los comandos de Mercurial. Si un
jerojasro@431: comando opera en un fichero que usted no pasó explícitamente en la
jerojasro@431: línea de comandos, usualmente se imprimirá el nombre del fichero, para
jerojasro@431: que usted no sea sorprendido por lo que sucede.
jerojasro@431: 
jerojasro@431: Esto es el principio de \emph{mínima sorpresa}. Si usted se ha
jerojasro@431: referido explícitamente a un fichero en la línea de comandos, no tiene
jerojasro@431: mucho sentido repetir esto de vuelta a usted. Si Mercurial está
jerojasro@431: actuando en un fichero \emph{implícitamente}, porque usted no pasó
jerojasro@431: nombres, ni directorios, ni patrones (ver más abajo), lo más seguro es
jerojasro@431: decirle a usted qué se está haciendo.
jerojasro@431: 
jerojasro@431: Usted puede silenciar a los comandos que se comportan de esta manera
jerojasro@431: usando la opción \hggopt{-q}.  También puede hacer que impriman el
jerojasro@431: nombre de cada fichero, aún aquellos que usted indicó explícitamente,
jerojasro@431: usando la opción \hggopt{-v}.
jerojasro@431: 
jerojasro@431: \section{Uso de patrones para identificar ficheros}
jerojasro@431: 
jerojasro@431: Además de trabajar con nombres de ficheros y directorios, Mercurial le
jerojasro@431: permite usar \emph{patrones} para identificar ficheros. El manejo de
jerojasro@431: patrones de Mercurial es expresivo.
jerojasro@431: 
jerojasro@431: En sistemas tipo Unix (Linux, MacOS, etc.), el trabajo de asociar
jerojasro@431: patrones con nombres de ficheros recae sobre el intérprete de comandos.
jerojasro@431: En estos sistemas, usted debe indicarle explícitamente a Mercurial que
jerojasro@431: el nombre que se le pasa es un patrón. En Windows, el intérprete no
jerojasro@431: expande los patrones, así que Mercurial identificará automáticamente
jerojasro@431: los nombres que son patrones, y hará la expansión necesaria.
jerojasro@431: 
jerojasro@431: Para pasar un patrón en vez de un nombre normal en la línea de
jerojasro@431: comandos, el mecanismo es simple:
igor@402: \begin{codesample2}
igor@402:   syntax:patternbody
igor@402: \end{codesample2}
jerojasro@431: Un patrón es identificado por una cadena de texto corta que indica qué
jerojasro@431: tipo de patrón es, seguido por un dos puntos, seguido por el patrón en
jerojasro@431: sí.
jerojasro@431: 
jerojasro@431: Mercurial soporta dos tipos de sintaxis para patrones. La que se usa
jerojasro@431: con más frecuencia  se denomina \texttt{glob}\ndt{Grupo, colección,
jerojasro@431: aglomeración.}; es el mismo tipo de asociación de patrones usado por
jerojasro@431: el intérprete de Unix, y también debería ser familiar para los
jerojasro@431: usuarios de la línea de comandos de Windows.
jerojasro@431: 
jerojasro@431: Cuando Mercurial hace asociación automática de patrones en Windows,
jerojasro@431: usa la sintaxis \texttt{glob}.  Por esto, usted puede omitir el
jerojasro@431: prefijo ``\texttt{glob:}'' en Windows, pero también es seguro usarlo.
jerojasro@431: 
jerojasro@431: La sintaxis \texttt{re}\ndt{Expresiones regulares.} es más poderosa;
jerojasro@431: le permite especificar patrones usando expresiones regulares, también
jerojasro@431: conocidas como regexps.
jerojasro@431: 
jerojasro@431: A propósito, en los ejemplos siguientes, por favor note que yo tengo
jerojasro@431: el cuidado de rodear todos mis patrones con comillas sencillas, para
jerojasro@431: que no sean expandidos por el intérprete antes de que Mercurial pueda
jerojasro@431: verlos.
jerojasro@431: 
jerojasro@431: \subsection{Patrones \texttt{glob} estilo intérprete}
jerojasro@431: 
jerojasro@431: Este es un vistazo general de los tipos de patrones que usted puede
jerojasro@431: usar cuando está usando asociación con patrone glob.
jerojasro@431: 
jerojasro@431: La secuencia ``\texttt{*}'' se asocia con cualquier cadena, dentro de
jerojasro@431: un único directorio.
igor@402: \interaction{filenames.glob.star}
igor@402: 
jerojasro@431: La secuencia ``\texttt{**}'' se asocia con cualquier cadena, y cruza los
jerojasro@431: % TODO token
jerojasro@431: límites de los directorios. No es una elemento estándar de los tokens
jerojasro@431: de glob de Unix, pero es aceptado por varios intérpretes Unix
jerojasro@431: populares, y es muy útil.
igor@402: \interaction{filenames.glob.starstar}
igor@402: 
jerojasro@431: La secuencia ``\texttt{?}'' se asocia con cualquier caracter sencillo.
igor@402: \interaction{filenames.glob.question}
igor@402: 
jerojasro@431: El caracter ``\texttt{[}'' marca el inicio de una \emph{clase de
jerojasro@431: caracteres}.  Ella se asocia con cualquier caracter sencillo dentro de
jerojasro@431: la clase. La clase se finaliza con un caracter ``\texttt{]}''. Una
jerojasro@431: clase puede contener múltiples \emph{rango}s de la forma
jerojasro@431: ``\texttt{a-f}'', que en este caso es una abreviación para
igor@402: ``\texttt{abcdef}''.
igor@402: \interaction{filenames.glob.range}
jerojasro@431: Si el primer caracter en aparecer después de ``\texttt{[}'' en la
jerojasro@431: clase de caracteres es un ``\texttt{!}'', se \emph{niega} la clase,
jerojasro@431: haciendo que se asocie con cualquier caracter sencillo que no se
jerojasro@431: encuentre en la clase.
igor@402: 
jerojasro@432: Un ``\texttt{\{}'' marca el inicio de un grupo de subpatrones, en
jerojasro@432: donde todo el grupo es asociado si cualquier subpatrón en el grupo
jerojasro@432: puede ser asociado. El caracter ``\texttt{,}'' separa los subpatrones,
jerojasro@432: y el ``\texttt{\}}'' finaliza el grupo.
igor@402: \interaction{filenames.glob.group}
igor@402: 
jerojasro@432: \subsubsection{Cuidado!}
jerojasro@432: 
jerojasro@432: No olvide que si usted desea asocia un patrón con cualquier
jerojasro@432: directorio, no debería usar el elemento para asociar con cualquier
jerojasro@432: cadena ``\texttt{*}'', ya que éste sólo generará asociaciones dentro
jerojasro@432: de un solo directorio. En vez de eso, use el caracter para asociar con
jerojasro@432: cualquier cadena ``\texttt{**}''. Este pequeño ejemplo ilustra la
jerojasro@432: diferencia entre los dos.
igor@402: \interaction{filenames.glob.star-starstar}
igor@402: 
jerojasro@432: \subsection{Asociación con patrones de expresiones regulares \texttt{re}}
igor@402: 
jerojasro@433: Mercurial acepta la misma sintaxis para expresiones regulares del
jerojasro@433: lenguaje de programación Python (internamente se usa el motor de
jerojasro@433: expresiones regulares de Python). Esta sintaxis está basada en la
jerojasro@433: misma del lenguaje Perl, que es el dialecto más popular en uso
jerojasro@433: (por ejemplo, también se usa en Java).
jerojasro@433: 
jerojasro@433: No discutiré el dialecto de expresiones regulares de Mercurial en
jerojasro@433: detalle aquí, ya que las mismas no son usadas frecuentemente. Las
jerojasro@433: expresiones regulares al estilo Perl se encuentran documentadas
jerojasro@433: exhaustivamente en una multitud de sitios web, y en muchos libros.
jerojasro@433: En vez de eso, me enfocaré en unas cuantas cosas que usted debería
jerojasro@433: conocer si tiene la necesidad de usar expresiones regulares en
jerojasro@433: Mercurial.
jerojasro@433: 
jerojasro@433: Una expresión regular es comparada contra un nombre de fichero
jerojasro@433: completo, relativo a la raíz del repositorio. En otras palabras, aún
jerojasro@433: si usted se encuentra en un subdirectorio \dirname{foo}, si desea
jerojasro@433: asociar ficheros en este directorio, su patrón debe empezar con
jerojasro@433: ``\texttt{foo/}''.
igor@402: 
jerojasro@434: Un detalle a tener en cuenta es que, si le son familiares las
jerojasro@434: expresiones regulares al estilo Perl, las de Mercurial están
jerojasro@434: \emph{enraízadas}. Esto es, que la asociación de una expresión se hace
jerojasro@434: desde el inicio de la cadena; no se buscan coincidencias dentro de la
jerojasro@434: cadena. Para buscar coincidencias en cualquier sitio dentro de una
jerojasro@434: cadena, empiece su patrón con un ``\texttt{.*}''.
jerojasro@434: 
jerojasro@434: \section{Filtrado de archivos}
jerojasro@434: 
jerojasro@434: Mercurial no sólo le provee una variedad de formas para especificar
jerojasro@434: ficheros; le permite limitar aún más dichos ficheros mediante el uso
jerojasro@434: de \emph{filtros}. Los comandos que operan con nombres de fichero
jerojasro@434: aceptan dos opciones de filtrado.
igor@402: \begin{itemize}
jerojasro@434: \item \hggopt{-I}, o \hggopt{--include}, le permite especificar un
jerojasro@434:     patrón con el que deben coincidir los ficheros para ser
jerojasro@434:     procesados.
jerojasro@434: \item \hggopt{-X}, o \hggopt{--exclude}, le brinda una manera de 
jerojasro@434:   \emph{evitar} procesar ficheros, si coinciden con este patrón.
igor@402: \end{itemize}
jerojasro@434: Usted puede pasar múltiples veces las opciones \hggopt{-I} y
jerojasro@434: \hggopt{-X} en la línea de comandos, e intercalarlos como desee.
jerojasro@434: Por defecto, Mercurial interpreta los patrones que usted pase usando
jerojasro@434: la sintaxis glob (pero usted puede usar expresiones regulares si lo
jerojasro@434: necesita).
jerojasro@434: 
jerojasro@434: El filtro \hggopt{-I} puede verse como un ``procese todos los ficheros
jerojasro@434: que coincidan con este filtro''.
igor@402: \interaction{filenames.filter.include}
jerojasro@434: El filtro \hggopt{-X} puede verse como ``procese únicamente los
jerojasro@434: ficheros que no coincidan con este patrón''.
igor@402: \interaction{filenames.filter.exclude}
igor@402: 
jerojasro@434: \section{Ignorar ficheros y directorios no deseados}
igor@402: 
igor@402: XXX.
igor@402: 
igor@402: \section{Case sensitivity}
igor@402: \label{sec:names:case}
igor@402: 
jerojasro@434: Si usted está trabajando en un ambiente de desarrollo mixto que
jerojasro@434: contiene tanto sistemas Linux (u otro Unix) y sistemas Mac o Windows,
jerojasro@434: debería tener en mente el hecho de que ellos tratan 
jerojasro@434: %TODO FIXME seguir desde aqui, no tengo idea de como traducir case
jerojasro@434: %sensitivity
igor@402: case (``N'' versus ``n'') of file names in incompatible ways.  This is
igor@402: not very likely to affect you, and it's easy to deal with if it does,
igor@402: but it could surprise you if you don't know about it.
igor@402: 
igor@402: Operating systems and filesystems differ in the way they handle the
igor@402: \emph{case} of characters in file and directory names.  There are
igor@402: three common ways to handle case in names.
igor@402: \begin{itemize}
igor@402: \item Completely case insensitive.  Uppercase and lowercase versions
igor@402:   of a letter are treated as identical, both when creating a file and
igor@402:   during subsequent accesses.  This is common on older DOS-based
igor@402:   systems.
igor@402: \item Case preserving, but insensitive.  When a file or directory is
igor@402:   created, the case of its name is stored, and can be retrieved and
igor@402:   displayed by the operating system.  When an existing file is being
igor@402:   looked up, its case is ignored.  This is the standard arrangement on
igor@402:   Windows and MacOS.  The names \filename{foo} and \filename{FoO}
igor@402:   identify the same file.  This treatment of uppercase and lowercase
igor@402:   letters as interchangeable is also referred to as \emph{case
igor@402:     folding}.
igor@402: \item Case sensitive.  The case of a name is significant at all times.
igor@402:   The names \filename{foo} and {FoO} identify different files.  This
igor@402:   is the way Linux and Unix systems normally work.
igor@402: \end{itemize}
igor@402: 
igor@402: On Unix-like systems, it is possible to have any or all of the above
igor@402: ways of handling case in action at once.  For example, if you use a
igor@402: USB thumb drive formatted with a FAT32 filesystem on a Linux system,
igor@402: Linux will handle names on that filesystem in a case preserving, but
igor@402: insensitive, way.
igor@402: 
jerojasro@434: \subsection{Almacenamiento portable y seguro de repositorios}
jerojasro@434: 
jerojasro@434: El mecanismo de almacenamiento de los repositorios en Mercurial es
jerojasro@434: %TODO aarrrgh, más case!!!
jerojasro@434: \emph{robusto frente a case sensitivity/insensitivity}. Los nombres de
jerojasro@434: fichero son traducidos para que puedan ser almacenados de manera
jerojasro@434: %TODO GRRRRR
jerojasro@434: segura tanto en sistemas case sensitive o case insensitive. Esto
jerojasro@434: significa que usted puede usar herramientas normales de copia de
jerojasro@434: ficheros para transferir un repositorio Mercurial a, por ejemplo, una
jerojasro@434: memoria USB, y trasladar de manera segura la memoria y el repositorio
jerojasro@434: de ida y vuelta entre un Mac, un PC ejecutando Windows, y un sistema
jerojasro@434: Linux
jerojasro@434: 
jerojasro@434: \subsection{Detección de conflictos de mayúsculas/minúsculas}
jerojasro@434: %TODO FIXME continuar aca, me niego a seguir traduciendo esto de
jerojasro@434: %momento
igor@402: 
igor@402: When operating in the working directory, Mercurial honours the naming
igor@402: policy of the filesystem where the working directory is located.  If
igor@402: the filesystem is case preserving, but insensitive, Mercurial will
igor@402: treat names that differ only in case as the same.
igor@402: 
igor@402: An important aspect of this approach is that it is possible to commit
igor@402: a changeset on a case sensitive (typically Linux or Unix) filesystem
igor@402: that will cause trouble for users on case insensitive (usually Windows
igor@402: and MacOS) users.  If a Linux user commits changes to two files, one
igor@402: named \filename{myfile.c} and the other named \filename{MyFile.C},
igor@402: they will be stored correctly in the repository.  And in the working
igor@402: directories of other Linux users, they will be correctly represented
igor@402: as separate files.
igor@402: 
igor@402: If a Windows or Mac user pulls this change, they will not initially
igor@402: have a problem, because Mercurial's repository storage mechanism is
igor@402: case safe.  However, once they try to \hgcmd{update} the working
igor@402: directory to that changeset, or \hgcmd{merge} with that changeset,
igor@402: Mercurial will spot the conflict between the two file names that the
igor@402: filesystem would treat as the same, and forbid the update or merge
igor@402: from occurring.
igor@402: 
igor@402: \subsection{Fixing a case conflict}
igor@402: 
igor@402: If you are using Windows or a Mac in a mixed environment where some of
igor@402: your collaborators are using Linux or Unix, and Mercurial reports a
igor@402: case folding conflict when you try to \hgcmd{update} or \hgcmd{merge},
igor@402: the procedure to fix the problem is simple.
igor@402: 
igor@402: Just find a nearby Linux or Unix box, clone the problem repository
igor@402: onto it, and use Mercurial's \hgcmd{rename} command to change the
igor@402: names of any offending files or directories so that they will no
igor@402: longer cause case folding conflicts.  Commit this change, \hgcmd{pull}
igor@402: or \hgcmd{push} it across to your Windows or MacOS system, and
igor@402: \hgcmd{update} to the revision with the non-conflicting names.
igor@402: 
igor@402: The changeset with case-conflicting names will remain in your
igor@402: project's history, and you still won't be able to \hgcmd{update} your
igor@402: working directory to that changeset on a Windows or MacOS system, but
igor@402: you can continue development unimpeded.
igor@402: 
igor@402: \begin{note}
igor@402:   Prior to version~0.9.3, Mercurial did not use a case safe repository
igor@402:   storage mechanism, and did not detect case folding conflicts.  If
igor@402:   you are using an older version of Mercurial on Windows or MacOS, I
igor@402:   strongly recommend that you upgrade.
igor@402: \end{note}
igor@402: 
igor@402: %%% Local Variables: 
igor@402: %%% mode: latex
igor@402: %%% TeX-master: "00book"
igor@402: %%% End: