.gitkeep – Incluyendo carpetas en los repositorios

¿Has visto esos ficheros .gitkeep que Ruby on Rails crea cuando generas un proyecto nuevo? ¿por qué están ahí? Git sólo gestiona ficheros, no carpetas. Esto es así por la forma en la que el índice (o staging area) de git se ha diseñado: sencillamente no lo permite. Tal y como se dice en la FAQ, nadie lo suficientemente competente se ha ocupado de implementar el soporte para carpetas. Aún así, nos encontraremos con que en muchas ocasiones nos vendría muy bien poder añadir carpetas vacías al repositorio.

¿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:
Añadiendo .gitkeep al repositorio con Bitbucket
# 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!

Ignorando ficheros en git – Parte II: Prioridades

En la entrega anterior de esta serie, vimos las cuatro formas en las que podemos ignorar ciertos ficheros de forma que no se incluyan en nuestros repositorios.

En este artículo vamos a ver en qué orden se aplican estas cuatro maneras de leer los patrones y qué ocurre cuando en ellos tenemos patrones contradictorios.

Patrones contradictorios

Supongamos que tenemos los siguientes patrones en los ficheros exclude y .gitignore:

#.git/info/exclude
*.phar
*.p
#.gitignore
!*.php

Estos patrones son contradictorios ya que en el primer caso estamos ignorando los ficheros con extensión .php y en el segundo estamos diciendo que no se ignoren (ese es el significado del signo de exclamación «!» inicial en el patrón).

¿Qué va a pasar? Dado que el fichero .gitignore tiene prioridad sobre el fichero .git/info/exclude, los ficheros se incluirán en el repositorio. Si abrimos SourceTree en nuestro proyecto veremos lo siguiente:

Reglas contradictorias I

La regla es que git revisa por orden la línea de comandos, el fichero .gitignore, el fichero exclude y  el fichero indicado por core.excludesfile. El primero último de ellos que contenga un patrón que explícitamente ignore o no un fichero dado, es el que aplica.

¿Qué pasa si dentro de un mismo fichero existen reglas contradictorias? Imagínate un fichero .gitignore como el siguiente:

# .gitignore
!*.php

# Otros patrones
....

# Un compañero de equipo añade días después la siguiente regla
*.php

Git utiliza la última regla, por lo que los ficheros se ignoran y no podríamos añadirlos al repositorio:Patrones contradictorios en .gitignore

.git/info/exclude vs .gitignore vs core.excludesfile

Entendido cómo funciona el orden de prioridades ¿qué patrones ponemos en cada una de las tres opciones que nos da git?

  • En .gitignore pondremos aquellos patrones que queremos que sean iguales en todos los clones que existen del repositorio. Todos los miembros del equipo los comparten. Es por ello que este fichero debe incluirse en el repositorio. Este es un buen lugar para ignorar ficheros de log y cache, configuraciones, claves privadas, etc.
  • En .git/info/exclude se incluyen patrones que se van a aplicar sólo a nuestra copia local y no se van a distribuir al resto de miembros del equipo. Este fichero es útil cuando por ejemplo, creas una rama local para desarrollar una determinada característica de la aplicación, y necesitas ignorar ciertos ficheros sin que el resto del equipo se vea afectado por ello.
  • En el fichero indicado por la variable core.excludesfile, incluimos aquellos patrones que queremos ignorar de forma global en todos los repositorios. Este es un lugar para incluir los ficheros del proyecto generados por nuestro entorno de desarrollo. Por ejemplo, si estamos trabajando con PHPStorm o RubyMine, incluiríamos el siguiente patrón:
.idea/

Para saber qué fichero es el que se indica en la variable core.excludesfile, usamos el comando git-config:

# git config --get core.excludesfile
/home/myuser/.gitignore_global

Si queremos modificar la ruta al fichero utilizamos la opción –global del comando git-config:

# git config --global core.excludesfile /home/myser/myconfig/mygitignore
# git config --get core.excludesfile
/home/myuser/myconfig/mygitignore

