b01t04.md

Git y GitHub

Git es un programa para gestionar código fuente. Fue creado por Linus Torvalds para gestionar el código fuente del kernel de Linux.

GitHub es una servicio de hosting de código fuente que ha evolucionado en una suerte de "red social" de programadores. Durante este curso, utilizaremos GitHub como herramienta colaborativa, siguiendo el espíritu de otros cursos de Fictizia.

Git

Git lo instalaste hace un par de bloques y aunque existen interfaces gráficas de usuario, durante este curso utilizaremos mayoritariamente la consola y las herramientas integradas en PyCharm.

1. Crea una cuenta en GitHub.

2. Utilizando la terminal, configura tu nombre de usuario:

   $ git config --global user.name "Salvador de la Puente"

3. Utilizando la terminal, configura tu e-mail también:

   $ git config --global user.email "[email protected]"

4. Crea un fork del repositorio del curso Fictizia/Master-en-Programacion-con-Python_ed1.

5. Encuéntrale un hueco al directorio del curso en algún lugar de tu sistema de archivos (te recomiendo en el directorio ~). Cambia de directorio:

   $ cd ~

6. Clona tu copia del repositorio con el siguiente comando (sustituye las porciones entre ángulos < y > por lo que corresponda):

   $ git clone https://github.com/<tu-usuario>/Master-en-Programacion-con-Python_ed1.git

7. El comando anterior crea una carpeta Master-en-Programacion-con-Python_ed1 donde se encuentra la copia del proyecto. Entra en esta carpeta:

   $ cd Master-en-Programacion-con-Python_ed1

   Vas a crear tu propio directorio como si se tratase de un módulo de Python, donde subirás tus proyectos y ejercicios. Hablaremos más sobre módulos y organización de código durante el curso.

8. Antes de modificar la estructura de directorios, crea una nueva rama con el siguiente comando:

   $ git checkout -b mis-proyectos

9. Ahora crea una nueva carpeta dentro de alumni con tu nombre de usuario (yo usaré el mío: delapuente):

   $ mkdir alumni/delapuente

10. Introduce el fichero fizzbuzz.py que creaste durante la lección anterior:

    $ mv ruta/hasta/fizzbuzz.py alumni/delapuente

11. Crea también un fichero llamado __init__.py vacío, dentro de tu directorio:

    $ touch alumni/delapuente/__init__.py

12. Comprueba el estado de git con:

    $ git status

13. Añade todos los nuevos archivos con:

    $ git add .

    El punto . indica el directorio actual. Git añade, recursivamente, todos los subdirectorios y ficheros modificados.

14. Vuelve a comprobar el estado de git. Lee la información en pantalla cuidadosamente para comprender como deshacer los últimos comandos si fuera necesario.

15. Crea una nueva versión con el comando:

    $ git commit -m'Añadiendo el módulo con mi usuario.'

16. Envía tus cambios a GitHub haciendo push a tu repositorio remoto:

    $ git push origin mis-proyectos

17. Introduce tus credenciales para permitir la sincronización con el repositorio remoto.

¿Qué ha pasado?

A lo largo de los pasos anteriores, hemos seguido un workflow o forma de trabajo llamada "forking-workflow". Hay muchas formas de trabajar en Git pero con esta se alcanzan algunas promesas de seguridad que no se logran con otros modelos y permite contribuir a cualquier repositorio sin ser contribuyente del mismo (algo para lo que los responsables del repositorio te tienen que dar permiso, explícitamente).

Todo comienza al crear una copia remota de un repositorio (un fork), en tu cuenta. Me referiré a la misma como "tu repositorio remoto". Luego has copiado tu repositorio remoto en tu ordenador, creando lo que llamaré "tu repositorio o copia local". Cuando haces esto, git añade, automáticamente, un "remoto" apuntando a tu copia remota. Los remotos son URLs hacia copias remotas. El remoto apuntando a la dirección de la que clonaste el repositorio se llama origin.

• Lista todos los remotos con:

  $ git remote -v

Lo siguiente que has hecho es crear una rama nueva (un branch). Git es capaz de trabajar con múltiples versiones de tu código, una a la vez.

• Lista todas las ramas con:

  $ git branch --list

  El asterisco muestra la rama activa. Presiona q para salir.

Después has modificado el contenido del proyecto para crear el módulo de tu usuario y los archivos pertinentes. Llega el momento de pedir a git que guarde tus cambios. Lo primero es anotar los cambios, esto es lo que hacemos con git add .. Al indicar a git que anote los cambios sobre el directorio actual (representado por el punto .), git anota recursivamente todos los cambios del directorio y subdirectorios. Estos cambios están ahora en el índice.

La penúltima orden, commit envía los cambios al histórico (también llamado "la historia del repositorio"). Cuando haces commit debes añadir un comentario.

El comentario es importante para mantener un histórico útil y existen recomendaciones a la hora de escribirlos:

• Writing Meaningful Git Commit Messages
• How to Write a Git Commit Message

Quédate con la opción que más se ajuste a tus necesidades.

• Visualiza los cambios en el histórico con:

  $ git log

  Fíjate en el numeraco en hexadecimal al comienzo de cada entrada del histórico. Este número se llama hash. A cada entrada del histórico se le llama commit. Se podría decir que el número identifica de manera inequívoca el estado del histórico. Sal del log pulsando q.

En realidad, podríamos decir que hay un histórico por rama pero cuando se habla de "la historia", nos solemos referir al histórico de la rama master.

La última orden, push copia la rama del repositorio local al repositorio remoto.

