Conectar una carpeta local a un repositorio de GitHub

Puede que alguna que otra vez te hayas querido animar a crear tu porfolio en GitHub, bien sea porque empiezas en el mundo de la programación y quieres dejar constancia de lo que aprendes/desarrollas o bien, simplemente, por tener un buen control de versiones de tu código. Es más, en mi caso personal, es por la segunda opción.

En mi repositorio de GitHub he ido subiendo algunas cosillas que he programado por gusto. De hecho, os he mostrado por aquí algunos de esos desarrollos como el editor de metadatos en ficheros mp3 o dividir una carpeta en subcarpetas, aunque hay otros proyectos públicos como el contenido de una asignatura de la UOC y otros tantos que tengo privados. Te dejo aquí el enlace a mi GitHub por si quieres echarle un ojo.

En esta entrada te voy a explicar como conectar una carpeta local a un repositorio de GitHub, es decir, utilizar una carpeta de tu ordenador como repositorio de tu código. Eso si, lo ideal para entender y trabajar esta entrada es que tengas un conocimiento previo sobre comandos git para trabajar local y remotamente con tus repositorios (buena idea para una futura entrada, por cierto), el propio git instalado en tu máquina y una cuenta en GitHub.

Una cosa más. Esto vas a poder reproducirlo en cualquier SO que cuente con las herramientas básicas de gestión, además de el software de git ya comentado justo en el párrafo de arriba. Yo voy a hacer el manual desde la consola de WSL (Windows Subsystem for Linux) con una distro de Red Hat Enterprise Linux 8.10. Pero tu puedes usar la CMD o Git Bash de Windows, tu terminal de Linux o la de Mac OS. Como te digo, es indiferente.

Dicho esto, vamos allá.

Generar una clave SSH y asociarla a tu cuenta de GitHub

El primer paso que vamos a llevar a cabo es generar una clave SSH y asociarla a tu cuenta de GitHub. De esta forma, evitaremos tener que estar constantemente introduciendo nuestras credenciales por consola.

Para ello, abre la terminal que vayas a utilizar y lanza el siguiente comando:

ssh-keygen -t ed25519 -C "tu_email@ejemplo.com"

Con este comando vas a generarte un par de clave privada y pública utilizando el algoritmo ed25519. Si esto te diese error porque tu sistema no soporta dicha codificación, puedes usar alternativas como rsa, así:

ssh-keygen -t rsa -b 4096 -C "tu_email@ejemplo.com"

En ambos casos, el asistente de generación te hará alguna preguntas, como la ruta y nombre de los ficheros que vas a generar y si quieres añadir un passphrase. Una vez respondas estas opciones (si pulsas intro, se deja valor por defecto), tendrás tu clave SSH generada.

Importante. Si vas a cambiar el nombre por defecto de salida, tienes dos opciones: o especificas la ruta completa (~carpeta_home/.ssh/FICHERO) o te cambias previamente al directorio .ssh de tu home.

Lo ideal es que generes dicha clave con el email asociado de tu cuenta GitHub.

[pablodelgado@DESKTOP-UU1NMET ~]$ cd .ssh/

[pablodelgado@DESKTOP-UU1NMET .ssh]$ ssh-keygen -t ed25519 -C "pabloj.df@gmail.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/pablodelgado/.ssh/id_ed25519): pdf_wsl250519
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in pdf_wsl250519.
Your public key has been saved in pdf_wsl250519.pub.
The key fingerprint is:
SHA256: XXXXXXXXXXXXXXX pabloj.df@gmail.com
The key's randomart image is:
+--[ED25519 256]--+
|      .. .oo     |
|     . o.=o+.    |
|      o.EoO+     |
|     . *o+ o     |
|      o S + .    |
|       . o o     |
|          o      |
+----[SHA256]-----+

