git remote: conecta tu repo local con GitHub

Tienes tus commits guardados en el portátil. Si se te rompe el disco, los pierdes todos, y tu compañera no puede ver nada de lo que llevas hecho. Conectar tu repo local con GitHub resuelve las dos cosas a la vez, y son tres comandos. Aquí te explico qué es un remoto, qué hace exactamente git remote conectar github cuando copias esa línea de un tutorial, y por qué git push a secas te pide un --set-upstream la primera vez.

Para seguir este post necesitas saber usar git init, git add y git commit: tener un repo local con al menos un commit hecho. Si ya tienes eso, ya has hecho la parte difícil. Conectarlo con GitHub es el primer paso del flujo de trabajo en equipo con Git y GitHub, y el resto de este post lo desmonta comando a comando.

¿Qué es un remoto en Git?

Un remoto es una copia de tu repositorio que vive en un servidor, normalmente en GitHub. Piensa en tu repo local como la carpeta de tu portátil donde trabajas, y en el remoto como una copia de seguridad compartida en internet a la que tú y tu equipo podéis subir y de la que podéis bajar.

Cuando haces git init y empiezas a guardar commits, todo eso solo existe en tu máquina. Git no habla con ningún servidor por su cuenta. Para que tus commits salgan del portátil tienes que decirle a Git a qué servidor quieres mandarlos, y ese servidor es el remoto.

GitHub no es lo único que puede alojar un remoto. GitLab, Bitbucket o un servidor propio también valen. Pero como GitHub es lo más común para empezar, es el que uso en los ejemplos.

Aquí hay dos direcciones posibles. Subir tu repo local a GitHub por primera vez es lo que vemos en este post. Si el repo ya existe en GitHub y lo que quieres es traértelo a tu máquina, eso es clonar un repositorio, el camino inverso, y git clone te configura el remoto solo.

¿Qué hace git remote add origin?

git remote add origin <url> registra la dirección de tu remoto y le pone el nombre corto origin. No sube ni un solo commit. Solo apunta en la configuración de tu repo local: “cuando diga origin, me refiero a esta URL”. Esta parte confunde a mucha gente, así que quédate con ella: añadir el remoto y subir el código son dos pasos distintos.

# Registra el remoto de GitHub con el nombre corto "origin".
# Cambia "ana" por tu usuario y "proyecto" por tu repo.
git remote add origin https://github.com/ana/proyecto.git

¿Por qué origin? Es solo una convención. Git no obliga a llamarlo así, pero por costumbre el primer remoto (el sitio de donde salió o a donde va tu repo) se llama origin. Podrías llamarlo github o casa y funcionaría igual. Casi todos los tutoriales usan origin, y seguir la convención te ahorra sorpresas.

La URL puede venir en dos formatos, y GitHub te muestra los dos en el botón verde “Code” de tu repositorio.

	HTTPS	SSH
Formato	https://github.com/ana/proyecto.git	git@github.com:ana/proyecto.git
Autenticación	usuario y un token de acceso personal	un par de claves SSH que configuras una vez
Cuándo usarla	lo más rápido para empezar tu primer repo	cómodo a largo plazo si ya tienes las claves puestas

Si estás empezando, usa HTTPS. Es copiar y pegar la URL y listo. Cuando te canses de meter el token, montas SSH, pero eso es otro tema.

¿Cómo compruebo que quedó bien conectado?

Con git remote -v. Ese comando lista los remotos que tienes configurados y te enseña la URL de cada uno, así confirmas que no te has equivocado antes de intentar subir nada.

git remote -v
# origin  https://github.com/ana/proyecto.git (fetch)
# origin  https://github.com/ana/proyecto.git (push)

Fíjate en que salen dos líneas para origin: una marcada (fetch) y otra (push). Fetch es traer cambios del remoto, push es enviarlos. Git te muestra las dos porque, aunque casi siempre apuntan al mismo sitio, se pueden configurar por separado. Si ves tu URL en las dos líneas y está bien escrita, el remoto quedó conectado.