Por una cuestión de comodidad, denominaremos de ahora en adelante este fichero como .gitignore_global, entendiendo que modificando esta opción de configuración, este fichero puede tener otro nombre y estar en una ruta diferente.

¿Conviene incluir en el repositorio los ficheros de configuración del entorno de desarrollo?

Una conversación que he tenido ya en varias ocasiones con diferentes personas es si conviene o no incluir en el fichero .gitignore los ficheros de configuración del entorno de desarrollo, ya sea Eclipse, Netbeans, PHPStorm o cualquier otro.

Mi política es la siguiente:

  • Si estás trabajando en un proyecto de software libre en el que puede participar cualquier persona, tendrías que incluir en el fichero todos y cada uno de los posibles IDE que los colaboradores utilicen. Esto complica el fichero innecesariamente y dificulta su mantenimiento. ¿Cuántos IDE o editores de texto diferentes utilizan todos los colaboradores de un proyecto? En este caso, lo mejor es que cada colaborador se responsabilice de configurar su fichero .git/info/exclude o .gitignore_global adecuadamente.
  • Si estás trabajando en un equipo en el que todos sus miembros utilizan el mismo entorno de desarrollo, entonces sí que incluyo los ficheros del IDE en el fichero .gitignore. El motivo es que no usamos más de dos o tres IDE diferentes que se pueden gestionar fácilmente con 3 o 4 patrones en el fichero .gitignore.

De cara a trabajar con gente novata en git dentro del equipo, la mejor opción es la segunda. El motivo es que no necesitan hacer nada una vez clonan el repositorio para ignorar los ficheros del entorno de desarrollo. Así les facilitamos un poco el trabajo al principio.

Esto es todo por hoy. En la siguiente entrega veremos los diferentes patrones que podemos utilizar para ignorar ficheros.

Ignorando ficheros en git – Parte I: Formas de ignorar ficheros

En esta serie vamos a profundizar un poco más en el fichero .gitignore, para qué sirve y cómo podemos usarlo, empezando por cómo decide git si ignorar un fichero o no.

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
Todos los ficheros mencionados arriba incluyen en su interior un conjunto de patrones de ficheros que se van a ignorar. Cada patrón va en una línea. Por ejemplo, si incluimos la siguiente línea en alguno de estos ficheros:
*.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:Fichero phar marcado como untracked

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á:SourceTree después de ignorar *.phar

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.

Prestashop empieza a utilizar github

Hace unos días, concretamente el pasado día 11, prestashop anunció que había había empezado su actividad en github. La cuenta se ha creado recientemente, el 16 de noviembre y un vistazo al repositorio muestra que a fecha de hoy ya tienen nada más y nada menos que 107 forks ¡y no ha pasado ni un mes! Si miráis los pull requests, también se observa bastante actividad con 74 pull requests cerrados en y 16 abiertos.

Es curioso que en la página para descarga de la versión de desarrollo permanecen todavía los enlaces a los repositorios de subversion ¿seguirán manteniendo los dos repositorios? ¿están todavía pensándose el volver a subversion en lugar de seguir con github o sencillamente no han tenido tiempo de cambiar la web 🙂 ?

Estaría muy bien que hiciesen estadísticas sobre el número personas diferentes que contribuye al proyecto antes y después de esta migración. Me aventuro a decir que la diferencia será significativa.

Otro grande que empieza a usar git ¿y tú todavía te lo estás pensando?

Crear ficheros en repositorios github a través de la web

Recientemente, github ha añadido una nueva funcionalidad a sus usuarios través de la web: la posibilidad de añadir ficheros directamente al repositorio a través del navegador. ¿Significa esto que podremos programar nuestra próxima aplicación usando la web de github? Pues no, aunque para gustos los colores.

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:

Creando ficheros desde github

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:

Pantalla para crear un fichero en github

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

Tras subir el fichero

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»:

Creando un .gitignore desde plantilla

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:

Creando fichero sobre repositorio sin permiso de escritura

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.

