Conectar Git con GitHub

Git guarda tus cambios en tu computadora, pero para respaldarlos en la nube y colaborar con otras personas necesitás vincularlo con GitHub. En este artículo vas a aprender a configurar la autenticación y conectar tu repositorio local con uno remoto, paso a paso

1. ¿Qué significa conectar Git con GitHub?

Conectar GIT con GitHub significa vincular el REPOSITORIO local de nuestro ordenador con un repositorio remoto alojado en GitHub. De esta manera, podemos trabajar y controlar las diferentes versiones de nuestro proyecto utilizando Git y, posteriormente, enviar esos cambios a GitHub para almacenarlos y compartirlos.

Por ejemplo, podemos tener un proyecto en nuestro ordenador:

mi-proyecto/
├── index.html
├── style.css
└── script.js

Si inicializamos Git dentro de esa carpeta, tendremos un repositorio local. Git se encargará de registrar los cambios que realicemos mediante commits.

Posteriormente, podemos vincular ese repositorio local con un repositorio remoto de GitHub:

Ordenador                         GitHub
─────────                         ──────

Repositorio local  ────────────►  Repositorio remoto
                       git push

A partir de ese momento, ambos repositorios estarán relacionados y podremos utilizar diferentes comandos para intercambiar información entre ellos.

Por ejemplo:

• git push → envía nuestros commits desde el repositorio local hacia GitHub.
• git pull → descarga cambios de GitHub y los integra en nuestro repositorio local.
• git fetch → consulta y descarga información del repositorio remoto sin integrar automáticamente esos cambios.
• git remote → permite consultar y administrar la conexión con los repositorios remotos.

Es importante entender que Git y GitHub no son lo mismo. Git es el sistema de control de versiones que utilizamos para gestionar nuestro proyecto, mientras que GitHub es una plataforma que permite alojar repositorios Git de forma remota.

Por lo tanto, cuando hablamos de conectar Git con GitHub, estamos estableciendo una comunicación entre nuestro repositorio local y un repositorio remoto, permitiendo que podamos enviar y recibir información entre ambos.

2. Diferentes maneras de conectar Git con GitHub

No existe una única forma de conectar nuestro proyecto local con GitHub. Podemos comenzar el proceso desde GitHub o desde Visual Studio Code, dependiendo de cómo queramos crear el repositorio remoto.

En ambos casos, el objetivo final es el mismo: tener nuestro repositorio local de Git vinculado con un repositorio remoto de GitHub, para poder enviar y recibir cambios entre ambos.

Opción 1: Crear primero el repositorio en GitHub

Una posibilidad es comenzar directamente desde GitHub. En este caso, primero creamos un repositorio en nuestra cuenta de GitHub y posteriormente vinculamos ese repositorio remoto con el proyecto que tenemos en nuestro ordenador.

El proceso, de forma general, sería:

Proyecto local en VS Code
          ↓
Repositorio local de Git
          ↓
Repositorio creado en GitHub
          ↓
Conectar ambos repositorios
          ↓
Enviar los archivos a GitHub

Por ejemplo, podemos tener nuestro proyecto en VS Code:

mi-proyecto/
├── index.html
├── style.css
└── script.js

Y crear en GitHub un repositorio llamado mi-proyecto. Después conectaremos ambos repositorios y podremos utilizar git push para enviar nuestros commits a GitHub.

Si todavía no sabemos cómo crear un repositorio desde GitHub, podemos consultar el artículo Crear un repositorio en GitHub, donde explicamos este procedimiento paso a paso.

Una vez creado el repositorio remoto, continuaremos con la conexión desde nuestro proyecto local.

Opción 2: Crear y publicar el repositorio desde Visual Studio Code

La segunda posibilidad es comenzar directamente con nuestro proyecto local en Visual Studio Code.

En este caso, no necesitamos crear previamente el repositorio desde la página web de GitHub. Podemos inicializar Git en nuestro proyecto y utilizar las herramientas de VS Code para publicar el proyecto en GitHub.

De forma general, el proceso sería:

Proyecto local en VS Code
          ↓
Inicializar Git
          ↓
Publicar en GitHub
          ↓
VS Code crea el repositorio remoto
          ↓
Repositorio local ↔ GitHub

En este caso, el proyecto ya contiene nuestros archivos. Lo que hacemos desde VS Code es publicar ese repositorio local en GitHub, creando el repositorio remoto y estableciendo la relación entre ambos.

Esta opción puede resultar especialmente cómoda cuando estamos desarrollando un proyecto directamente desde VS Code y queremos subirlo a GitHub sin tener que crear primero el repositorio desde la página web.

