Capítulo 39 Git y GitHub

Aquí proveemos algunos detalles sobre Git y GitHub. Sin embargo, solo estamos rascando la superficie. Para obtener más información sobre este tema, recomendamos los siguientes recursos:

Codeacademy: https://www.codecademy.com/learn/learn-git
Guías de GitHub: https://guides.github.com/activities/hello-world/
Try Git tutorial: https://try.github.io/levels/1/challenges/1
Happy Git y GitHub para el useR: http://happygitwithr.com

39.1 ¿Por qué usar Git y GitHub?

Hay tres razones principales para usar Git y GitHub.

Compartir: Incluso si no aprovechamos la funcionalidad avanzada y útiles de control de versiones, aún podemos usar Git y GitHub para compartir nuestro código.
Colaboración: Una vez que configuren un repositorio central, pueden hacer que varias personas realicen cambios en el código y mantengan las versiones sincronizadas. GitHub ofrece un servicio gratuito para repositorios centralizados. GitHub también tiene una herramienta, llamada pull request, que cualquier persona puede usar para sugerir cambios a su código. Pueden aceptar o rechazar fácilmente la recomendación.
Control de versiones: Las capacidades de control de versiones de Git nos permite darle seguimiento a los cambios que realizamos en nuestro código. Además, podemos volver a las versiones anteriores de los archivos. Git también nos permite crear branches en las que podemos probar ideas, luego decidir si fusionamos (merge en inglés) la nueva rama con la original.

Aquí nos enfocamos en los aspectos de uso compartido de Git y GitHub y remitimos al lector a los enlaces anteriores para obtener más información sobre esta herramienta útil.

39.2 Cuentas GitHub

Después de instalar git¹³², el primer paso es obtener una cuenta de GitHub. Las cuentas básicas de GitHub son gratuitas. Para hacer esto, vayan a GitHub.com donde verán un cuadro en el que pueden registrarse.

Quieren escoger un nombre con cuidado. Debe ser breve, fácil de recordar y deletrear, relacionado de alguna manera con su nombre y, por supuesto, profesional. Este último es importante ya que podrían estar enviando enlaces a sus cuentas de GitHub a posibles empleadores. En el siguiente ejemplo, sacrifico la facilidad de deletreo para incorporar mi nombre. Sus iniciales y apellidos suelen ser una buena opción. Si tienen un nombre muy común, es posible que tengan que tomar eso en cuenta. Una solución sencilla sería agregar números o deletrear parte de su nombre.

La cuenta que uso para mi investigación, rafalab, es la misma que uso para mi página web¹³³ y Twitter¹³⁴, que lo hace fácil de recordar para los que siguen mi trabajo.

Una vez que tengan una cuenta de GitHub, estarán listos para conectar Git y RStudio a esta cuenta.

Un primer paso es dejar que Git sepa quiénes somos. Esto facilitará la conexión con GitHub. Comenzamos abriendo una ventana de terminal en RStudio (recuerden que pueden obtener una a través de Tools en la barra de menú). Ahora usamos el comando git config para decirle a Git quiénes somos. Escribiremos los siguientes dos comandos en nuestra ventana de terminal:

git config --global user.name "Your Name"
git config --global user.mail "your@email.com"

Deben usar la cuenta de correo electrónico que utilizaron para abrir su cuenta de GitHub. La sesión de RStudio debería verse así:

Empiecen yendo a Global Options, seleccionando Git/SVN y luego ingresando una ruta para el ejecutable de Git que acabamos de instalar.

En la instalación predeterminada de Windows, la ruta será C:/Program File/Git/bin/git.exe, pero deben encontrarla explorando su sistema, ya que esto puede cambiar de un sistema a otro. Ahora, para evitar ingresar nuestra contraseña de GitHub cada vez que intentemos acceder a nuestro repositorio, crearemos lo que se llama una SSH RSA Key. RStudio puede hacer esto por nosotros automáticamente si hacemos clic en el botón Create RSA Key:

Pueden seguir las instrucciones predeterminadas como se muestra a continuación:

Git, RStudio y GitHub ahora deben poder conectarse y estamos listos para crear un primer repositorio de código de GitHub.

