Todos los patrones que usa git

Hagamos un pequeño repaso de lo que ya sabemos:

• Las líneas en blanco no se consideran un patrón. Se usan para hacer los ficheros más legibles
• Si la linea comienza con #, se considera un comentario
• El prefijo ! sirve para negar un patrón
• Si el patrón termina en / sólo se aplicará a carpetas, es decir, un patrón «web/» ignorará la carpeta web/ pero no ignorará un fichero que se llame web

Hasta aquí lo que ya habíamos visto ¿qué nos falta?

• Si el patrón no termina en /, git lo interpreta como un «shell glob pattern«. Internamente git llama a la función fnmatch con el flag FNM_PATHNAME: esto significa que ni el * ni el ? incluyen el carácter /. En seguida veremos ejemplos.
• Una / al principio del patrón indica el inicio de una ruta relativa a la carpeta en la que se encuentre el fichero .gitignore. Una línea del tipo /config.php ignorará el fichero config.php pero no ignorará web/config.php

Shell globs en git

Los ficheros .gitignore, .git/info/exclude y .gitignore_local permiten incluir patrones de tipo shell. Si habéis trabajado con cualquier shell de Unix o el CMD de windows, estaréis familiarizados con el funcionamiento de estos patrones. En caso contrario, aquí tenéis las reglas que se siguen.

En una expresión que contenga el símbolo «?», éste se corresponde con uno y sólo un carácter

Ejemplos:

# Ignora los ficheros bg-01.jpg bg-lt.jpg
#
# No ignora los ficheros bg-1.jpg y bg-001.jpg
#
bg-??.jpg

Este patrón ignorará los ficheros cuyos nombres empiezan por «bg-«, van seguidos exactamente de dos caracteres, y luego van seguidos de «.jpg». Por eso el fichero bg-1.jpg no se ignora, porque entre «bg-» y «.jpg» no hay dos caracteres, sólo uno. Este ejemplo ilustra que el símbolo «?» no indica un caracter opcional.

En una expresión que contenga el símbolo » * «, éste se corresponde con cualquier número de caracteres

Ejemplos:

# Ignora todos los ficheros acabados en .nib
#
# Ignora tanto MainWindow.nib y builds/MainWindow.nib
*.nib

#Ignora todos los ficheros que empiecen por "bg-" y acaben en ".jpg"
bg-*.jpg

En el primer ejemplo, estamos ignorando cualquier fichero que acabe en .nib, independientemente de la carpeta en la que se encuentre. En el segundo ejemplo, estamos ignorando cualquier fichero que empiece por «bg-» y acabe por «.jpg». Una pregunta: ¿se ignorará el fichero «bg-.jpg» usando este patrón?. La respuesta la tenéis un poco más abajo.

En una expresión que contenga corchetes [ ], éstos se corresponden con uno y sólo un caracter de los que están incluidos en los corchetes.

Ejemplos:

# Ignora los ficheros *.o y *.a
*.[ao]

# Ignora los ficheros .nib y .xib
*.[xn]ib

Estos patrones no ignoran los ficheros liberia.so o los ficheros mainwindow.ib. Es necesario que alguno de los caracteres que están entre corchetes aparezcan en el fichero.

Si se necesita utilizar los caracteres ? * [ ] en un patrón, estos deberán escaparse con \

Ejemplo:

# Ignorando ficheros que contienen [ y ] en el nombre
#
# Este patrón ignorará los ficheros
# cache/cache-[hG7].cache y cache/cache-[009].cache
cache/cache-\[???\].cache

Shell globs y carpetas

¿Qué significa que git utilice el flag FNM_PATHNAME al llamar a la función fnmatch? Que los símbolos * ? y [] no incluyen el caracter » / » de separación de directorios.

# El uso de FNM_PATHNAME hace que el siguiente patrón ignore los ficheros
# web/fichero.html, pero no ignore el fichero web/admin/fichero.html
#
# Como el " * " no incluye " / ", el fichero web/admin/fichero.html no 
# encaja con el patrón
web/*.html

¿Qué ocurre si necesitamos justo el efecto contrario? es decir, queremos ignorar todos los ficheros .html que están en las subcarpetas de web pero no ignorar los ficheros .html que están en web. El patrón sería el siguiente:

# Ignora los ficheros .html que están en subcarpetas de la carpeta web
# No ignora los ficheros web/*.html
#
# Con este patrón, el fichero web/fichero.html se incluirá en el repositorio
# mientras que ficheros con web/admin/fichero.html o web/images/ se 
# ignorarán
web/**/*.html