¿Cuál de las dos opciones debemos utilizar?

Las dos son válidas. La diferencia principal está en dónde comenzamos el proceso.

Si creamos primero el repositorio desde GitHub, posteriormente conectamos nuestro repositorio local con ese repositorio remoto.

Si comenzamos desde VS Code, podemos partir de nuestro proyecto local y publicarlo directamente en GitHub.

En ambos casos terminaremos teniendo una estructura similar:

        REPOSITORIO LOCAL
               ↕
          Git + VS Code
               ↕
        REPOSITORIO REMOTO
             GitHub

En los siguientes apartados veremos cada una de estas alternativas paso a paso, para que podamos elegir el método que mejor se adapte a nuestro flujo de trabajo.

3. Crear y conectar el repositorio desde VS Code

Como dijimos, no necesitamos crear previamente el repositorio desde la página web de GitHub. Podemos partir de una carpeta que ya contiene nuestro proyecto, convertirla en un repositorio Git y posteriormente publicarla en GitHub desde VS Code.

Visual Studio Code dispone de una integración con GitHub que permite publicar un repositorio local directamente. Al utilizar esta opción, VS Code puede crear el repositorio en GitHub, configurarlo como repositorio remoto y enviar nuestros commits.

El proceso general será:

Proyecto local
      ↓
Inicializar Git
      ↓
Preparar los archivos
      ↓
Crear el commit
      ↓
Publicar en GitHub
      ↓
VS Code crea el repositorio remoto
      ↓
Repositorio local ↔ GitHub

Paso 1. Abrir el proyecto en Visual Studio Code

Lo primero que debemos hacer es abrir en VS Code la carpeta que contiene nuestro proyecto.

Por ejemplo:

mi-proyecto/
├── index.html
├── style.css
└── script.js

Desde VS Code podemos seleccionar:

File → Open Folder…

y elegir la carpeta de nuestro proyecto.

También podemos abrir directamente la carpeta desde el explorador de archivos y seleccionar Abrir con Visual Studio Code, dependiendo de cómo tengamos configurado nuestro sistema.

Paso 2. Abrir el panel Control de código fuente

Una vez abierto el proyecto, debemos acceder al panel Source Control o Control de código fuente.

Podemos hacerlo seleccionando el icono de control de código fuente en la barra lateral de VS Code.

También podemos utilizar el atajo:

Ctrl + Shift + G

Este panel nos permite trabajar con Git desde la interfaz gráfica de VS Code, incluyendo preparar archivos, crear commits y sincronizar nuestro repositorio.

Paso 3. Inicializar el repositorio Git

Si nuestra carpeta todavía no es un repositorio Git, VS Code mostrará la opción:

Initialize Repository

Al seleccionarla, VS Code ejecutará internamente la inicialización de Git para esa carpeta.

Es equivalente a ejecutar desde la terminal:

git init

A partir de ese momento, nuestro proyecto local se convierte en un repositorio Git.

Podemos comprobarlo porque VS Code comenzará a mostrar los archivos que Git está siguiendo o que todavía no han sido agregados al repositorio.

Paso 4. Revisar los archivos del proyecto

Después de inicializar Git, los archivos que todavía no están siendo seguidos por Git aparecerán en el panel Control de código fuente.

Por ejemplo:

Changes

U  index.html
U  style.css
U  script.js
Lenguaje del código: CSS (css)

La letra U indica que son archivos que Git todavía no está siguiendo.

Antes de realizar el primer commit, es recomendable revisar qué archivos queremos incluir en nuestro repositorio.

Por ejemplo, si tenemos archivos que no queremos subir, podemos incluirlos en un archivo .gitignore.

Paso 5. Preparar los archivos para el commit

Para preparar los archivos podemos utilizar el botón + que aparece junto a cada archivo.

También podemos utilizar el botón + que aparece junto a la sección Changes para preparar todos los cambios.

Cuando los archivos están preparados, pasarán de:

Changes

a:

Staged Changes

Este proceso corresponde al concepto de staging area de Git.

Desde la terminal sería equivalente a:

git add .

VS Code permite realizar esta operación desde su interfaz gráfica, pero el funcionamiento interno sigue siendo el de Git.

Paso 6. Crear el primer commit

Una vez preparados los archivos, debemos crear nuestro primer commit.

En el cuadro de mensaje de commit podemos escribir, por ejemplo:

Primer commit

Después seleccionamos:

Commit

Este commit guarda una versión de nuestro proyecto en el historial local de Git.