39.3 Repositorios de GitHub

Ya pueden crear un repositorio o “repo” de GitHub. La idea general es tener al menos dos copias de su código: una copia en sus computadoras y otra en GitHub. Si añaden colaboradores a este proyecto, cada uno tendrá una copia en su computadora. La copia de GitHub generalmente se considera la copia main (antes llamada master) con la que se sincroniza cada colaborador. Git les ayudará a mantener sincronizadas todas las copias diferentes.

Como se mencionó anteriormente, una de las ventajas de mantener el código en un repositorio de GitHub es que pueden compartirlo fácilmente con posibles empleadores interesados en ver ejemplos de su trabajo. Debido a que muchas compañías de ciencia de datos usan sistemas de control de versiones, como Git, para colaborar en proyectos, también pueden estar impresionadas de que ya conocen al menos los conceptos básicos.

El primer paso para crear un repositorio para su código es inicializar en GitHub. Como ya crearon una cuenta, tendrán una página en GitHub con el URL http://github.com/username.

Para crear un repositorio, primero inicien una sesión en su cuenta haciendo clic en el botón Sign In en https://github.com. Es posible que ya hayan iniciado una sesión, en cuyo caso el botón Sign In no aparecerá. Si inician sesión, deben ingresar su nombre de usuario y contraseña. Le recomendamos que configuren su navegador para recordar esto y evitar escribirlo cada vez.

Una vez en sus cuentas, pueden hacer clic en Repositories y luego hacer clic en New para crear un nuevo repositorio:

Entonces querrán elegir un buen nombre descriptivo para el proyecto. En el futuro, es posible que tengan docenas de repositorios, así que tomen esto en cuenta al elegir un nombre. Aquí usaremos homework-0. Le recomendamos que hagan público el repositorio. Si prefieren mantenerlo en privado, tendrán que pagar un cargo mensual.

Ahora tienen su primer repositorio en GitHub. El siguiente paso será clonarlo (clone it en inglés) en su computadora y comenzar a editar y sincronizar usando Git.

Para hacer esto, es conveniente copiar el enlace proporcionado por GitHub específicamente para conectarse a este repositorio, usando Git como se muestra a continuación. Más tarde, necesitaremos copiar y pegar esto, así que asegúrense de recordar este paso.

39.4 Descripción general de Git

Las principales acciones en Git son:

pull: Jalar/tirar cambios desde el repositorio remoto, en este caso el repositorio de GitHub.
add: Añadir archivos o, como decimos en la jerga de Git, stage los archivos.
commit: Asignar cambios al repositorio local.
push: Empujar cambios al repositorio remote, en nuestro caso el repositorio GitHub.

Para permitir efectivamente el control de versiones y la colaboración en Git, los archivos se mueven a través de cuatro áreas diferentes:

Pero, ¿cómo comienza todo? Hay dos formas: podemos clonar un repositorio existente o inicializar uno. Exploraremos la clonación primero.

39.4.1 Clonar

Vamos a clonar un Upstream Repository existente. Pueden verlo en GitHub aquí: https://github.com/rairizarry/murders. Al visitar esta página, pueden ver varios archivos y directorios. Estos son el Upstream Repository. Al hacer clic en el botón verde de clonar, podemos copiar el URL del repositorio: https://github.com/rairizarry/murders.git.

Pero, ¿qué significa clonar? En lugar de descargar todos estos archivos a su computadora, vamos a copiar toda la estructura de Git, que significa que agregaremos los archivos y directorios a cada una de las tres etapas locales: Working Directory, Staging Area y Local Repository. Cuando clonan, estos tres son exactamente iguales en el comienzo.

Pueden ver rápidamente un ejemplo de esto haciendo lo siguiente. Abran una terminal y escriban:

pwd
mkdir git-example
cd git-example
git clone https://github.com/rairizarry/murders.git
cd murders
#> /Users/rafa/myDocuments/teaching/data-science/dslibro
#> Cloning into 'murders'...

Ahora han clonado un repositorio de GitHub y tienen un directorio de trabajo de Git, con todos los archivos, en su sistema.