Si git remote -v no devuelve nada, es que el add no llegó a ejecutarse o lo hiciste en otra carpeta. Y si ves una URL con una errata, tranquila, se arregla sin borrar nada, lo vemos en los errores comunes.

¿Qué hace git push -u origin main?

git push -u origin main hace dos cosas: sube tu rama main al remoto origin y, gracias al -u, deja memorizado que tu main local va emparejada con la main de GitHub. Este es el primer push, el que de verdad manda tus commits a internet.

# Sube la rama main al remoto origin y guarda la asociación (-u).
git push -u origin main

El -u es la forma corta de --set-upstream. Sin él, cada vez que quisieras subir tendrías que escribir git push origin main entero, repitiendo el remoto y la rama. Con -u puesto una sola vez, Git anota en su configuración que tu main sigue a la main de origin, y a partir de ahí te basta git push o git pull a secas: Git ya sabe a dónde. Eso es la rama upstream: la asociación entre tu rama local y la del remoto.

¿Y por qué main y no otra cosa? Es el nombre de tu rama principal. GitHub crea los repos con main por defecto desde hace años. Si tu rama se llama distinto, cámbialo en el comando por el nombre real (lo ves con git branch).

Solo pones el -u en el primer push de cada rama. Una vez guardada la asociación, ya no hace falta repetirlo. Si algún día creas una rama nueva y la subes por primera vez, vuelves a usar -u para esa rama concreta.

Antes de seguir, prueba tú a ordenar los pasos de conectar un repo local con GitHub en este ejercicio interactivo:

Cargando ejercicio...

¿Qué diferencia hay entre origin y origin/main?

origin es el remoto entero (el servidor); origin/main es una rama concreta dentro de ese remoto, vista desde tu máquina. Se parecen al leerlas, pero son cosas distintas, y entender la diferencia te evita mucha confusión más adelante.

origin es el nombre corto de la URL del servidor. Cuando escribes git push origin main, el origin de ahí es el destino: el GitHub al que subes.

origin/main es otra cosa: es la rama de seguimiento remoto. Es la foto que Git guarda en tu máquina de dónde estaba la main del remoto la última vez que sincronizaste. No se actualiza sola. Si tu compañera sube un commit a GitHub, tu origin/main no se entera hasta que tú traes cambios. Por eso a veces tu origin/main está “atrasada” respecto a lo que hay de verdad en el servidor.

	origin	origin/main
Qué es	el remoto: el nombre corto de la URL del servidor	la rama de seguimiento remoto: tu foto local de la main del remoto
Cuándo cambia	cuando editas la URL con git remote set-url	cuando sincronizas con fetch, pull o push
Ejemplo	https://github.com/ana/proyecto.git	commit a1b2c3d, la última posición conocida de main en GitHub

Actualizar esa foto es justo lo que hacen git fetch y git pull: traen del servidor la posición real y mueven tu origin/main al día. Una vez tienes el remoto conectado, sincronizar es el siguiente paso natural.

Errores comunes al conectar el remoto

error: remote origin already exists.

Este es el más frecuente, y sale cuando intentas git remote add origin ... pero ya tenías un origin puesto (a veces porque el tutorial te lo hizo poner antes y no te acordabas). El mensaje exacto de Git es:

git remote add origin https://github.com/ana/proyecto.git
# error: remote origin already exists.

No borres el repo ni empieces de cero. Si la URL vieja está mal, la cambias con set-url. Si prefieres quitar el remoto y volver a añadirlo, git remote remove origin lo elimina limpiamente.

# Opción A: cambiar la URL del origin que ya existe.
git remote set-url origin https://github.com/ana/proyecto.git

# Opción B: quitarlo y volver a añadirlo.
git remote remove origin
git remote add origin https://github.com/ana/proyecto.git

La URL con el usuario o el repo mal escritos