También podríamos realizar esta misma operación desde la terminal:

git commit -m "Primer commit"
Lenguaje del código: JavaScript (javascript)

Por lo tanto, en este punto tenemos:

Proyecto local
      ↓
Repositorio Git local
      ↓
Primer commit

Todavía no hemos creado el repositorio remoto en GitHub.

Paso 7. Publicar el repositorio en GitHub

Ahora llega el paso que diferencia este procedimiento del otro método (cuando el repositorio esta previamente creado).

Dentro del panel Control de código fuente, VS Code puede mostrar la opción:

Publish to GitHub

Esta opción permite publicar nuestro repositorio local directamente en GitHub.

Al seleccionarla, VS Code nos pedirá iniciar sesión en GitHub si todavía no lo hemos hecho.

Paso 8. Iniciar sesión en GitHub desde VS Code

Si es la primera vez que utilizamos la integración con GitHub, VS Code puede solicitar que iniciemos sesión.

El proceso normalmente nos lleva al navegador para autorizar la conexión con nuestra cuenta de GitHub y posteriormente regresar a VS Code.

VS Code incorpora autenticación para las operaciones Git con GitHub, por lo que no necesitamos instalar una extensión adicional únicamente para realizar operaciones básicas como clonar, hacer push o publicar un repositorio.

Una vez autenticados, podremos continuar con la publicación.

Paso 9. Elegir el nombre y la visibilidad del repositorio

VS Code nos permitirá elegir algunas opciones para el nuevo repositorio.

Entre ellas podemos seleccionar si queremos que el repositorio sea:

• Public: cualquier persona podrá encontrar y consultar el repositorio.
• Private: solamente las personas autorizadas podrán acceder a él.

También podremos indicar el nombre del repositorio.

Por ejemplo:

mi-proyecto

Es recomendable utilizar un nombre que identifique claramente el proyecto.

Paso 10. Seleccionar los archivos que queremos publicar

Durante el proceso de publicación, VS Code permite seleccionar qué archivos queremos incluir en el commit inicial que será enviado a GitHub.

Por eso es importante revisar previamente nuestro proyecto y asegurarnos de no estar incluyendo información que debería mantenerse privada.

Por ejemplo, nunca deberíamos publicar accidentalmente:

.env
passwords.txt
configuracion-secreta.txt
Lenguaje del código: CSS (css)

Para evitar este tipo de situaciones, podemos utilizar un archivo .gitignore.

Paso 11. VS Code crea el repositorio en GitHub

Después de confirmar la publicación, VS Code se encarga de crear el repositorio remoto en nuestra cuenta de GitHub.

Por ejemplo:

GitHub
└── mi-proyecto

Aquí está una de las principales ventajas de este método: no tuvimos que entrar previamente a GitHub para crear el repositorio.

VS Code realiza el proceso de publicación y configura el repositorio remoto.

Paso 12. VS Code conecta el repositorio local con GitHub

Una vez creado el repositorio remoto, VS Code configura la conexión entre nuestro repositorio local y GitHub.

Conceptualmente, terminamos con:

┌─────────────────────┐
│  Repositorio local  │
│       Git           │
└──────────┬──────────┘
           │
           │ conexión remota
           ▼
┌─────────────────────┐
│       GitHub        │
│ Repositorio remoto  │
└─────────────────────┘

En términos de Git, nuestro repositorio local tendrá un repositorio remoto configurado, normalmente identificado con el nombre:

origin

A partir de este momento podemos consultar el remoto desde la terminal utilizando:

git remote -v

Deberíamos obtener información relacionada con el repositorio de GitHub que acabamos de publicar.

Paso 13. Comprobar el repositorio en GitHub

Finalmente, podemos entrar en nuestra cuenta de GitHub y abrir el nuevo repositorio.

Allí deberíamos encontrar los archivos que hemos publicado.

Por ejemplo:

mi-proyecto
├── index.html
├── style.css
└── script.js
Lenguaje del código: CSS (css)

Esto confirma que nuestro proyecto local ha sido publicado en GitHub.

Paso 14. ¿Qué hacemos después de conectar el repositorio?

A partir de este momento, el flujo de trabajo habitual será:

Modificar archivos
       ↓
Revisar cambios
       ↓
Stage
       ↓
Commit
       ↓
Push
       ↓
GitHub

Por ejemplo, si posteriormente modificamos index.html, podemos abrir nuevamente el panel Control de código fuente, revisar el cambio, preparar el archivo y crear un nuevo commit.