[pablodelgado@DESKTOP-UU1NMET .ssh]$ ls -la
total 0
drwx------ 1 pablodelgado pablodelgado 512 May 19 14:47 .
drwx------ 1 pablodelgado pablodelgado 512 May 19 14:46 ..
-rw-r--r-- 1 pablodelgado pablodelgado 185 May 19 13:04 known_hosts
-rw------- 1 pablodelgado pablodelgado 411 May 19 14:47 pdf_wsl250519
-rw-r--r-- 1 pablodelgado pablodelgado 101 May 19 14:47 pdf_wsl250519.pub

Como puedes observar, se han generado dos ficheros con el patrón que indiqué: pdf_wsl250519 (clave privada) y pdf_wsl250519.pub (clave pública).

Ahora, debemos copiar el contenido de la clave pública en nuestro repositorio de GitHub. Para ello, basta con visualizar el contenido para copiarlo y pegarlo en destino (yo acorto la salida por cuestiones de seguridad, pero tú tendrás la salida completa).

[pablodelgado@DESKTOP-UU1NMET .ssh]$ cat pdf_wsl250519.pub
ssh-ed25519 AAAA...qKM pabloj.df@gmail.com

Copia esa salida y dirígete a tu cuenta de GitHub → Settings → SSH and GPG keys. Una vez dentro, pulsamos en el botón New SSH key. Tenemos que rellenar tres campos: el nombre que quieres ponerle a dicha llave, el tipo de llave y la llave (pública) en si. Fíjate como lo he dejado yo:

Ya solo tienes que darle al botón de Add SSH key para terminar la configuración. Posiblemente, te saldrá un método de confirmación que deberás tener configurado en tu cuenta. En mi caso, tengo asociada la app Authenticator, por lo que solo debo introducir el código y listo.

Al terminar, volverás al apartado de SSH keys donde podrás visualizar tanto la recién creada como las anteriores que ya tuvieses.

Genial. Ya tenemos nuestra clave SSH asociada a nuestra cuenta de GitHub.

Configurar git para usarlo con GitHub

Vamos ahora a configurar el aplicativo de git en local con unos datos básicos para su uso: nuestro email y nuestro nombre, necesarios para que cuando hagamos un commit todo quede debidamente registrado. Solo debemos lanzar estos dos comandos:

git config --global user.name "Tu nombre"
git config --global user.email "tu_email@ejemplo.com"

En mi caso, los he lanzado así (de nuevo, el mismo correo asociado a GitHub):

[pablodelgado@DESKTOP-UU1NMET ~]$ git config --global user.name "Pablo Delgado"
[pablodelgado@DESKTOP-UU1NMET ~]$ git config --global user.email "pabloj.df@gmail.com"

Para corroborar que se han grabado correctamente, podemos hacer uso del parámetro –list.

[pablodelgado@DESKTOP-UU1NMET ~]$ git config --list
user.email=pabloj.df@gmail.com
user.name=Pablo Delgado

¡Listo! Otro pasito más completado.

Asociar carpeta local a un repositorio remoto

Y vamos ahora con la chicha que nos atañe. Para poder conectar una carpeta local a un repositorio de GitHub, debemos seguir estos tres sencillos pasos.

Inicializar un repositorio git en local

El primer paso que vamos a realizar es inicializar un repositorio de git en nuestra carpeta local. Para ello, nos dirigimos a la carpeta que va a contener nuestro código (en mi caso, /mnt/c/proyectos/Python/biblioteca). He lanzado un ls -la para que veas que no hay nada previo en dicho directorio.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ pwd
/mnt/c/proyectos/Python/biblioteca

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ls -la
total 0
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 13:19 .
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 13:19 ..

Ahora, para inicializar el repo, lanzamos el siguiente comando:

git init

Esto creará una nueva carpeta llamada .git (recuerda que en sistemas UNIX, el punto denota un directorio oculto, como el de .ssh). Aquí, git almacenará toda la información relacionada y necesaria con el control de versiones de tu proyecto.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git init
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint:   git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint:   git branch -m <name>
Initialized empty Git repository in /mnt/c/proyectos/Python/biblioteca/.git/

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ls -la
total 0
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 16:43 .
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 13:19 ..
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 16:43 .git