Otra pregunta: Este patrón ¿ignora el fichero web/admin/subcarpeta/fichero.txt?

Rutas relativas

Un patrón que comienza por » / «, indica que para decidir si el fichero se ignora o no, se utiliza una ruta relativa al fichero .gitignore:

# Ignora los fichero *.c en la carpeta raiz del proyecto: memory.c
# No ignora los ficheros en subcarpetas como modules/cache.c
/*.c

Conclusiones

En esta entrega hemos visto cómo interpreta git los patrones glob shell y los patrones a rutas relativas. En la siguiente entrega veremos cómo podemos usar múltiples ficheros .gitignore. Estos nos ayudarán a salvar las limitaciones que tenemos a la hora de trabajar con múltiples subcarpetas.

Respuestas:

1. Efectivamente, el patrón «bg-*.jpg» ignora que fichero «bg-.jpg». Eso es porque a diferencia de símobol «?», el símbolo «*» se corresponde con cualquier número de caracteres, incluido cero caracteres.
2. El patrón web/**/*.html no ignora el fichero web/admin/subcarpeta/fichero.txt. Dado que se usa el parámetro FNM_PATHNAME, el » ** » no incluye el caracter » / » y por lo tanto este patrón sólo incluye las carpetas que son hijos de web, no incluye los nietos y niveles de más profundidad en la jerarquía de carpetas.

Comentarios y líneas en blanco

Podemos hacer nuestro fichero más legible si incluimos comentarios y separadores:

• Cualquier línea que comience por # es un comentario
• Una línea en blanco no se considera un patrón por parte de git, por lo que puede ser usada como un separador

Sé considerado con el resto de los miembros del equipo y comenta adecuadamente cada uno de los patrones que utilices. Indica el porqué de ese patrón de forma que el resto de compañeros o colaboradores sepan porqué has decidido en un momento dado ignorar ciertos ficheros. Y una cosa más, no todo el mundo usa las mismas herramientas que tú ni tiene tu mismo nivel de conocimientos en determinadas materias así que piensa un poco en los demás y ayúdales:

# Jetbrains IDEs: PHPStorm / RubyMine  
# (No todo el mundo tiene que saber que los ficheros .idea son de un 
# entorno de desarrollo)
.idea 

# Ficheros de documentación sphynx. Puedes generar tu copia local de la doc
# en /doc/build utilizando los scripts sphynx en /doc
/doc/build/

Negación

Utilizando el carácter ! podemos invertir un patrón ¿Qué significa invertir un patrón? Veamoslo con un ejemplo:

# Incluir expresamente en el repositorio todos los ficheros con extensión php
!*.php

¿Porqué podemos necesitar este tipo de patrones? Imagina que estás trabajando en un proyecto en PHP; como te puedes imaginar, si tu repositorio sólo tuviese estas dos líneas en los ficheros git/info/exclude, .ignore y .gitignore_local podríamos quitarlas ya que el efecto sería el mismo. Ahora bien ¿para qué podemos necesitar un patrón como este?:

• Tal y como vimos en la anterior entrega, para invertir patrones de menor prioridad
• Crear excepciones a patrones muy restrictivos

Veamos un ejemplo del segundo caso. Siguiendo con el ejemplo de un proyecto en PHP, podemos eliminar la línea anterior ya que no hace falta. Ahora bien ¿qué hacemos con los ficheros html?:

# Ignorar todos los ficheros .html...
*.html

 #... excepto en la carpeta web
