2 Control de versiones con GitHub y RStudio

Dra. Alejandra Medina Rivera

28 de octubre de 2024

  • Este documento se basa en “Happy Git with R” de Jenny Bryan, los STAT 545 TAs, Jim Hester

https://happygitwithr.com

2.1 Diapositivas

2.2 ¿Por qué hacer control de versiones de nuestros proyectos?

  1. ✅ Los proyectos suelen cambiar y crecer.
  2. 💾 Es díficil saber cuáles fueron todos los cambios a lo largo del tiempo (en especial tiempos largos, hazlo por tu yo del futuro!).
  3. 🤔 Las colaboraciones se pueden complicar sin un buen control de versiones.
  4. 🔐 Seguridad.

2.3 Git

  • Git es un sistema de control de versiones
  • Git funciona con GitHub, Bitbucket o GitLab

¿Por qué usar Git en vez de solo renombrar los archivos?

✅✅Por qué es mejor tener una filogenia del archivo.

Git es un sistema de control de versiones distribuido, gratuito y de código abierto, diseñado para manejar todo tipo de proyectos, desde los más pequeños hasta los más grandes, con rapidez y eficiencia.

Git es fácil de aprender y ocupa poco espacio con un rendimiento rapidísimo. Supera a las herramientas SCM como Subversion, CVS, Perforce y ClearCase con características como la ramificación local barata, las cómodas áreas de preparación y los múltiples flujos de trabajo.

2.3.1 Git vs controles de versión a mano

Con Git cada contribuidor tiene una copia del repositorio central, con todos los archivos y la historia de los cambios por los que han pasado.

Excuse me, do you have a moment to talk about version control?, Jennifer Bryan, 2017

⚠️ NO OLVIDES TENER INSTALADO Git, en caso de que aún no lo hayas instalado, lo puedes descargar en el siguiente enlace https://git-scm.com/downloads.

Para conocer la localización y la versión de Git que tienes en tu computadora, corre el siguiente comando en la terminal: which git y git --version

2.4 Recomendaciones para sus proyectos

  • Dedicar un directorio
  • Es mejor organizarlo en un RStudio Project
  • Hacer un repositorio de Git
  • Trabajen como siempre, solo además de guardar, recuerden hacer commit
  • De vez en vez hagan push de sus cambios cuando los hayan verificado.

2.5 Proyectos colaborativos

  • GitHub se parece más a un GoogleDoc que a un Word Document.
  • Es fácil que los colaboradores hagan cambios y también es fácil saber quién hizo que.
  • El owner del proyecto puede dar permisos a los diferentes colaboradores.
  • También existen organizaciones, esto puede ser útil para manejar los permisos de grupos grandes de colaboración.

2.6 GitHub

GitHub es una plataforma para guardar proyectos, hace uso de Git. Su principal utilidad es para generar código fuente de programas.

⚠️ NO OLVIDES TENER UNA CUENTA EN GITHUB, en caso de que aún no lo hayas hecho, puedes ir la página de GitHub y seleccionar join. Es indispensable tu usuario para los ejercicios que siguen.

También existen otras plataformas como Bitbucked y GitLab, las cuales funcionan de manera similar a GitHub.

2.7 Manual de sobreviviencia con Git Y GitHub en RStudio (en caso de ser necesario)

  • Por cualquier problema con la conexión entre RStudio y Git, siempre ten en cuenta la ubicación de dónde se instaló Git.
    • Puedes usar en la terminal which git (Mac y Linux)
    • O bien usar en la terminal where git (Windows)
  • Recuerda que la terminal (o línea de comandos ó consola ó shell ó bash) es un programa en tu computadora que funciona para correr otros programas. Desde RStudio puedes abrir la terminal, lo cual es muy conveniente si estás trabajando en un proyecto. Puedes abrir una terminal con:
    • Tools > Terminal (abre la terminal dentro del IDE de RStudio)
    • Tools > Shell (abre una terminal externa a RStudio)