Después podremos seleccionar Push o Sync Changes para enviar nuestros commits a GitHub. VS Code ofrece estas acciones directamente desde su interfaz.

También podemos realizar el proceso desde la terminal:

git add .
git commit -m "Actualizar proyecto"
git push
Lenguaje del código: JavaScript (javascript)

¿Qué hemos conseguido con este procedimiento?

Al comenzar con un proyecto local y utilizar Publish to GitHub, hemos realizado varias operaciones:

1. Creamos un repositorio Git local.
2. Preparamos los archivos.
3. Creamos nuestro primer commit.
4. Iniciamos sesión en GitHub desde VS Code.
5. Creamos un repositorio remoto en GitHub.
6. Conectamos el repositorio local con el remoto.
7. Publicamos nuestros commits en GitHub.

Por lo tanto, el resultado final es:

        PROYECTO LOCAL
              │
              │ Git
              ▼
     REPOSITORIO LOCAL
              │
              │ push
              ▼
          GITHUB
              │
              ▼
     REPOSITORIO REMOTO

La principal diferencia respecto al método anterior es dónde comenzamos el proceso. En este caso comenzamos con nuestro proyecto local en VS Code y desde allí lo publicamos directamente en GitHub, en lugar de crear primero el repositorio remoto desde la página web de GitHub.

4. Conectar repositorio local a un repositorio remoto

En este punto del curso ya sabemos cómo crear un repositorio remoto en GitHub y también conocemos cómo crear y publicar un repositorio desde Visual Studio Code. Por eso, en este apartado no vamos a repetir el proceso de creación del repositorio remoto.

Aquí nos vamos a concentrar en algo fundamental: cómo tomar un proyecto que tenemos en nuestro ordenador, convertirlo en un repositorio Git local, conectarlo con un repositorio remoto que ya existe en GitHub y enviar nuestros archivos desde el repositorio local hacia GitHub paso a paso.

El proceso completo será:

Proyecto local
      ↓
Inicializar Git
      ↓
Preparar archivos
      ↓
Crear commit
      ↓
Conectar con GitHub
      ↓
Enviar archivos
      ↓
Repositorio remoto

Paso 1. Tener preparado el proyecto local

Comenzamos con un proyecto que tenemos almacenado en nuestro ordenador.

Por ejemplo:

mi-proyecto/
├── index.html
├── style.css
└── script.js

Abrimos esta carpeta desde Visual Studio Code.

Es importante que la terminal de VS Code se encuentre ubicada dentro de la carpeta principal del proyecto.

Podemos abrirla desde:

Terminal → New Terminal

o utilizando:

Ctrl + Ñ

Paso 2. Comprobar si el proyecto ya utiliza Git

Antes de inicializar Git, podemos comprobar el estado del proyecto:

git status

Si la carpeta todavía no es un repositorio Git, veremos un mensaje indicando que no es un repositorio.

En ese caso, debemos inicializar Git.

NOTA! Si el proyecto ya es un repositorio Git porque anteriormente ejecutamos git init, no es necesario volver a ejecutar este comando.

Paso 3. Inicializar Git en el proyecto

Si todavía no tenemos un repositorio Git local, ejecutamos:

git init

Este comando crea la carpeta oculta .git dentro de nuestro proyecto.

Por ejemplo:

mi-proyecto/
├── .git/
├── index.html
├── style.css
└── script.js

A partir de este momento, Git comenzará a controlar las versiones de nuestro proyecto.

Sin embargo, todavía no hemos conectado este repositorio con GitHub.

Paso 4. Comprobar los archivos del proyecto

Ahora podemos utilizar:

git status

Git nos mostrará los archivos que todavía no están siendo seguidos.

Por ejemplo:

Untracked files:
  index.html
  style.css
  script.js
Lenguaje del código: CSS (css)

Esto significa que los archivos existen en nuestro proyecto, pero Git todavía no los ha incluido en el área de preparación.

Paso 5. Agregar los archivos al área de preparación

Para preparar todos los archivos podemos utilizar:

git add .

El punto indica que queremos agregar los cambios correspondientes al directorio actual.

Después podemos comprobar nuevamente el estado:

git status

Ahora los archivos aparecerán como preparados para realizar un commit.

En este momento tenemos:

Working Directory
       ↓
   git add .
       ↓
Staging Area

Paso 6. Crear el primer commit

Una vez preparados los archivos, debemos guardarlos en el historial de Git mediante un commit.

Por ejemplo:

git commit -m "Primer commit"
Lenguaje del código: JavaScript (javascript)

El commit representa una versión concreta de nuestro proyecto.