.gitignore en XCode

Cuando creamos un proyecto nuevo en XCode y marcamos la opción para que utilice el control de versiones, ¿qué está haciendo XCode por debajo?

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ñadiendo repositorio de XCode a SourceTree paso 1

  • 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

Añadiendo repositorio XCode a SourceTree paso 2

  • Cuando se cierre la ventana y volvamos al listado de repositorios de SourceTree, hacemos doble clic sobre el repositorio que acabamos de crear

Los ficheros que XCode no incluye

Cuando git crea el repositorio, añade el siguiente contenido al fichero .git/info/exclude

.DS_Store
UserInterface.xcuserstate

Este fichero, a diferencia de .gitignore, contiene reglas que se aplican sólo a nuestro repositorio local (si compartimos el repositorio con otros usuarios a través de github o bitbucket, no verán estas reglas).

Aparte de estas dos reglas, ¿qué más no ha incluido XCode en el repositorio nada más crearlo?

Si no habéis abierto todavía el repositorio en SourceTree (haced doble clic sobre él en la ventana de Bookmarks) hacedlo ahora. A la izquierda haced clic sobre la rama master, veréis que en la sección «Files in the working tree» nos aparecen los ficheros que XCode no ha añadido al repositorio:

Ficheros nos incluidos por XCode en el repositorio

Si os fijáis, estos ficheros no están incluidos y no se están ignorando. Eso significa que cualquiera podría añadirlos al repositorio en cualquier momento, veamos cómo.

Dejemos la ventana del SourceTree como está (luego volveremos a ella) y volvamos a XCode para modificar alguno de los ficheros (como si estuviésemos trabajando en algo serio). Una vez modificado, vamos a Archivo -> Source Control -> Commit (u OPCIÓN-CMD-C) para acceder a la pantalla para enviar un commit:

Commit desde XCode

Como podemos ver, en la parte de arriba a la izquierda tenemos los ficheros que no están incluidos inicialmente en el repositorio, y que son los mismos que hemos visto con SourceTree. Si los marcáis junto a los otros tres ficheros que he modificado, los añadiríamos al repositorio.

La pregunta es…

¿Deben estar los «Workspace Settings» y «User Data» en el repositorio?

«Workspace Settings» contiene información relacionada con los proyectos, así que a no ser que sea algo que estrictamente sólo vamos a usar nosotros, conviene incluirlo en el repositorio.

Sin embargo, la carpeta «User Data» que contiene la configuración propia de nuestro usuario, sí conviene ignorarla ya que si no lo hacemos y trabajamos con otras personas, vamos a encontrarnos constantemente con conflictos difíciles de resolver sobre el IDE, no sobre el proyecto en sí.

Para ignorar estos ficheros, abrimos un editor de textos cualquiera y dentro de la raíz del proyecto creamos un fichero de texto plano al que llamaremos «.gitignore» (no os olvidéis del «punto» delante del nombre del fichero) y añadimos las siguientes líneas:

.DS_Store
UserInterface.xcuserstate
xcuserdata

  • Las dos primeras reglas son el mismo contenido que teníamos en .git/info/exclude. Las ponemos aquí para asegurarnos de que todo el mundo que se descargue el repositorio ignora estos ficheros
  • La tercera línea es la que ignora las preferencias de usuario

Una vez creado el fichero, volvemos a la pantalla de commit del XCode y veremos lo siguiente:

Ignorando User Data

¡Ya no podemos enviar la carpeta «User Data» por error!. Marcamos la carpeta «Workspace Settings» junto al resto de ficheros y hacemos el commit.

¿Ya está?

No, todavía no. Cuando he creado el fichero .gitignore, no lo he creado usando XCode así que si habéis hecho los commits desde XCode como yo, el fichero .gitignore no está incluido en el repositorio. ¿No me crees? Vuelve a la ventana del SourceTree que hemos dejado olvidada hace unos minutos y verás:

Añadiendo .gitignore al repositorio