2.8 Cómo clonar un repositorio y tener conección/permisos para modificarlo?

  • Git puede comunicarse con un servidor remoto usando uno de dos protocolos, HTTPS o SSH, y cada protocolo usa credenciales diferentes.

  • La recomendación actual de GitHub es usar HTTPS porque es la manera más fácil de configurar y tiene operabilidad en multiples redes y plataformas.

    • Es menos probable que HTTPS sea bloqueado por un firewall.
    • Una conexión HTTPS permite que credential.helper almacene en caché su contraseña. (por tanto puedes configurar tu usuario y contraseña en tu equipo de uso)
    • Es más sencillo acceder a un repositorio desde cualquier lugar, ya que solo necesitas los detalles de tu cuenta (no se requieren claves SSH) para escribir en el repositorio.

  • Usualmente cuando inicies un proyecto colaborativo con GitHub inicializa el ropositorio con un README. Copia el HTTPS URL para clonar el repositorio en la terminal git clone https://github.com/TU-USUARIO/TU-REPOSITORIO.git.

2.9 Credenciales HTTPS en Cache

Para usar HTTPS debes crear un token de acceso personal, PAT (PERSONAL ACCESS TOKEN), esa será tu credencial para HTTPS. Es una alternativa al uso de contraseñas para la autenticación en GitHub.

Como precaución de seguridad, GitHub elimina automáticamente los tokens de acceso personales que no se han usado durante un año.

¿Cómo crear un token?

  1. Ve a tu perfil de GitHub, dale click a la imagen de perfil (usualmente en la esquina superior derecha), y busca la opción de settings ó configuración según sea la configuración de idioma que tengas.

  2. Da click a continuación en Developer settings ó Parámetros del desarrollador.

  3. En la barra lateral izquierda da click en Tokens de acceso personal.

  4. Haz click en Generar un nuevo token.

  5. Asígna un nombre descriptivo a tu token.

  6. Selecciona los alcances o permisos que deseas otorgarle a este token. Para usar tu token para acceder a repositorios desde la línea de comando, selecciona repo. (Recomendados: repo, user, workflow )

  7. Finalmente haz click en generar token.

  8. Listo, copia y pega tu token en el lugar dónde siempre lo puedas volver a copiar, ya que por razones de seguridad, una vez salgas de la página no podrás volver a ver el token.

  • Nota: Preserva tus tokens de la misma manera que tus contraseñas y no se las reveles a nadie.

Una vez que tengas un token, puedes ingresarlo en lugar de tu contraseña cuando realices operaciones de Git a través de HTTPS.

El punto final es que una vez configurada una PAT, varios paquetes de R, incluidos usethis y gh, podrán trabajar con la API de GitHub en su nombre, de forma automática. Por lo tanto, una PAT configurada correctamente significa que todo esto funcionará a la perfección:

- Operaciones HTTPS remotas a través de la línea de comando Git y, por lo tanto, a través de RStudio
- Operaciones HTTPS remotas a través del paquete gert R y, por lo tanto, usethis
- Operaciones de la API de GitHub a través del paquete gh R y, por lo tanto, usethis

Probar el repositorio Clonado

Después de hacer clone Usa estos comandos para verificar tu repositorio y revisar desde dónde se está sincorinzando.

cd myrepo
ls -la
head README.md
git remote show origin

Probemos haciendo un cambio en el README

echo "Something I want to add to the README in my local computer" >> README.md
git status

  • Qué pasó?

  • Ahora tenemos que decirle a git que queremos seguir los cambios de ese archivo

  • Vamos a commit los cambios y luego a subir (push) los mismos a GitHub

git add README.md
git commit -m "A commit from my local computer"
git push

Recuerda tu TOKEN!!

¿Cómo crear un token desde R?

Puedes ir directamente a la página de GitHub a la parte para generar tu token de acceso personal mediante la siguiente función:

usethis::create_github_token()

Y con las opciones que se mencionaban anteriormente puedes configurar y crear tu PAT.

Si lo que quieres es especificar tu PAT en RStudio, las siguientes funciones te serán útiles:

library(gitcreds)

gitcreds_set()
library(credentials)

set_github_pat()

Para eliminar credenciales utiliza la función credentials::git_credential_forget()

2.9.1 Actividad

Ejecuta los códigos y genera tu PAT, recuerda no perderlo!

2.10 Conectando RStudio con Git y Github.

Para lo que sigue a continuación, deberías tener esto:

  1. Tener una cuenta en GitHub
  2. R y RStudio actualizados
  3. Git instalado
  4. Saber que desde la terminal puedes hacer push y pull

2.11 GitHub primero, RStudio después…

  1. Crea un repositorio en GitHub: mi_repositorio > Public > YES initialize this repository with a README > clicken el gran botón verde “Create repository”
  2. En RStudio crea un nuevo proyecto: File > New Project > Version Control > Git. Ahi pega el URL del repositorio https://github.com/mi_usuario/mi_repositorio.git. Da click en Create Project.

Esto nos generará los siguientes elementos:

  • Un directorio nuevo
  • Un repositorio Git enlazado a al repositorio de GitHub
  • Un proyecto en RStudio

Con este procedimiento ya no es necesario preocuparse por configurar controles remotos Git y rastrear ramas en la línea de comandos.

2.11.1 Actividad

  • Genera un repositorio con el nombre que desees. Y conéctalo a RStudio. Cerciorate de que el archivo README se encuentre en tu nueva carpeta.
  • Usa la función usethis::use_r("titulo_de_un_script") y observa lo que sucede.

PAUSA

¿Cómo comento y doy push/pull desde RStudio?

2.11.2 Comentar, pull y push

Con la flecha azul podemos hacer pull (RECUERDA HACERLO ANTES DE HACER UN PUSH), y con la flecha verde un push. Para poder comentar y hacer push debemos marcar con una flechita mediante un click en las pequeñas cajas blancas de la columna Staged, damoc click en commit lo cual no abre la siguiente ventana.

Volvemos a dar click en commit, y finalizamos con push (flecha verde).

2.12 Rmarkdown en GitHub

  • Creemos un Rmakrdown y subámoslo a GitHub
  • Ahora hay que agregarlo al repositorio (add), stage and commit.
  • Subieron el hmlt? Qué tal se ve?
  • No se ve como queremos, verdad? Para eso necesitamos recuperar el .md. El .md es un resultado intermedio de crear el html desde Rmd.
  • Tenemos que cambiar el header para esto
---
title: "RmarkwondTest"
output: 
  html_document:
    keep_md: true
---

2.12.1 Actividad

  • Usa el código dir.create("mis_imagenes") en la consola de tu sesión de RStudio (la que está vinculada a tu repositorio). Ejecuta el siguiente código quitando los #:
install.packages("MASS")
library (MASS)
data(MASS::cats)
# pdf("mis_imagenes/cats_plot.pdf") 
ggplot(cats, aes(x = Sex)) + 
    geom_bar(fill = "orange", color = "black") + theme_classic() +
    xlab("Sexo") + ylab("Número de Gatos") + ggtitle("Gatos")
# dev.off()
  • Comenta y da push a los cambios que realizaste en el repositorio.

2.13 RStudio primero y GitHub también

Usa uno de los proyectos que hayas generado en las sesiones anteriores, PERO, que no esté enlazado a GitHub. Ahora veremos como conectar un proyecto de R existente con GitHub. Realiza los pasos que hicimos en GitHub primero, RStudio después pero asegurate de crear un repositorio con un nuevo nombre.