Nuestro repositorio local ahora tiene una estructura conceptual similar a:

Repositorio local
       │
       └── Primer commit

Todavía falta establecer qué repositorio remoto de GitHub utilizaremos.

Paso 7. Obtener la URL del repositorio remoto de GitHub

Como el repositorio remoto ya fue creado previamente en GitHub, ahora necesitamos obtener su dirección.

Desde la página del repositorio en GitHub podemos seleccionar:

Code

y copiar la URL que corresponda al método de conexión que queremos utilizar.

Por ejemplo, mediante HTTPS:

https://github.com/usuario/mi-proyecto.git
Lenguaje del código: JavaScript (javascript)

También podemos utilizar SSH:

[email protected]:usuario/mi-proyecto.git

La elección entre HTTPS y SSH dependerá del método de autenticación que hayamos configurado previamente.

Paso 8. Conectar el repositorio local con GitHub

Ahora debemos indicarle a Git dónde se encuentra nuestro repositorio remoto.

Para ello utilizamos:

git remote add origin URL_DEL_REPOSITORIO

Por ejemplo, utilizando HTTPS:

git remote add origin https://github.com/usuario/mi-proyecto.git
Lenguaje del código: JavaScript (javascript)

O utilizando SSH:

git remote add origin [email protected]:usuario/mi-proyecto.git

Aquí estamos creando una conexión entre:

Repositorio local
       │
       │ origin
       ▼
Repositorio remoto
     GitHub

¿Qué significa origin?

origin es simplemente el nombre que normalmente utilizamos para identificar el repositorio remoto principal.

Por ejemplo:

git remote add origin https://github.com/usuario/mi-proyecto.git
Lenguaje del código: JavaScript (javascript)

No significa que origin sea una palabra especial de GitHub ni que debamos utilizar obligatoriamente ese nombre. Es un nombre convencional que Git utiliza habitualmente para identificar el repositorio remoto principal.

Paso 9. Comprobar que el repositorio remoto está conectado

Antes de enviar nuestros archivos, podemos comprobar que Git tiene correctamente configurado el repositorio remoto:

git remote -v

Podremos obtener algo similar a:

origin  https://github.com/usuario/mi-proyecto.git (fetch)
origin  https://github.com/usuario/mi-proyecto.git (push)
Lenguaje del código: JavaScript (javascript)

Esto nos confirma que nuestro repositorio local conoce el repositorio remoto de GitHub.

Paso 10. Comprobar el nombre de la rama principal

Antes de realizar el primer push, es recomendable comprobar el nombre de nuestra rama actual:

git branch

Podríamos encontrar algo como:

* master

o:

* main

Actualmente main es el nombre más habitual para la rama principal.

Si queremos utilizar main, podemos cambiar el nombre de nuestra rama actual mediante:

git branch -M main

Ahora nuestra rama principal será:

main

Paso 11. Enviar los archivos al repositorio remoto

Llegamos finalmente al objetivo principal de este apartado: enviar los archivos y commits del repositorio local a GitHub.

Para hacerlo utilizamos:

git push -u origin main

Este comando le indica a Git que queremos enviar nuestra rama local main hacia la rama main del repositorio remoto origin.

Podemos representarlo así:

Repositorio local                 GitHub
       │                            │
       │        git push            │
       ├───────────────────────────►│
       │                            │
       │        archivos + commits │
       └───────────────────────────►│

¿Qué significa cada parte de git push -u origin main?

El comando:

git push -u origin main

está compuesto por varias partes:

git push

Indica que queremos enviar nuestros commits al repositorio remoto.

origin

Es el nombre que le hemos asignado al repositorio remoto.

main

Es la rama local que queremos enviar.

-u

Establece una relación de seguimiento entre nuestra rama local y la rama remota correspondiente.

Por eso, después del primer push, normalmente podremos utilizar simplemente:

git push

sin tener que volver a escribir:

git push -u origin main

Paso 12. Autenticarnos con GitHub

Dependiendo del método que hayamos elegido para conectar el repositorio remoto, Git puede necesitar autenticarnos ante GitHub.

Si utilizamos HTTPS, la autenticación puede realizarse mediante un Personal Access Token.

Si utilizamos SSH, Git utilizará las claves SSH que hayamos configurado previamente.

Por eso es importante que el método de autenticación esté correctamente configurado antes de intentar realizar el push.

Si todo está configurado correctamente, Git podrá comunicarse con GitHub y enviar nuestros commits.

Paso 13. Comprobar los archivos en GitHub

Después de ejecutar correctamente:

git push -u origin main