Efectivamente, no está incluido. En otro post os contaré porqué necesitamos incluirlo; para no desviarnos del tema de esta entrada, vamos a incluirlo arrastrándolo al área «Files staged in the index» y haciendo clic sobre «Commit».

(Nota: si preferís añadir el fichero por línea de comandos os resumo los pasos. Abrís una terminal, vais a la carpeta raíz del proyecto de XCode, ejecutáis «git add .gitignore» y luego ejecutáis «git commit -m’Añadiendo .gitignore’ «)

Ahora sí, ya tenemos la versión más sencilla del fichero .gitignore.

¿La versión más sencilla? ¿…es que faltan más cosas?

Sí, en función del proyecto en el que estéis trabajando podéis necesitar no incluir otros ficheros como .nib, clases obsoletas, etc. La comunidad ha generado ya un fichero de reglas estándar que podéis consultar en Stack Overflow, y que copio un poco más abajo para que las tengáis a mano.

¿Usáis vosotros alguna regla que no esté en este fichero? ¿Cuáles son las reglas que utilizáis normalmente? Compartid vuestro .gitignore como un gist en github y poned aquí el enlace. ¡Compartir es vivir!

Could not embed GitHub Gist 4260145: Not Found
.

¡Happy gitting!

Creando nuestro primer repositorio en Bitbucket – Parte II: Subiendo el primer fichero

En la primera parte de esta serie vimos cómo crear en bitbucket nuestro primer repositorio. Partiendo este punto, en esta entrada veremos cómo:

  • Subir el código fuente al repositorio
  • Crear un fichero README con información sobre el repositorio
  • Enviar el fichero README a Bitbucket mediante push

Paso 1: Clonar el respositorio en nuestro ordenador

Lo primero que tenemos que hacer, una vez creado el repositorio en bitbucket, es clonar el repositorio en nuestra máquina. Si estáis trabajando con un Mac, como es mi caso, y habéis instalado previamente SourceTree, podéis hacer clic en la parte superior derecha derecha en el botón «Clone» y posteriormente sobre el botón «Clone in SourceTree».

Clonar el repositorio en SourceTree

Cuando hagáis clic sobre el botón, se abrirá la aplicación y nos pedirá que seleccionemos una ruta en la que guardar el repositorio y un nombre corte (Bookmark Name) para localizarla rápidamente en el listado de repositorios de SourceTree:

Clonar repositorio en SourceTree

Una vez le demos al botón «Clone», SourceTree nos mostrará el repositorio en el listado:

Repositorio en SourceTree

Si todo ha ido bien, ya estamos listos para dar el siguiente paso.

Paso 2: Crear el fichero README

Siempre que trabajemos con Bitbucket o github, es muy conveniente tener un fichero README en la raíz de nuestro repositorio, así que vamos a crearlo.

Lo primero y muy importante es que SourceTree no es un editor de código, tampoco es un IDE, es decir, no nos sirve para modificar el contenido de los ficheros:

  • Cuando programes tus tests y clases, ajustes tus ficheros de configuración o maquetes la nueva versión de la web, seguirás usando tu editor o IDE favorito para hacer tu trabajo
  • Cuando tus tests estén todos en verde, hayas terminado una una versión de tu página HTML, o tengas la configuración adecuada de tu sistema, cambiaremos a SourceTree para guardar en el repositorio el trabajo que hemos realizado [1]

Vamos a la carpeta en la que hemos clonado el repositorio y creamos un fichero README.md con el siguiente contenido:

Una vez creado el fichero, dejamos el IDE o editor de texto que hayamos utilizado y volvemos a SourceTree. En la pantalla principal, abrimos el repositorio que acabamos de crear haciendo doble clic sobre él en el listado. Al hacerlo, se nos abrirá una pantalla similar a la que se muestra a continuación:

El nuevo fichero README.md en el área de trabajo

En el área de trabajo, situada en la parte inferior, vemos el fichero README.md que acabamos de crear. ¡Ha llegado el momento de subirlo a Bitbucket!

Paso 3: Subir el fichero a Bitbucket