Aquí Git no se queja al hacer el add, porque no comprueba que la URL exista hasta que intentas subir. Escribes git remote add origin con una errata en tu nombre de usuario, git remote -v te enseña la URL equivocada tan tranquilo, y solo al hacer push falla la autenticación o te dice que el repositorio no existe. Por eso conviene revisar la salida de git remote -v antes del primer push. La solución es la misma de arriba: git remote set-url origin <url-correcta>.

Updates were rejected por historia divergente

Si al hacer push ves algo como un ! [rejected] seguido de “Updates were rejected because the remote contains work that you do not have locally” (git lo muestra en varias líneas, con algún hint: incluido), significa que en GitHub hay commits que tú no tienes en local. Suele pasar cuando creaste el repo en GitHub con un README o un .gitignore marcados en la web: el remoto arrancó con un commit que tu portátil no conoce.

La reacción de mucha gente es forzar el push para “ganar”, y ese es el error de verdad. Forzar sobrescribe en el servidor el trabajo que había, y si era de tu compañera, lo pierdes. Lo correcto es traer primero lo que hay en el remoto con git pull, resolver si hace falta, y volver a subir. En el rarísimo caso de que algún día necesites forzar, --force-with-lease es más seguro que --force porque aborta si el remoto cambió por debajo, pero para conectar tu repo por primera vez casi nunca vas a necesitar forzar nada.

Olvidar el -u en el primer push

No rompe nada, solo es incómodo. Si haces git push origin main sin -u, sube igual, pero no guarda la asociación, así que la próxima vez git push a secas te volverá a pedir que digas el remoto y la rama. Se arregla ejecutando una vez git push -u origin main (o git branch --set-upstream-to=origin/main) para dejar la rama upstream anotada.

Checklist de conexión

• Tienes un repo local con al menos un commit (git log muestra algo)
• Copiaste la URL correcta desde el botón “Code” de tu repositorio en GitHub
• Ejecutaste git remote add origin <url> sin errores
• git remote -v muestra tu URL en las líneas (fetch) y (push)
• El primer envío fue git push -u origin main con el -u puesto
• Tras el push, ves tus archivos en la página del repo en GitHub

Conectar el remoto es el primer paso de trabajar con Git en serio. Si quieres practicar todo el flujo (ramas, push, pull, resolver conflictos) con ejercicios guiados en lugar de tutoriales sueltos, lo tienes montado paso a paso en el curso Git de cero a profesional.

Fuentes

1. git remote, documentación oficial de Git: comportamiento de add, -v, set-url y remove, y el estado de salida al añadir un remoto que ya existe.
2. git push, documentación oficial de Git: qué hace -u/--set-upstream y el formato de los mensajes de rechazo del remoto.

Preguntas Frecuentes

¿Puedo tener más de un remoto?

Sí. Un repo puede tener varios remotos con nombres distintos, por ejemplo origin apuntando a tu GitHub y upstream apuntando al repositorio original que copiaste. Añades cada uno con git remote add <nombre> <url> y los ves todos con git remote -v. En tu primer proyecto casi siempre tendrás solo origin, pero es útil saber que el límite no es uno.

¿Qué pasa si me equivoqué en la URL al conectar el remoto?

No pasa nada grave y no hace falta borrar el repo. Cambias la URL con git remote set-url origin <url-correcta> y compruebas el resultado con git remote -v. Git no valida la URL al añadirla, así que una errata solo se nota al intentar subir; por eso conviene revisar git remote -v antes del primer push.

¿El -u hay que ponerlo siempre?

No. El -u solo se pone la primera vez que subes una rama, porque su trabajo es guardar la asociación entre tu rama local y la del remoto. Una vez hecho eso, git push y git pull a secas ya saben a dónde ir. Si creas una rama nueva más adelante, vuelves a usar -u la primera vez que subas esa rama concreta.

¿origin es obligatorio como nombre del remoto?

No, es una convención. Puedes llamar a tu remoto como quieras al hacer git remote add <nombre> <url>. Se usa origin porque casi todo el mundo lo hace y los tutoriales lo dan por hecho, así que seguir la costumbre te evita tener que traducir cada comando a tu nombre inventado.

Un concepto nuevo cada semana

Suscribirme