podemos regresar a GitHub y actualizar la página del repositorio.

Ahora deberían aparecer nuestros archivos:

mi-proyecto
├── index.html
├── style.css
└── script.js
Lenguaje del código: CSS (css)

Lo que antes teníamos únicamente en nuestro ordenador ahora también está disponible en el repositorio remoto de GitHub.

¿Qué hemos hecho exactamente?

Aunque el objetivo era simplemente enviar los archivos a GitHub, en realidad hemos realizado varios pasos diferentes:

1. Proyecto local
       ↓
2. git init
       ↓
3. git add .
       ↓
4. git commit
       ↓
5. git remote add origin
       ↓
6. git branch -M main
       ↓
7. git push
       ↓
8. Repositorio remoto en GitHub

Es importante entender esta secuencia porque git push no toma directamente archivos de nuestro ordenador y los copia a GitHub.

Git trabaja con commits.

Primero debemos:

Archivos
   ↓
git add
   ↓
Staging Area
   ↓
git commit
   ↓
Repositorio local

Y después:

Repositorio local
       ↓
   git push
       ↓
Repositorio remoto

Por eso, cuando utilizamos git push, lo que estamos enviando principalmente son los commits del repositorio local que todavía no se encuentran en el repositorio remoto.

¿Qué hacemos una vez enviados los archivos a GitHub?

Una vez que el repositorio local ya está conectado con GitHub, el procedimiento para enviar nuevos cambios es mucho más sencillo.

Supongamos que modificamos index.html.

Primero podemos comprobar los cambios:

git status

Después agregamos los archivos modificados:

git add .

Creamos un nuevo commit:

git commit -m "Actualizar página principal"
Lenguaje del código: JavaScript (javascript)

Y finalmente enviamos ese commit a GitHub:

git push

El flujo habitual será entonces:

Modificar archivos
       ↓
git status
       ↓
git add .
       ↓
git commit
       ↓
git push
       ↓
GitHub

Este será uno de los flujos de trabajo más utilizados durante nuestro día a día con Git y GitHub.

Resumen del procedimiento

Si queremos recordar únicamente los comandos principales utilizados para conectar un proyecto local con un repositorio remoto de GitHub que ya existe, podemos resumirlos así:

git init
git add .
git commit -m "Primer commit"
git remote add origin URL_DEL_REPOSITORIO
git branch -M main
git push -u origin main
Lenguaje del código: JavaScript (javascript)

Después de realizar esta configuración inicial, para enviar nuevos cambios normalmente será suficiente con:

git add .
git commit -m "Descripción de los cambios"
git push
Lenguaje del código: JavaScript (javascript)

De esta manera, nuestro proyecto local queda conectado con GitHub y podemos utilizar el repositorio remoto como una copia compartida y centralizada de nuestro historial de Git.

5. Conflictos al conectar Git con GitHub

Cuando conectamos por primera vez un repositorio local de Git con un repositorio remoto de GitHub, podemos encontrarnos con algunos conflictos al intentar enviar nuestros archivos mediante git push.

Uno de los casos más habituales ocurre cuando el repositorio remoto de GitHub ya contiene archivos o commits que nuestro repositorio local no tiene.

Por ejemplo, imaginemos que tenemos este proyecto en nuestro ordenador:

mi-proyecto/
├── index.html
├── style.css
└── script.js

Ya hemos creado el repositorio Git localmente y hemos realizado nuestro primer commit:

Repositorio local
└── Commit A
    ├── index.html
    ├── style.css
    └── script.jsLenguaje del código: CSS (css)

Pero, al mismo tiempo, hemos creado en GitHub un repositorio que ya contiene un README.md:

Repositorio remoto - GitHub
└── Commit B
    └── README.mdLenguaje del código: CSS (css)

Ahora tenemos dos repositorios que poseen historiales diferentes:

Repositorio local          Repositorio remoto
       │                         │
    Commit A                  Commit B
       │                         │
   index.html                README.md
   style.css
   script.jsLenguaje del código: CSS (css)

Si intentamos ejecutar:

git push -u origin main

Git puede rechazar el envío.

5.1. ¿Por qué Git rechaza el push?

Git no está rechazando el envío simplemente porque exista un archivo en GitHub que también exista en nuestro proyecto local.

El problema principal es que el repositorio remoto ya tiene commits que no existen en nuestro repositorio local.

Git evita sobrescribir automáticamente el historial remoto.

Por ejemplo:

LOCAL                         REMOTO
  │                             │