Para hacerlo, seleccionamos el fichero README.md en el área de trabajo y le damos al botón «Add» que tenemos en el menú superior. También podemos arrastrarlo a la sección «Files staged in the index» que está justo encima:

Añadir fichero al staging area

Una vez tenemos el fichero en el área de ensayo (staging area) hacemos un commit presionando el botón «Commit» de la barra de herramientas. Se abrirá la siguiente ventana en la que debemos escribir un mensaje que describa qué hemos hecho. En este caso es sencillo: «Añadiendo el fichero README.md»:

Haciendo un commit desde SourceTree

Cuando terminemos, presionamos el botón «Commit». Al cerrase la ventana, fíjate que a la izquierda, en la sección «Branches» nos aparece una nueva rama que SourceTree por defecto ha llamado «master»:Pantalla tras hacer commit del fichero README.md

El último paso es enviar el commit a Bitbucket. Presionamos el icono Push en la barra de herramientas, en la ventana emergente seleccionamos la rama local master y a continuación presionamos OK:

Haciendo pull desde SourceTree

Nos pedirá la contraseña de nuestro usuario de Bitbucket, la introducimos y presionamos «Aceptar». Si tenemos conexión de red y no nos hemos equivocado al poner la contraseña, la ventana emergente se cerrará y volveremos a la pantalla del repositorio. Si se produce algún error, SourceTree nos avisará y nos mostrará el mensaje que git ha generado.

Pues ya está, si no nos ha avisado SourceTree de que algo ha ido mal, significará que nuestro commit ha sido correctamente enviado al repositorio remoto. Volvemos al navegador web y recargamos la página del repositorio, que tendrá un aspecto similar a este:

Página de inicio del repositorio no vacío en bitbucket

donde vemos cómo Bitbucket nos muestra el contenido del fichero README.md, la actividad reciente del repositorio y la información general del repositorio en la parte derecha.

Esto es todo, ya hemos subido el primer fichero y tenemos el repositorio listo para empezar a trabajar en nuestro proyecto. Si tenéis consultas, preguntas o comentarios sobre este procedimiento, no dudéis en preguntarnos.

————-

[1] Este tener que cambiar del IDE al SourceTree y del SourceTree al IDE no siempre es necesario: a día de hoy casi cualquier entorno de desarrollo dispone de módulos de integración con sistemas de gestión de código. Con estos módulos es posible hacer el commit y el push que hemos hecho en este artículo sin necesidad de abandonar el IDE.

 

¿Por qué se necesita un fichero README en la raíz de un repositorio git?

El objetivo de este fichero es facilitar una guía rápida a los que acaban de descubrir nuestra aplicación, API o librería de cómo empezar a usarla. Es muy importante que vaya al grano, sea conciso y muy claro. Para extendernos y entrar en detalles está la documentación, a la que siempre podemos enlazar desde dentro de nuestro README.

Servicios como Github o Bitbucket disponen de una interfaz web para navegar por los repositorios git, ver el código fuente, ver la historia y hacer pull requests entre otras muchas opciones. Estos servicios han adoptado el convenio de mostrar en la página web de inicio del repositorio el contenido de este fichero.

¿Y si no trabajo con github ni bitbucket?

También debes tenerlo. Si trabajas tú sólo, para que te ayude a refrescar la memoria cuando pase el tiempo; y si trabajas con otras personas, para que cuando clonen el repositorio git sepan qué hacer.

¿Qué formatos soporta?

El fichero README puede ser redactado en diferentes formatos, el más sencillo de ellos es texto plano (.txt). Tanto Github como Bitbucket ofrecen un servicio adicional, y es que si el fichero está escrito en ciertos formatos, se convertirá a HTML y se mostrará bastante más legible en la web.

Aunque el formato más extendido es markdown, ambos servicios soportan diversos formatos:

¿Qué significa clonar un repositorio?

Clonar un repositorio significa bajarse una copia completa del mismo a nuestro a ordenador. ¿Y qué quiere decir una copia completa, os preguntaréis? Pues significa que después de clonar un repositorio tendréis en vuestro ordenador toda la historia del repositorio, completa.