!web/*.html

En este caso, cualquier fichero con extensión .html en cualquier carpeta se ignorará, excepto los ficheros que estén en la carpeta web. Cuidado porque ficheros .html que estén en una subcarpeta de web, como por ejemplo web/archive, también se ignorarán. Más adelante veremos porqué.

Ignorando carpetas enteras

Si un patrón acaba con una barra /, git ignorará cualquier fichero dentro de esa carpeta:

# Ignorar el contenido de las carpetas log y cache
cache/
log/

Git ignorará cualquier fichero que esté dentro de cache/ o log/ o en cualquier subcarpeta que cuelgue de ellas.

Este patrón no se lleva muy bien con la negación ¿Por qué decimos esto? Imagina que quieres ignorar el contenido de la carpeta web entera (incluyendo todas las subcarpetas que cuelgan de ella) excepto el fichero web/index.php. Con lo que sabemos hasta ahora, intentaríamos una combinación de patrones como la siguiente:

#Esto no funciona:
# git ignorará también el fichero index.php
web/
!web/index.php

Desafortunadamente esto no funciona y git ignorará fichero index.php. Veremos en una futura entrega cómo resolver este problema.

Una última nota sobre el uso de /. Si usamos el siguiente patrón

#Ignorar el contenido de la carpeta web
web/

y web no es una carpeta sino un enlace simbólico o un fichero regular:

total 16
-rw-r--r-- 1 aalba staff 0 22 dic 14:42 Alumno.php
-rw-r--r-- 1 aalba staff 0 22 dic 14:41 Curso.php
-rw-r--r-- 1 aalba staff 0 22 dic 14:42 Licencia.php
-rw-r--r-- 1 aalba staff 339 7 dic 16:39 README.md
drwxr-xr-x 3 aalba staff 238 29 dic 08:29 builds
lrwxr-xr-x 1 aalba staff 11 29 dic 08:29 web -> builds/html

¡el fichero no se ignora!

$ git status
# On branch master
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# web
  ^^^ -> el enlace simbólico o fichero regular no se ignora ya que el patrón
         web/ sólo se aplica a carpetas

Esto es todo por hoy, en la siguiente entrega de la serie veremos los patrones shell que podemos utilizar.

¿Porqué carpetas vacías?

Hay muchas herramientas, aplicaciones y frameworks que requieren de la existencia de ciertas carpetas para funcionar. Un ejemplo: tanto Symfony como Ruby on Rails necesitan disponer de directorios en los que almacenar cachés y logs. El contenido de estas carpetas se ignora siempre del repositorio; son archivos locales que sólo tienen sentido en cada copia local ¿pará que queremos distribuir a nuestros compañeros de trabajo los archivos de log creados por nuestro portátil mientras estamos desarrollando la aplicación? Es un derroche inútil de recursos y una fuente de conflictos que nos quitará mucho tiempo y no nos aportará nada.

El problema que se deriva de esto es que si ignoramos toda la carpeta completa utilizando un patrón de este tipo:

#Ignorando cache y log
cache/
log/

cuando otra persona clone el repositorio esas carpetas no se crearán. A no ser que las cree manualmente, la aplicación no funcionará.

La solución es decirle a git que cree las carpetas cuando clone el repositorio y luego que ignore su contenido. ¿Cómo se hace? creamos un fichero vacío dentro de la carpeta, lo añadimos al repositorio y le decimos a git que ignore el resto de archivos que están dentro. Esto se puede hacer de dos maneras:

• A través de un fichero .gitkeep
• A través de un fichero .gitignore

.gitkeep

Lo primero que debemos tener claro es que el uso del fichero .gitkeep es un convenio. En ningún lugar de la documentación de git veréis que se haga referencia a este fichero. De hecho, si no os gusta el nombre nada os impide cambiarlo y usar cualquier otro.

Veamos cómo usar este fichero:

• Antes de añadir al fichero .gitignore el patrón que ignore la carpeta cache, creamos el fichero cache/.gitkeep, bien usando el comando touch o con nuestro editor de texto o entorno de desarrollo.

# touch cache/.gitkeep

• Una vez creado el fichero lo añadimos al repositorio y hacemos el commit:

# git add cache/.gitkeep 
# git commit -m'Añadiendo el fichero cache/.gitkeep

• Editamos el fichero .gitignore (o lo creamos si no existe) y añadimos el patrón para ignorar la carpeta cache:

# Ignorando los ficheros de la carpeta cache/
cache/

•  Hacemos commit del fichero .gitignore

Ya está, la próxima vez que alguien cree el repositorio, se creará el fichero cache/.gitkeep a la vez que se ignora cualquier otro fichero que esté en la carpeta cache/.

Esta técnica utiliza la siguiente característica de git: si un fichero ya está en el índice (es decir, git ya está haciendo seguimiento de las modificaciones de ese fichero) a pesar de que el .gitignore lo ignore, git lo seguirá monitorizando.

Utilizar un fichero .gitignore

El método anterior tiene una pega: tenemos patrones para ignorar ficheros que requieren que tengamos varias excepciones en el índice de git (cache/.gitkeep, log/.gitkeep, etc). No hay problema con ello, aunque si no os gusta podemos utilizar otra de las características de git para no tener excepciones en el índice: utilizar un fichero .gitignore dentro de la carpeta que queremos ignorar.

• Crear el fichero cache/.gitignore con los siguientes patrones

# Ignorar todos los ficheros...
*

# ...excepto el fichero .gitignore
!.gitignore

• Añadir el fichero cache/.gitignore al repositorio y hacer un commit

Si repetís esta operación con las carpetas cuyos ficheros queráis ignorar, no tendréis necesidad de andar incluyendo excepciones en el índice.

Cualquiera de los dos métodos nos permite tener carpetas «vacías» en el repositorio, aunque vacías, vacías del todo no lo están. ¿Qué método usáis vosotros normalmente? ¡Esperamos vuestros comentarios!

¡Happy gitting!

En cualquier proyecto, existen ficheros que no deben incluirse en el repositorio. Por nombrar algunos de ellos:

• Ficheros de log
• Cachés
• Ficheros que contienen claves privadas (App keys y App secrets) para acceder a las API o servicios web
• Ficheros de configuración con contraseñas de bases de datos
• Ficheros binarios compilados
• Ficheros de configuración del entorno de desarrollo

Cuando empiezas a utilizar git, tardas muy poco en preguntarte cómo puedes evitar subir estos ficheros al repositorio. Si buscas la respuesta en google, encontrarás en todos sitios que lo que tienes que hacer es crear un fichero .gitignore que hay que subir al repositorio o crear un fichero .git/info/exclude para poner las reglas locales. Tú lo creas y entonces empiezan las preguntas: ¿Y cuál de los dos tiene preferencia? ¿Y porqué lo tengo que incluir en el repositorio?  ¿Y porqué subo uno sí y otro no? ¿Un fichero, no son propiedades como en subversion? ¿Y si yo quiero usar un .gitignore y el resto del mundo otro?

Para responder a estas preguntas debemos platearnos la pregunta adecuada que es…

¿Cómo decide git qué ficheros incluir o no en el repositorio?

La respuesta a esta pregunta está en la página de manual de gitignore. Por orden de prioridad, git busca patrones para excluir ficheros en los siguientes lugares:

1. En la línea de comandos: ciertos comandos, como por ejemplo git ls-files o git read-tree, permiten excluir ficheros a través de argumentos. Estos patrones tendrán la máxima prioridad.
2. En los ficheros .gitignore
3. En el fichero $GIT_DIR/info/exclude
4. En el fichero definido en la variable de configuración core.excludesfile

*.jar

git ignorará cualquier fichero con extensión .jar en cualquier directorio.

¿Qué quiere decir que git ignora ficheros?

Veamos qué ocurre cuando ignoramos un fichero en un repositorio. Imagina que acabas de empaquetar tu aplicación PHP en un fichero .phar en la carpeta builds. Esto es lo que veríamos en SourceTree:

Si no hacemos nada, tendremos que acordarnos siempre de no incluir este fichero al hacer commit. Esto es peligroso, ya que si alguna vez tenemos muchos ficheros pendientes de añadir o excluir del commit, puede que se nos «cuele» mynewapp.phar sin darnos cuenta.

Para evitar el estar pendiente de subir o no estos ficheros, usamos un editor de texto y abrimos el fichero .git/info/exclude de nuestro repositorio. Añadimos el siguiente patrón al final del fichero:

*.phar

Cuando volvamos al SourceTree, veremos que el fichero ya no está:

Ya está, ya estamos tranquilos: no añadiremos por accidente el fichero al repositorio.

Seguro que os estaréis preguntando: «¿Porqué no lo ha puesto en .gitignore, como dice nuestro gran San Google?». A lo largo de la serie veremos si poner este patrón en el fichero .git/info/exclude es la mejor opción o conviene ponerlo en otro lugar. De momento lo dejaremos así.

Esto ha sido todo por hoy. En la siguiente entrega veremos qué patrones incluir en cada uno de los tres métodos que podemos utilizar y cómo trabajar con el orden de prioridades descrito anteriormente.

Bromas aparte, la funcionalidad puede parecer una tontería, pero bien utilizada es bastante útil. A modo de ejemplo, la vamos a utilizar en un caso real para crear un fichero README.md en un repositorio que no lo tiene.

Si lo tuviese que hacer por el procedimiento normal, tendría que hacer lo siguiente:

• Crear el fichero README.md en mi copia local
• git add README.md para añadir el fichero al índice
• git commit -m’Añadiendo README.md’ para hacer el commit
• git pull para bajarme a mi copia local las últimas modificaciones
• Si en el último paso ha habido algún conflicto, tendríamos que resolverlo (si habéis usado bien las ramas, esto no pasará)
• git push para subir los cambios

La verdad es que es bastante trabajo para subir un fichero de texto ¿verdad? Bueno, pues vamos a ver cómo lo hacemos desde la web.

En primer lugar, vamos a la página de github, accedemos con nuestro usuario y contraseña y vamos a la página de nuestro repositorio:

En la captura anterior veis dónde está el botón. Hacemos clic sobre él y se nos abrirá la pantalla para crear el fichero:

La pantalla no tiene mucho misterio, como podéis ver en la captura:

• Seleccionamos en qué rama lo queremos crear
• Introducimos el nombre y extensión del fichero
• Ponemos el contenido
• Rellenamos el mensaje para el commit (el resumen es obligatorio)

Una vez tenemos el fichero escrito, hacemos clic sobre «Commit New File» y si no se produce ningún error, volveremos a la pantalla del repositorio con algunos cambios:

• El fichero ya lo tenemos en el repositorio
• Hay un commit más en el repositorio

Pues ya está. Para obtener el fichero en nuestra copia local, hacemos un pull de la rama en la que hemos subido el fichero. Como veis, es un poquito más cómodo que el método normal y nos puede ahorrar tiempo en ciertas tareas.

¿Cuándo conviene usar esta funcionalidad de github?

Como pone en la propia entrada del blog en github, es un método pensado para ficheros como el README, LICENSE, el .gitignore o escribir documentación. Usa el sentido común y sé práctico. Yo, por ejemplo, lo he usado para crear un fichero sencillo con datos de prueba en json y pasárselo a mis compañeros desde el iPad en el sofá o para crear un fichero sencillo con traducciones en formato CSV.

Creando .gitignore desde plantillas

Los chicos de github están en todo, así que para ahorrarnos un poco de trabajo han creado una serie de plantillas para crear ficheros .gitignore. Para verlas y seleccionarlas, creamos un nuevo fichero como hemos visto antes y en el nombre del mismo escribimos «.gitignore»:

Cuando lo hagamos, veremos a la derecha un desplegable para seleccionar la plantilla. La seleccionamos y ya podemos editar el fichero, quitando reglas o añadiendo las que puedan faltar. Al terminar, no nos olvidamos de hacer clic sobre «Commit New File».

¿Y si el repositorio no es mío?

Si intentas crea un fichero sobre un repositorio sobre el que no tienes permiso, verás el siguiente mensaje:

Lo que nos está diciendo es que antes de crear el fichero va a hacer un fork del repositorio en nuestra cuenta y que el fichero será creado en el nuevo repositorio. Una vez creado, podemos hacer un pull request al administrador del repositorio original para que incorpore el nuevo fichero en su repositorio.

Básicamente sigue los siguientes pasos:

• Crea e inicializa un repositorio git en la carpeta raíz del proyecto
• Añade todos los ficheros al repositorio excepto las carpetas [nombre].xcodeproj/project.xcworkspace y [nombre].xcodeproj/xcuserdata/
• Hace un commit con el comentario «Initial Commit»

Para ver en qué estado ha quedado el repositorio vamos a seguir los siguientes pasos:

• Creamos proyecto nuevo en XCode, cualquiera de las plantillas que vienen por defecto nos vale (tanto de iOS como de Mac)
• Abrimos SourceTree
• En la ventana «bookmarks» hacemos clic sobre el icono para añadir repositorio

• A continuación seleccionamos «Add working copy», ya que XCode ya ha inicializado el repositorio por nosotros. En el campo «Working copy path» buscamos la carpeta en la que está nuestro proyecto e introducimos un alias campo «»Bookmark Name» si el que crea SourceTree no nos gusta. Hacemos clic sobre «Add» cuando hayamos terminado