Y LISTO!! usa un simple ctrl + c, ó mv ó click derecho + copiar ó el método que prefieras para mover o copiar archivos. Copia los archivos de tu antigüo proyecto al proyecto nuevo. Solo haz commit y push y listo, lo que tenía en tu antigüo proyecto ya está enlazado a GitHub.

2.14 Proyecto existente, GitHub al final

Supongamos que tenemos un proyecto de R existente en algún lugar de nuestra computadora.

NOTA: Para generar proyecto de RStudio desde la consola puedes utilizar el siguiente código:

usethis::create_project()

O en RStudio con File > New Project > Existing Directory

Si su proyecto ya es un proyecto de RStudio, ejecútelo.

¿Ya es un repositorio de Git? La presencia del panel de Git debería alertarlo. Si es así, ha terminado.

Sino este es el primer camino a seguir:

  • Con el páquete usethis usa la función usethis::use_git
  • En RStudio ve a Tools > Project Options > Git/SVN. Dentro de Version control system, selecciona Git. Y da click a “Yes” cuando aparezca “Confirm New Git Repository?”.

Si usaste RStudio o usethis, el proyecto debería reiniciarse en RStudio. Hazlo tu mismo si hizo git init. RStudio ahora debería tener un panel Git.

2.14.1 Breviario cultural con los PATs

Si usas el paquete usethis Y has configurado un token de acceso personal (PAT) de GitHub has esto en R:

usethis::use_github()

Esto creará un nuevo repositorio en GitHub, lo agregará como un control remoto, configurará una rama de seguimiento y lo abrirá en su navegador. Lea la ayuda de use_github() para conocer sus argumentos y consejos sobre cómo configurar una PAT. Esto es extremadamente útil para una variedad de flujos de trabajo que llaman a la API de GitHub. Considere configurar esto si usa usethis, devtools o gh con regularidad.

Volviendo al tema de Proyecto existente, GitHub al final.

Otra opción que se puede hacer para conectar un proyecto existen a GitHub es ir a hacer un repositorio a GitHub PERO ten en cuenta los siguientes cambios:

  1. Elije un nombre de repositorio; probablemente debería coincidir con el nombre de su proyecto y directorio local.
  2. NO inicialice este repositorio con un archivo README.

Todo lo demás es igual a los pasos que hacíamos en GitHub primero, RStudio después…

Ahora ve a tu proyecto de RStudio, has clic en los “dos cuadros de color púrpura y un cuadrado blanco” en el panel de Git. Has clic en “Agregar control remoto”. Pegue la URL aquí y elija un nombre remoto, casi con certeza el origin. Ahora “ADD”.

Pasado esto deberiamos volver en el cuadro de diálogo “New Branch”. Ingresa “master” como el nombre de la rama y asegúrate de que la opción “Sync branch with remote” esté marcada. Haz clic en “Create”. En el siguiente cuadro de diálogo elije “overwrite”.

Ahora solo haz commit/pull/push y cérciorate que FUNCIONE!!

2.15 Git basics: commands

  • Fetch Commits
git fetch
  • Create and Switch to a branch
git branch [branch-name]
git checkout [branch-name]

2.16 Merge conflics

  • A veces, no tan a veces también, las cosas no salen bien a la primera
  • Merging (Fusionar) es una de esas cosas
  • Cuando bajamos un cambio o fusionamos branches esto puede pasar.
  • Primera regla: NO ENTRAR EN PANICO!!!
  • Revisen el status del repositorio. Qué archivo tiene conflicto?

2.17 Merge conflics

  • Abran ese archivo y busquen los problemas de merge. Es fácil, se ven así:
<<<<<<< HEAD:index.html
<div id="footer">contact : email.support@github.com</div>
=======
<div id="footer">
 please contact us at support@github.com
</div>
>>>>>>> issue-5:index.html
  • Editen esa sección, dejen una versión final.
  • Hagan commit y push
  • Si entran en pánico? Aborten la misión!
git merge --abort t

2.18 En resumen

¡QUE LA FUERZA TE ACOMPAÑE!