Conectar carpeta local a un repositorio de GitHub

Como ya tenemos el el repositorio local creado y configurado, ahora nos toca conectarlo a nuestro repositorio remoto en GitHub. Esto es más sencillo de lo que piensas, ya que el comando necesario es este:

git remote add origin <link SSH de tu repositorio remoto de GitHub>

Como ves, solo necesitas tener el link SSH a tu repo. ¡Es fácil de encontrar!

Dirígete a tu repositorio en GitHub y en la barra de tareas que aparece debajo del nombre, verás un botón verde llamado Code. Ahí, en el desplegable, verás que te aparecen tres opciones: HTTPS, SSH y GitHub CLI. A nosotros nos atañe la segunda opción, SSH.

Copia ese enlace. Como puedes obserbar, GitHub te avisa de que vas a usar una llave SSH protegida por contraseña.

Ahora puedes lanzar el comando de antes con el link necesario.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git remote add origin git@github.com:pablodelflo/biblioteca-personal.git

Y si quieres comprobar que todo ha ido bien:

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git remote -v
origin  git@github.com:pablodelflo/biblioteca-personal.git (fetch)
origin  git@github.com:pablodelflo/biblioteca-personal.git (push)

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh -T git@github.com
Hi pablodelflo! You've successfully authenticated, but GitHub does not provide shell access.

¡Listo! Ya tienes enlazados tu repositorio local y remoto. De hecho, voy a realizar dos pruebas más para que veas como se trabaría con ellos (aunque recuerda, la explicación no forma parte de esta entrada. Déjame en comentarios si te gustaría que escriba un post sobre comandos básicos de git.

Sincronizando repos: de GitHub a local

Esta acción es la que conocemos como pull. Es decir, vamos a traernos todos los cambios del repositorio remoto al local. Si comprobamos nuestro repo local, vamos a ver que no hay nada, solo el directorio .git.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ls -la
total 0
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 16:43 .
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 13:19 ..
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 16:56 .git

Y aunque en remoto el repositorio también esté ausente de código, hay un fichero que se creó con el repo (siempre que lo indicáramos nosotros): el README.md. Este fichero es un documento de presentación principal de un repositorio git. Está escrito en Markdown (.md) y suele ser lo primero que ve cualquiera que entra a nuestro repo.

Bien, para sincronizar nuestro repositorio desde GitHub hacia local, lanzamos ese comando pull que dijimos antes:

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git pull origin main
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 906 bytes | 90.00 KiB/s, done.
From github.com:pablodelflo/biblioteca-personal
 * branch            main       -> FETCH_HEAD
 * [new branch]      main       -> origin/main

Si ahora hacemos un listado de nuestro directorio, veremos que ese README.md está disponible de manera local y que incluso podemos visualizar su contenido:

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ls -la
total 0
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 17:39 .
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 13:19 ..
drwxrwxrwx 1 pablodelgado pablodelgado 512 May 19 17:39 .git
-rwxrwxrwx 1 pablodelgado pablodelgado  79 May 19 17:39 README.md

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ cat README.md
# biblioteca-personal
Programa en python para gestionar mi biblioteca persona.

¡Nos hemos traído hasta los errores de tipeo! Vamos a aprovechar que falta una l a la palabra personal y, de paso, creamos un fichero main.py vacío para realizar una subida de local.

Sincronizando repos: de local a GitHub

Ahora tocaría hacer la operación inversa, es decir, subir a nuestro repositorio remoto todos los cambios que hayamos hecho en local. Primero, voy a arreglar la falta de ortografía del README.md y crear un fichero main de Python vacío.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ vi README.md

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ cat README.md
# biblioteca-personal
Programa en python para gestionar mi biblioteca personal.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ touch main.py

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ls -ltr
total 0
-rwxrwxrwx 1 pablodelgado pablodelgado 80 May 19 17:44 README.md
-rwxrwxrwx 1 pablodelgado pablodelgado  0 May 19 17:44 main.py

Perfecto. Ahora que tengo mis ficheros modificados y creados, procedo a subirlos. Para ello, tenemos que realizar un push. Este push consta de tres fases (aunque ya veréis en el futuro que no necesariamente hay que hacerlas por separado):

1. Añadir los ficheros creados/modificados con git add . (aunque en lugar del . puedes especificar que ficheros deseas incluir).
2. Hacer un commit, un punto de control o instantánea del estado de tu proyecto en un momento dado. A este punto de control le suele acompañar un mensaje que identifique el porqué de dicho commit, utilizando el flag -m.
3. Por último, enviamos nuestros cambios al repo remoto con git push.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git add .

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git commit -m "Primer commit de local a remoto"
[master 9638b10] Primer commit de local a remoto
 2 files changed, 1 insertion(+), 1 deletion(-)
 create mode 100644 main.py

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ git push origin main
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 324 bytes | 81.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0), pack-reused 0
To github.com:pablodelflo/biblioteca-personal.git
   9638b10..b985d32  main -> main