Como otras cosas en el curso, aprenderemos más sobre Git conforme avancemos a través de las lecciones. Además, con lo que veremos a continuación, vosotros mismos podréis contribuir a expandir y enriquecer el curso. Si queréis profundizar en git, echadle un vistazo a los siguientes recursos:

• Git-it*
• Git (interactive) cheat sheet*
• Resources to learn Git
• Comparing Workflows
• Version Control with Git

En caso de no saber qué hacer si se mete la pata con Git:

• Oh shit, git!
• Git pretty*

A veces ayuda navegar los sucesos de un repositorio de forma más rica. Podéis hacerlo con el siguiente cliente de escritorio.

También podéis revisar el contenido de la lección sobre Git que viene con el Máster en Programación FullStack con JavaScript y Node.js.

Guardar trabajo para más tarde

A veces trabajaremos en un proyecto y tendremos que cambiar de rama con cosas a medio hacer. En tal caso podemos guardar el progreso hasta el momento en la pila del stash. Para guardar el trabajo hasta el momento utiliza:

$ git stash

Al ejecutar la orden, se crea un nuevo commit y se guarda en el stash. También se revierte el estado del proyecto al último commit (vamos, que se descartan todos los cambios).

Puedes listar las entradas del stash con:

$ git stash list

El listado muestra el mensaje autogenerado que se usó para guardar el estado. Este mensaje es importante porque indica la rama sobre la que estabas trabajando. Puedes recuperar el último estado salvado con:

$ git stash pop

Este comando aplica los cambios al estado de la rama actual y elimina el estado guardado. Si no quisieras quitarlo del stash, utiliza:

$ git stash apply

Aprende más sobre el stash con los siguientes recursos:

• Git Stash*
• Useful tricks you might not know about Git stash

Colaborando con GitHub

Una vez hemos subido nuestras ramas a GitHub, llega el momento de contribuir a los repositorios. GitHub ofrece innumerables características para la gestión de equipos, de proyectos, y de código, incluyendo una editor online pero en esta sección nos centraremos en dos características: issues y pull requests.

Issues

En el contexto de GitHub, podríamos traducir issue como "cuestión", en un sentido más amplio que el de "pregunta". Una issue representa "algo que hacer".

Podéis crear issues con preguntas, o tareas que penséis que podrían mejorar el curso. Podéis usarlo para apuntar problemas, mejoras o bugs en el código de los ejemplos. Cuando decidáis crear una nueva issue, haced clic sobre el botón "New Issue" en el panel de issues y podréis elegir entre algunas plantillas, dependiendo de lo que queráis apuntar.

En un proyecto de código abierto, aquí encontrariais las tareas que hay que hacer o los bugs que hay que arreglar. También es común hacer preguntas a la comunidad o llevar discusiones sobre decisiones de diseño.

Os aconsejo que os familiaricéis creando y buscando issues:

• Mastering Issues*
• Mastering Markdown*
• Searching issues and pull requests

Pull requests

La forma de contribuir en este mundo del código abierto es realizando peticiones de mezcla (a falta de una mejor traducción). Estas consisten en pedir a los encargados del repositorio original que incluyan los cambios en una de tus ramas.

1. Visita tu repositorio en GitHub y haz clic en el botón "New Pull Request".

2. El repositorio base (base repository) debe haberse configurado automáticamente a Fictizia/Master-en-Programacion-con-Python_ed1, rama master. Utiliza los controles desplegables para seleccionar el repositorio desde el que se realizará la mezcla (head repository), en este caso el tuyo y luego selecciona la rama mis-proyectos.

3. Observa las diferencias.

4. Haz clic en "Create Pull Request" para terminar de crear la petición de mezcla.

5. Espera hasta que tus cambios se mezclen.

Si quieres saber más sobre pull request, no dudes en consultar algunos de los siguientes recursos:

• Creating a pull request from a fork*
• About pull requests

El proceso de revisión

La revisión de código es, posiblemente, el aspecto más importante del ciclo de contribución. Durante la fase de revisión, los encargados del repositorio original revisan el código propuesto e intervienen con conmentarios pidiendo explicaciones, sugiriendo mejores implementacions o destacando typos o errores en la implementación.

Las herramientas para la revisión de código quedan fuera del alancance del curso pero es necesario saber desenvolverse en una situación como esta porque será la forma en que se corregirán tus ejercicios.

Una vez te hayas hecho cargo de los distintos comentarios de tu revisor en tu repositorio local tendrás que repetir los pasos 12 a 17 para anotar los cambios y enviar un nuevo commit. El pull request se actualiza al mismo tiempo que el histórico de la rama se actualiza.

Actualizando la base de código

Ahora que he actualizado el repositorio original con vuestros módulos, tendrás que poner al día tu copia local. Con la forma de trabajo que estamos utilizando, tu copia remota nunca se pondrá al día. Tan sólo usarás tu repositorio remoto para almacenar tus ramas con las modificaciones que quieras incorporar al repositorios principal. Sin embargo, tu copia local sí que tiene que estar siempre actualizada. Veamos cómo se hace esto:

1. Añade un remoto con la URL del repositorio original. Llámalo upstream (no es obligatorio pero se trata de un convenio):

   $ git remote add upstream https://github.com/Fictizia/Master-en-Programacion-con-Python_ed1.git

2. Lista los remotos y asegúrate de que tienes origin apuntando a tu repositorio remoto y upstream apuntando al repositorio remoto original

3. Sitúate sobre tu rama master:

   $ git checkout master

4. Mezcla el contenido de la rama master del remoto upstream con tu rama activa:

   $ git pull upstream master

5. Comprueba el histórico de la rama máster.

6. Puedes borrar tu rama, porque ya está mezclada:

   $ git branch -d mis-proyectos

7. También puedes borrar la rama de tu repositorio remoto.