Repositorio Git: cómo crearlo con git init y conectar un remote

Un repositorio Git es un proyecto cuyos cambios sigue Git. Físicamente es una carpeta normal con tus archivos más un directorio oculto .git en el que se guarda todo el historial: commits, ramas, etiquetas y configuración. Si borras .git, te quedan solo los archivos, sin ninguna versión anterior.

De qué se compone un repositorio

Al trabajar con Git conviene tener presentes tres áreas por las que viajan los cambios:

• directorio de trabajo (working tree): los archivos que ves y editas;
• índice (staging area): el borrador del próximo commit, adonde llegan los cambios con git add;
• historial: la base de commits dentro de .git, adonde llegan los cambios con git commit.

En sentido estricto, el repositorio es el contenido de .git. El directorio de trabajo no es más que una versión «desplegada» del proyecto que Git saca del historial.

Cómo crear un repositorio Git con git init

Entra en la carpeta del proyecto y ejecuta un solo comando:

cd ~/projects/my-app
git init

Initialized empty Git repository in /home/user/projects/my-app/.git/

Puedes crear el repositorio tanto en una carpeta vacía como en una que ya tenga archivos. En el segundo caso no se pierde nada: los archivos existentes simplemente quedan sin seguimiento (untracked) hasta que los añadas con git add.

Variantes útiles del comando:

# Crear la carpeta y el repositorio dentro de una vez
git init my-app

# Definir el nombre de la primera rama (si no, master o el valor de la configuración)
git init -b main

# Hacer de main la rama por defecto en todos los repositorios nuevos
git config --global init.defaultBranch main

El primer commit

Un repositorio vacío sin commits casi no sirve de nada. Justo después de git init lo habitual es:

git config --global user.name "Juan Pérez"
git config --global user.email "juan@example.com"

git status
git add .
git commit -m "Estructura inicial del proyecto"

El nombre y el e-mail se configuran una vez por ordenador y se graban en cada commit. Sin ellos, Git se negará a hacer el commit y te pedirá que te identifiques.

Añade .gitignore desde el principio

Antes del primer git add . crea un archivo .gitignore con lo que no debe entrar en el repositorio: dependencias, compilaciones, secretos y archivos del IDE.

node_modules/
dist/
.env
.idea/
.vscode/
*.log
__pycache__/

Si un archivo ya entró en un commit, .gitignore no lo quitará. Hay que dejar de seguirlo manteniéndolo en disco con git rm --cached .env y después hacer commit.

Qué hay dentro de la carpeta .git

En el trabajo normal no hace falta mirar ahí, pero entender su estructura resuelve muchas dudas:

De aquí sale una conclusión importante: una rama en Git es un archivo diminuto con un único hash. Por eso crear ramas es instantáneo y no cuesta nada.

Cómo comprobar si una carpeta es un repositorio

git status
# o, con más precisión
git rev-parse --is-inside-work-tree

Fuera de un repositorio obtendrás fatal: not a git repository (or any of the parent directories): .git. Fíjate en «parent directories»: Git busca .git subiendo por el árbol de carpetas. Si ejecutas git init por error en tu carpeta personal, toda ella se convertirá en un repositorio, y habrá que borrar esa carpeta .git.

Repositorio local y repositorio remoto

Un repositorio creado con git init existe solo en tu ordenador. Para compartir el código y tener una copia de seguridad se le conecta un repositorio remoto (remote), una copia en un servidor: GitHub, GitLab, Bitbucket o tu propio servidor Git.

Para Git, el repositorio remoto no es el «principal»: cada copia es completa y contiene todo el historial. Lo que lo convierte en central es solo el acuerdo del equipo.

git remote: conectar un repositorio remoto

Un remote es un nombre corto para la dirección del servidor. Por convención, el principal se llama origin.

# Añadir un remote
git remote add origin git@github.com:username/my-app.git

# Ver la lista con las direcciones
git remote -v

origin  git@github.com:username/my-app.git (fetch)
origin  git@github.com:username/my-app.git (push)

Después envía la rama y vincúlala con la remota:

git push -u origin main

Comandos principales de git remote

Formatos de dirección

• https://github.com/user/repo.git: HTTPS, funciona en todas partes; para escribir necesitas un token;
• git@github.com:user/repo.git: SSH, necesita una clave; una vez configurado, no pide contraseñas;
• /srv/git/repo.git o file:///srv/git/repo.git: ruta local, cómoda para experimentar.