Commit A                      Commit B
  │                             │
  └───────────┐   ┌─────────────┘
              │   │
              ▼   ▼
          Historiales
           diferentes

Por eso podemos encontrarnos con un mensaje similar a:

! [rejected] main -> main (non-fast-forward)Lenguaje del código: CSS (css)

o con un mensaje que indique que las actualizaciones fueron rechazadas porque el repositorio remoto contiene trabajo que nosotros no tenemos localmente.

5.2. Un caso muy habitual: crear un README desde GitHub

Este problema aparece con frecuencia cuando creamos el repositorio remoto desde GitHub y marcamos la opción:

Add a README file

Por ejemplo, GitHub crea:

README.mdLenguaje del código: CSS (css)

y genera automáticamente un commit.

Mientras tanto, nuestro proyecto local puede tener su propio historial:

LOCAL
Commit A
   ↓
index.html
style.css
script.jsLenguaje del código: CSS (css)

y GitHub:

REMOTO
Commit B
   ↓
README.mdLenguaje del código: CSS (css)

Aunque los archivos sean diferentes, los dos repositorios tienen historiales independientes.

Por eso, cuando vamos a subir un proyecto local que ya tiene un historial de Git, suele ser conveniente crear el repositorio remoto inicialmente vacío, sin generar automáticamente un README, .gitignore o licencia.

De esta manera podemos establecer la conexión y enviar nuestro historial local:

Repositorio local
       │
       │ git push
       ▼
Repositorio remoto vacío
       │
       ▼
Archivos + historial local

5.3. ¿Qué ocurre si el repositorio remoto ya tiene archivos?

Si el repositorio remoto ya contiene archivos o commits, no significa que hayamos perdido nuestro proyecto ni que tengamos que eliminar inmediatamente el repositorio.

Tenemos que decidir cómo queremos integrar ambos historiales.

Una opción habitual es traer primero los cambios del repositorio remoto, integrarlos con nuestro repositorio local y posteriormente volver a realizar el push.

Por ejemplo:

git pull origin main --allow-unrelated-histories

La opción:

--allow-unrelated-histories

le indica a Git que permita combinar dos historiales que comenzaron de manera independiente.

Después de ejecutar el comando, Git puede integrar el contenido remoto con nuestro proyecto local.

Si no existen conflictos en los archivos, podremos continuar con un commit y posteriormente hacer:

git push

5.4. ¿Qué significa --allow-unrelated-histories?

Esta opción es especialmente importante cuando tenemos dos repositorios que fueron creados de forma independiente.

Por ejemplo:

Repositorio local
      ↓
git init
      ↓
Commit A


Repositorio GitHub
      ↓
Crear README
      ↓
Commit B

Ambos tienen un historial, pero no comparten un commit inicial común.

Por eso Git considera que son:

Historial local ───────┐
                       ├── Historiales independientes
Historial remoto ──────┘

Con:

git pull origin main --allow-unrelated-histories

le estamos indicando a Git que queremos permitir esa combinación.

Esta opción no debería utilizarse automáticamente ante cualquier error de git push. Primero debemos entender por qué Git rechazó el envío.

5.5. ¿Y si el mismo archivo existe en local y en GitHub?

Aquí hay una diferencia importante.

Que un archivo tenga el mismo nombre en ambos repositorios no significa automáticamente que exista un conflicto.

Por ejemplo, podemos tener:

LOCAL
index.htmlLenguaje del código: CSS (css)

y:

GITHUB
index.htmlLenguaje del código: CSS (css)

El problema aparece si ambos archivos tienen contenido diferente y Git necesita determinar cómo combinar esas modificaciones.

Por ejemplo:

LOCAL
index.html
    ↓
<h1>Mi página web</h1>


GITHUB
index.html
    ↓
<h1>Mi sitio web</h1>Lenguaje del código: HTML, XML (xml)

En este caso Git puede detectar un conflicto de contenido porque las dos versiones modificaron la misma parte del archivo de manera incompatible.

Entonces tendremos que decidir manualmente qué contenido queremos conservar.

5.6. ¿Cómo se resuelve un conflicto de Git?

Cuando Git encuentra un conflicto, puede insertar marcas dentro del archivo para indicarnos las diferentes versiones.

Por ejemplo:

<<<<<<< HEAD
<h1>Mi página web</h1>
=======
<h1>Mi sitio web</h1>
>>>>>>> origin/main

Estas marcas indican:

<<<<<<< HEAD

el contenido que tenemos en nuestra rama local.

=======

separa las dos versiones.

>>>>>>> origin/main

indica el contenido procedente del repositorio remoto.