ls
#> README.txt
#> analysis.R
#> data
#> download-data.R
#> murders.Rproj
#> rdas
#> report.Rmd
#> report.md
#> report_files
#> wrangle-data.R

El Working Directory es el mismo que el directorio de trabajo de Unix. Cuando editan archivos usando un editor como RStudio, cambian los archivos en esta área y solo en esta área. Git puede decirles cómo se relacionan estos archivos con las versiones de los archivos en otras áreas con el comando git status:

Si verifican el estatus ahora, verán que nada ha cambiado y recibirán el siguiente mensaje:

git status
#> On branch master
#> Your branch is up to date with 'origin/master'.
#> 
#> nothing to commit, working tree clean

Ahora vamos a hacer cambios en estos archivos. Eventualmente, queremos que estas nuevas versiones de los archivos sean rastreadas y sincronizadas con el Upstream Repository. Pero no queremos darle seguimiento a cada cambio pequeño: no queremos sincronizar hasta que estemos seguros de que estas versiones son lo suficientemente finales como para compartirlas. Por esta razón, el sistema de control de versiones no guarda las ediciones en el Staging Area.

Para demostrar, agregamos un archivo al Staging Area con el comando git add. A continuación creamos un archivo usando el comando de Unix echo solo como ejemplo (normalmente usarían RStudio):

echo "test" >> new-file.txt

También estamos agregando un archivo temporero del cual que no queremos llevar cuenta:

echo "temporary" >> tmp.txt

Ahora podemos organizar el archivo que finalmente queremos agregar a nuestro repositorio:

git add new-file.txt

Observen lo que dice el estatus ahora:

git status
#> On branch master
#> Your branch is up to date with 'origin/master'.
#> 
#> Changes to be committed:
#>   (use "git restore --staged <file>..." to unstage)
#>  new file:   new-file.txt
#> 
#> Untracked files:
#>   (use "git add <file>..." to include in what will be committed)
#>  tmp.txt

Como new-file.txt está staged, la versión actual del archivo se agregará al repositorio local la próxima vez que decidimos commit, que hacemos de la siguiente manera:

git commit -m "adding a new file"
#> [master 6874aa2] adding a new file
#>  1 file changed, 1 insertion(+)
#>  create mode 100644 new-file.txt

Ahora hemos cambiado el repositorio local, que pueden confirmar usando:

git status

Sin embargo, si volvemos a editar ese archivo, solo cambia en el directorio de trabajo. Para agregar al repositorio local, necesitamos añadirlo y commit los cambios que se agregan al repositorio local:

echo "adding a line" >> new-file.txt
git add new-file.txt
git commit -m "adding a new line to new-file"
#> [master 0759c90] adding a new line to new-file
#>  1 file changed, 1 insertion(+)

Tengan en cuenta que este paso a menudo es innecesario en nuestros usos de Git. Podemos omitir la parte de preparación si agregamos el nombre del archivo al comando commit de esta manera:

echo "adding a second line" >> new-file.txt
git commit -m "minor change to new-file" new-file.txt
#> [master 6838381] minor change to new-file
#>  1 file changed, 1 insertion(+)

Podemos darle seguimiento a todos los cambios que hemos realizado con:

git log new-file.txt
#> commit 6838381153d8349a4902c1af0a01639105f94984
#> Author: Rafael A. Irizarry <rairizarry@gmail.com>
#> Date:   Mon Oct 31 09:00:37 2022 -0400
#> 
#>     minor change to new-file
#> 
#> commit 0759c9057ed4dfa1eaaf0cd194ed0bd93d79e6c2
#> Author: Rafael A. Irizarry <rairizarry@gmail.com>
#> Date:   Mon Oct 31 09:00:37 2022 -0400
#> 
#>     adding a new line to new-file
#> 
#> commit 6874aa224774446dd3d1844e2e25a5131d0675bb
#> Author: Rafael A. Irizarry <rairizarry@gmail.com>
#> Date:   Mon Oct 31 09:00:36 2022 -0400
#> 
#>     adding a new file