Y listo. Si vamos a nuestro repo de GitHub, veremos estos cambios que hemos realizado.

EXTRA WSL: errores con SSH y GitHub

Aunque he probado este procedimiento en varios equipos y distros, me encontré en un par de ellos con un error en WSL referentes a la autenticación SSH y GitHub. Así que los dejé anotados para ofrecer una solución en caso de que te salga este problema.

Al intentar hacer la prueba de conexión con GitHub, me saltó este error:

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh -T git@github.com
Warning: Permanently added the ECDSA host key for IP address '140.82.121.3' to the list of known hosts.
git@github.com: Permission denied (publickey).

Vaya, permiso denegado. Pues vamos a arreglarlo. Primero, intento listar las claves SSH, pero también daba error:

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh-add -l
Could not open a connection to your authentication agent.

Vale, esto quiere decir que no hay ningún agente SSH corriendo, así que vamos a levantarlo manualmente.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ eval "$(ssh-agent -s)"
Agent pid 98

Ahora está levantado y tiene un pid asociado. Ahora, agregamos nuestra clave SSH al agente para que no nos pida la password en cada ejecución.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh-add ~/.ssh/pdf_wsl250519
Identity added: /home/pablodelgado/.ssh/pdf_wsl250519 (pabloj.df@gmail.com)

¡Listo! Si ahora listamos las claves e intentamos conectar a GitHub, veremos que el proceso es correcto.

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh-add -l
256 SHA256:A/lZpXXXXXXXXXxxxxxxxxxXXXXXXXXXXXP6oI pabloj.df@gmail.com (ED25519)

[pablodelgado@DESKTOP-UU1NMET biblioteca]$ ssh -T git@github.com
Hi pablodelflo! You've successfully authenticated, but GitHub does not provide shell access.

Conclusión

¡Y esto es todo!

De esta forma podemos conectar una carpeta local a un repositorio de GitHub, para así poder usar el control de versiones git en nuestros desarrollos de código.

Repasa todos los pasos que hemos hecho y asimila conceptos como: generar una clave SSH, asignarla a tu perfil de GitHub, inicializar un repo local y enlazarlo con uno remoto.

Prometo una próxima entrada profundizando más en git y en sus comandos básicos.

¿Qué te ha parecido esta entrada? Recuerda que puedes dejarme tus impresiones y/o dudas justo aquí abajo, en comentarios. Y, como siempre te pido, comparte esta entrada en RRSS para que más gente conozca mi web.

Y ya, para redondear el asunto, si quieres suscribirte a mi newsletter para no perderte ninguna novedad de la web, me haces la persona más feliz del universo. Te prometo que solo recibirás la notificación de que he publicado una nueva entrada, ¡nada más!

Hasta la próxima, ¡un saludo!