Debemos editar el archivo y decidir qué versión queremos conservar.

Por ejemplo:

<h1>Mi sitio web</h1>Lenguaje del código: HTML, XML (xml)

Después debemos guardar el archivo y continuar con el proceso:

git add .
git commit -m "Resolver conflicto con repositorio remoto"
git pushLenguaje del código: JavaScript (javascript)

5.7. ¿Cuál es la mejor manera de evitar estos conflictos al comenzar?

Cuando tenemos un proyecto local que ya utiliza Git y queremos subirlo a un repositorio nuevo de GitHub, podemos simplificar mucho el proceso.

Una opción recomendable es:

5.7.1. Crear el repositorio en GitHub

Creamos el repositorio remoto, pero inicialmente lo dejamos vacío.

Es decir, evitamos seleccionar:

• Crear README.
• Crear .gitignore.
• Crear una licencia.

5.7.2. Conectar nuestro repositorio local

git remote add origin URL_DEL_REPOSITORIO

5.7.3. Comprobar la rama

git branch

Si queremos utilizar main:

git branch -M main

5.7.4. Enviar nuestro historial local

git push -u origin main

De esta manera:

       PROYECTO LOCAL
             │
             │ git push
             ▼
    ┌─────────────────┐
    │ GitHub vacío    │
    └────────┬────────┘
             │
             ▼
   Archivos + commits
       del proyecto

El procedimiento resulta mucho más sencillo porque no existen dos historiales independientes que haya que combinar.

5.8. Importante: no todos los errores de git push son iguales

Cuando git push es rechazado, no debemos asumir automáticamente que existe un conflicto de archivos.

Puede haber diferentes causas:

• El repositorio remoto ya tiene commits.
• Los historiales local y remoto son diferentes.
• Existe un conflicto de contenido.
• Estamos trabajando con ramas diferentes.
• No tenemos permisos para escribir en el repositorio.
• Hay un problema de autenticación mediante HTTPS o SSH.
• La rama remota tiene cambios que todavía no hemos descargado.

Por eso, lo primero que debemos hacer es leer el mensaje que devuelve Git.

No es recomendable ejecutar comandos como git push --force simplemente porque el push haya sido rechazado. El uso incorrecto de --force puede sobrescribir el historial remoto y provocar la pérdida de cambios.

5.9. En resumen

Cuando conectamos Git con GitHub por primera vez, debemos distinguir entre archivos diferentes, archivos iguales y conflictos de historial.

El caso más habitual es:

Repositorio local
       │
       │ tiene commits
       ▼
    Commit A


Repositorio remoto
       │
       │ también tiene commits
       ▼
    Commit B

Si ambos repositorios fueron creados independientemente, Git puede impedir el push porque el repositorio remoto contiene información que nuestro repositorio local todavía no tiene.

Por eso, cuando tenemos un proyecto local que ya posee su propio historial de Git, una estrategia sencilla es crear el repositorio remoto vacío en GitHub y después enviar nuestro repositorio local mediante git push.

En cambio, si el repositorio remoto ya contiene información que queremos conservar, debemos traer esos cambios, integrar ambos historiales y resolver cualquier conflicto que aparezca antes de volver a realizar el push.

6. Preguntas frecuentes sobre conectar Git con GitHub

mi-proyecto/
├── index.html
├── style.css
├── script.js
└── .gitignore

git init
git add .
git commit
git push

Ordenador
   ↓
Git
   ↓
Repositorio local

git remote add origin https://github.com/usuario/proyecto.git

git push origin main

git remote -v

origin  https://github.com/usuario/proyecto.git (fetch)
origin  https://github.com/usuario/proyecto.git (push)

git remote add origin https://github.com/usuario/proyecto.git

git push

Archivos modificados
        ↓
    git add
        ↓
   Staging Area
        ↓
   git commit
        ↓
Repositorio local
        ↓
    git push
        ↓
GitHub

https://github.com/usuario/proyecto.git

[email protected]:usuario/otro-proyecto.git

git remote -v

git remote set-url origin NUEVA_URL

Repositorio local
      ↓
   Commit A


Repositorio remoto
      ↓
   Commit B

git add .
git commit -m "Descripción de los cambios"
git push

git push

git status

        ORDENADOR
   ┌─────────────────┐
   │ Repositorio     │
   │ local           │
   └────────┬────────┘
            │
       git push
            ↓
   ┌─────────────────┐
   │ Repositorio     │
   │ remoto          │
   │ GitHub          │
   └─────────────────┘

git status
git add .
git commit -m "Descripción de los cambios"
git push