En consecuencia, podréis:

  • Navegar por la historia del proyecto, viendo cómo ha evolucionado
  • Ver los cambios que han ocurrido en el código
  • Saber quién y cuándo ha modificado cada cosa
  • Acceder a las ramas del proyecto y crear las vuestras propias
  • Empezar a modificar el código, guardar los cambios y añadir vuestro trabajo al que ya existe

Y todo esto sin necesidad de estar conectados a internet. Sólo necesitaremos conexión a internet cuando queramos «compartir» nuestro trabajo con alguien más o queramos subir nuestro trabajo a un servicio como bitbucket o github.

Esta es una de las preguntas más habituales que nos hacéis en el curso casi antes de empezarlo.

Creando nuestro primer repositorio en Bitbucket – Parte I: registro y creación del repositorio

En este artículo, primero de una serie de dos, vamos a ver cuáles son los pasos para crear nuestro primer repositorio en bitbucket, clonarlo en nuestra máquina de trabajo y subir nuestro código fuente.

Paso 1 – Registrándonos en Bitbucket

Si ya dispones de una cuenta, puedes pasar directamente al siguiente paso. Lo primero que haremos será acceder a la página de registro y completar el formulario que nos aparece en pantalla:

  • El nombre de usuario que escojas es el que te identificará en la aplicación. Cualquier actividad que realices en Bitbucket, tanto pública como privada, mostrará este nombre de usuario como un enlace a tu perfil.
  • Como lo que queremos es crear nuestra cuenta de usuario personal, vamos a seleccionar «Individual». En unaentrada posterior veremos cómo trabajar con equipos (teams).
  • Si ya dispones de una cuenta en OpenID, puedes utilizarla para crear la cuenta de Bitbucket empleando el enlace que te aparece en la parte superior derecha del formulario.

Sigamos con el proceso de registro normal rellenando el formulario y enviándolo, haciendo clic en SignUp. Cuando lo hagamos, ocurrirán dos cosas:

  • Se nos remitirá un correo electrónico para confirmar nuestra cuenta, cosa que deberemos hacer para acceder a toda la funcionalidad de Bitbucekt
  • El sistema nos logeará automáticamente, presentándonos la pantalla de bienvenida

Paso 2 – Creando el repositorio

Este es un buen momento para, antes de seguir, revisar nuestro correo y confirmar la cuenta que hemos utilizado. Una vez lo hagamos, volvemos a esta pantalla en la que haremos clic sobre el botón «Create your first repository»

Atajo para crear nuestro primer repositorio

A continuación, se nos mostrará el formulario para crear nuestro primer repositorio:

Creando nuestro primer repositorio

En este formulario es importante ajustar las siguientes opciones:

  • Darle un nombre al repositorio, así como una descripción. Esta descripción se mostrará en la página del repositorio. Conviene escribir un texto conciso y breve. Luego podremos crear un fichero README con información más detallada.
  • Quitar la casilla «Access Level» si queremos que nuestro repositorio sea público, lo que significa que cualquier usuario, registrado o no, podrá ver el contenido. Esta opción se puede cambiar a posteriori.
  • Marcar Git como tipo de repositorio
  • Activar la gestión de tickets (Issue tracking) y la Wiki, si es que queremos utilizar estas secciones en nuestro proyecto
  • Seleccionar el lenguaje de programación

Rellenados todos los campos, hacemos clic sobre el botón «Create repository» y se nos mostrará la siguiente pantalla:

Pizarra del repositorio

Ya tenemos todo listo para empezar a trabajar con nuestro repositorio en nuestro ordenador. En la siguiente entrega veremos cómo subir nuestro código al repositorio que acabamos de crear.

Con respecto a la pizarra, veremos en posteriores entradas qué son los botones de Clone o Fork así como qué herramientas nos facilita Bitbucket para trabajar con nuestro repositorio.

¡Happy gitting!