Para mantener todo sincronizado, el paso final es impulsar los cambios al Upstream Repository. Esto se hace con el comando git push así:

git push

Sin embargo, en este ejemplo particular, no podrán hacerlo porque no tienen permiso para editar el Upstream Repository. Si este fuera su repositorio, podrían.

Si este es un proyecto colaborativo, el Upstream Repository puede cambiar y volverse diferente a nuestra versión. Para actualizar nuestro repositorio local para que sea como el Upstream Repository, usamos el comando fetch:

git fetch

Y entonces para hacer estos cambios al Staging Area y Working Directory, utilizamos el comando:

git merge

No obstante, a menudo solo queremos cambiar ambos con un solo comando. Para esto, utilizamos:

git pull

Aprenderemos en la Sección 39.6 cómo RStudio tiene botones para hacer todo esto. Los detalles ofrecidos aquí les ayuda a entender lo que sucede en el trasfondo.

39.5 Inicializando un directorio Git

Ahora exploremos la segunda manera en que podemos comenzar: inicializando un directorio en nuestra propia computadora en lugar de clonar.

Supongan que ya tenemos un directorio local con archivos y queremos convertir este directorio en un repositorio colaborativo de GitHub. La forma más eficiente de lograr esto es inicializando el directorio local.

Para demostrar cómo hacer esto, inicializaremos el directorio de asesinatos con armas de fuego que creamos en la Sección 38.7. Tengan en cuenta que ya creamos un directorio con varios subdirectorios en nuestra computadora, pero aún no tenemos un repositorio local de Git o un Upstream Repository de GitHub.

Comenzamos creando un nuevo repositorio en nuestra página de GitHub. Hacemos clic en el botón New:

Lo llamamos murders aquí para que coincida con el nombre del directorio en nuestro sistema local. Pero si están haciendo esto para otro proyecto, elijan un nombre apropiado.

Luego obtenemos una serie de instrucciones sobre cómo comenzar, pero en su lugar podemos usar lo que hemos aprendido. Lo principal que necesitamos de esta página es copiar el URL del repositorio, en este caso: https://github.com/rairizarry/murders.git.

En este momento, podemos abrir un terminal y cd a nuestro directorio de proyectos locales. En nuestro ejemplo, sería:

cd ~/projects/murders

Entonces, inicializamos el directorio. Esto convierte el directorio en un directorio Git y Git comienza a llevar cuenta:

git init

Todos los archivos ahora están solo en nuestro directorio de trabajo; no hay archivos en nuestro repositorio local o en GitHub.

El siguiente paso es conectar el repositorio local con el repositorio de GitHub. En un ejemplo anterior, hicimos que RStudio hiciera esto por nosotros. Ahora tenemos que hacerlo nosotros mismos. Podemos agregar cualquiera de los archivos y hacer commit:

git add README.txt
git commit -m "First commit. Adding README.txt file just to get started"

Ahora tenemos un archivo en nuestro repositorio local y podemos conectarlo al Upstream Repository, que tiene URL: https://github.com/rairizarry/murders.git.

Para hacer esto, usamos el comando git remote add.

git remote add origin `https://github.com/rairizarry/murders.git`

Ahora podemos usar git push ya que hay una conexión a un Upstream Repository:

git push

En la Sección 40.3, continuamos trabajando con este ejemplo, mientras demostramos cómo podemos usar RStudio para trabajar con Git y mantener un proyecto sincronizado en GitHub.

39.6 Usando Git y GitHub en RStudio

Si bien la línea de comandos Git es una herramienta eficaz y flexible, puede ser algo desalentador cuando estamos comenzando. RStudio proporciona una interfaz gráfico que facilita el uso de Git en el contexto de un proyecto de análisis de datos. Describimos cómo usar este atributo de RStudio para hacer esto aquí.

Ahora estamos listos para comenzar un proyecto de RStudio que usa control de versiones y almacena el código en un repositorio de GitHub. Para hacer esto, comenzamos un proyecto pero, en lugar de New Directory, seleccionaremos Version Control y luego seleccionaremos Git como nuestro sistema de control de versiones:

El URL del repositorio es el enlace que usaron para clonar. En la Sección 39.3, usamos https://github.com/username/homework-0.git como ejemplo. En el nombre del directorio del proyecto, deben poner el nombre de la carpeta que se generó, que en nuestro ejemplo será el nombre del repositorio homework-0. Esto creará una carpeta llamada homework-0 en su sistema local. Una vez que hagan esto, se crea el proyecto y está al tanto de la conexión a un repositorio de GitHub. Verán en la esquina superior derecha el nombre y el tipo de proyecto, así como una nueva pestaña en el panel superior derecho titulada Git.

Si seleccionan esta pestaña, les mostrará los archivos de sus proyectos con algunos iconos que le brindan información sobre estos archivos y su relación con el repositorio. En el ejemplo a continuación, ya agregamos un archivo a la carpeta, llamado code.R, que pueden ver en el panel para editar.

Ahora debemos prestar atención al panel Git. Es importante saber que sus archivos locales y el repositorio de GitHub no se sincronizarán automáticamente. Como se describe en la Sección 39.4, deben sincronizar usando git push cuando estén listos. A continuación, les mostramos que pueden hacerlo a través de RStudio en lugar del terminal.

Antes de comenzar a trabajar en un proyecto colaborativo, generalmente lo primero que hacemos es pull los cambios desde el repositorio remoto, en nuestro caso el de GitHub. Sin embargo, para el ejemplo que se muestra aquí, dado que estamos comenzando con un repositorio vacío y somos los únicos que hacemos cambios, no tenemos que comenzar con pull.

En RStudio, el status del archivo en relación con los repositorios remotos y locales se representa en los símbolos de status con colores. Un cuadrado amarillo significa que Git no sabe nada sobre este archivo. Para sincronizar con el repositorio de GitHub, necesitamos add el archivo, luego commit el cambio a nuestro repositorio de Git local y entonces push el cambio al repositorio de GitHub. En este momento, el archivo está en nuestra computadora. Para añadir el archivo usando RStudio, hacemos clic en la caja Stage. Verán que el ícono de status ahora cambia a una A verde.

Nota: solo estamos añadiendo el archivo code.R. No necesariamente tenemos que añadir todos los archivos de nuestro repositorio local al repositorio de GitHub, solo los que queremos darle seguimiento o los que queremos compartir. Si nuestro trabajo está produciendo archivos de cierto tipo a los que no queremos darle seguimiento, podemos agregar el sufijo que define estos archivos al archivo .gitignore. Aquí pueden ver más detalles sobre el uso de .gitignore: https://git-scm.com/docs/gitignore. Estos archivos dejarán de aparecer en su panel RStudio Git. Para el ejemplo que se muestra aquí, solo agregaremos code.R. Pero, en general, para un proyecto de RStudio, recomendamos agregar los archivos .gitignore y .Rproj.

Ahora estamos listos para enviar el archivo a nuestro repositorio local. En RStudio, podemos usar el botón Commit. Esto abrirá una nueva ventana de diálogo. Con Git, cada vez que hacemos commit a un cambio, debemos ingresar un comentario que describe los cambios.

En este caso, simplemente escribimos que estamos agregando un nuevo script. En este ventana de diálogo, RStudio también le ofrece un resumen de lo que está cambiando al repositorio de GitHub. Aquí, como es un archivo nuevo, todo el archivo se resalta en verde, que resalta los cambios.

Una vez que presionen el botón Commit, deben ver un mensaje de Git con un resumen de los cambios que se confirmaron. Ahora estamos listos para empujar estos cambios al repositorio de GitHub. Podemos hacer esto haciendo clic en el botón Push en la esquina superior derecha:

Ahora vemos un mensaje de Git que nos dice que el push ha sido exitoso. En la ventana emergente ya no vemos el archivo code.R. Esto se debe a que no se han realizado nuevos cambios desde la última vez que hicimos push. Podemos salir de esta ventana emergente ahora y continuar trabajando en nuestro código.

Si ahora visitamos nuestro repositorio en la web, veremos que coincide con nuestra copia local.

¡Felicitaciones, han compartido código con éxito en un repositorio de GitHub!