Errores frecuentes

«error: remote origin already exists». Ya existe un remote con ese nombre. Si quieres cambiar la dirección, usa git remote set-url origin <url>, no otro add.

«failed to push some refs» / «Updates were rejected». En el servidor hay commits que tú no tienes; a menudo es el README creado al dar de alta el repositorio en la web. Ejecuta git pull --rebase origin main y repite el push. Si los historiales no tienen ninguna relación, Git responderá «refusing to merge unrelated histories», y entonces git pull necesita la opción --allow-unrelated-histories. Es más fácil crear el repositorio vacío en la web.

«src refspec main does not match any». Intentas enviar una rama que no existe: o aún no hay ningún commit, o la rama se llama master. Compruébalo con git branch.

Tu propio servidor Git: repositorio bare

GitHub no es obligatorio. Cualquier máquina a la que tengas acceso por SSH puede hacer de repositorio remoto. Para ello se crea en el servidor un repositorio «desnudo» (bare), sin directorio de trabajo, solo con el contenido de .git:

# En el servidor
ssh user@server
git init --bare /srv/git/my-app.git

# En tu ordenador
git remote add origin user@server:/srv/git/my-app.git
git push -u origin main

Para trabajar con un servidor así entre tres personas basta con dar a los compañeros acceso SSH a la carpeta del repositorio y un grupo común con permisos de escritura. Para separar permisos por ramas y proyectos ya no es suficiente; entonces hace falta un hosting de Git completo.

En un repositorio bare no se puede «entrar y corregir un archivo»: está pensado solo para intercambiar mediante push y fetch. Así funcionan los repositorios de cualquier hosting de Git. Si necesitas interfaz web, revisión de código e issues, se instalan soluciones self-hosted como GitLab, Gitea o Forgejo.

Ramas de seguimiento: cómo ve el repositorio local al servidor

Tras conectar un remote y hacer el primer git fetch o git push, aparecen en el repositorio ramas remotas del tipo origin/main. No son ramas del servidor, sino «instantáneas» locales de lo que viste en el servidor en la última sincronización. Solo se actualizan con fetch, pull y push.

De ahí la diferencia importante entre los tres comandos de intercambio:

Para saber cuánto va por detrás o por delante tu rama:

git fetch
git status -sb

## main...origin/main [ahead 2, behind 1]

Aquí tienes dos commits que no están en el servidor y el servidor tiene uno que tú no tienes. Antes del push hay que traer ese commit.

El vínculo entre la rama local y la remota (upstream) se establece con la opción -u en el primer push. Si se te olvidó, puedes configurarlo aparte: git branch --set-upstream-to=origin/main. Para ver todos los vínculos: git branch -vv.

Varios repositorios: monorepo o uno por proyecto

Una pregunta habitual de principiante es cuántos repositorios Git crear. Regla sencilla: un repositorio por cada unidad que se desarrolla y se publica de forma independiente. Los proyectos de práctica, los proyectos personales y los servicios separados van en repositorios distintos. No crees un repositorio para toda la carpeta «Mis proyectos»: el historial se mezclará y será difícil publicar un solo proyecto en tu portafolio.

Las grandes empresas a veces mantienen todo el código en un monorepositorio para hacer cambios comunes y una compilación única, pero es una decisión de arquitectura consciente con sus propias herramientas. Un principiante debería empezar por la regla «un proyecto, un repositorio» y no anidar nunca un repositorio dentro de otro sin submódulos.

git init o git clone

Después de git clone el remote origin ya está configurado y no hay que añadirlo a mano.

Paso a paso: de una carpeta a un repositorio en GitHub

1. Crea la carpeta del proyecto y ejecuta git init -b main.
2. Añade .gitignore y un README.
3. Haz el primer commit: git add . y git commit -m "Initial commit".
4. Crea en GitHub un repositorio vacío, sin README, licencia ni .gitignore.
5. Conéctalo: git remote add origin <dirección>.
6. Envía el código: git push -u origin main.
7. A partir de ahí trabaja en ciclo: cambios → git add → git commit → git push.

Resumen

Un repositorio Git es tu proyecto más la carpeta .git con todo el historial. Se crea con git init, y la conexión con el servidor se configura con git remote add origin y el primer git push -u. El repositorio remoto puede ser GitHub, GitLab o tu propio servidor Git con un repositorio bare. La creación del primer repositorio, el índice y la conexión de un remote se practican en el curso de Git.