Cómo subir un proyecto a GitHub paso a paso

Hola, ¿cómo están? Bienvenidos. En este tutorial veremos paso a paso cómo subir un proyecto a GitHub. De esta manera podrás compartir el código de tus proyectos de PHP o Laravel con tu equipo de trabajo y trabajar de forma colaborativa.

¡Empecemos!

Qué es un repositorio

Un repositorio es una dirección en la nube, alojada en un servicio como GitHub, Bitbucket o GitLab, donde se almacena y se lleva el seguimiento de un conjunto de archivos y carpetas de un proyecto en específico. Cada proyecto tiene su propia ruta de acceso exclusiva.

Los repositorios son fundamentales para la colaboración y la gestión de cambios en proyectos de software: son el lugar donde vive la versión oficial del código y donde queda registrado quién cambió qué y cuándo.

Git y GitHub no son lo mismo

Conviene tener clara la diferencia antes de seguir, porque se confunden todo el tiempo.

Git es un sistema de control de versiones distribuido, desarrollado por Linus Torvalds. Se instala en tu computadora y funciona sin internet. Es el que lleva el registro de las versiones de tu código.

GitHub es un servicio en la nube que aloja repositorios de Git para que puedas respaldarlos y compartirlos. Es el más usado por la comunidad de desarrolladores, pero no es el único.

Dicho de otro modo: Git hace el trabajo, GitHub guarda el resultado. Si quieres entender Git más a fondo, lo desarrollamos en qué es Git.

Para seguir este tutorial necesitas descargar Git e instalarlo en tu máquina, y tener una cuenta de GitHub.

Antes de empezar: configura Git

Si es la primera vez que usas Git en esta computadora, configúralo. Git firma cada cambio con estos datos, y sin ellos el primer commit va a fallar:

git config --global user.name "Tu Nombre"
git config --global user.email "tu@correo.com"

Usa el mismo correo de tu cuenta de GitHub. Así tus aportes quedan asociados a tu perfil.

Crear un nuevo repositorio en GitHub

Abre el navegador e inicia sesión en GitHub. En la pantalla principal haz clic en New, o en el botón Create repository.

Se abrirá un formulario que te pide algunos datos:

• Repository name. El nombre del nuevo repositorio. Sin espacios y en minúsculas es lo habitual.
• Description. Una breve descripción de lo que contendrá el proyecto. Es opcional, pero ayuda cuando tengas veinte repositorios.
• Public / Private. Público lo ve todo el mundo; privado solo tú y quienes autorices. Si el proyecto es de un cliente, privado.
• Initialize this repository with. Sirve para crear el repositorio con archivos iniciales como el README, el .gitignore o una licencia. Para este tutorial no marques ninguna, porque vamos a subir un proyecto que ya existe y esos archivos causarían un conflicto en el primer envío.

Una vez llenados los campos, haz clic en Create repository.

Si todo está correcto, GitHub crea el repositorio y te lleva a una pantalla con las instrucciones para empezar, que contempla tres situaciones: crear un proyecto desde cero, subir uno que ya tienes en tu máquina, o traerlo desde otro repositorio.

Subir tu proyecto local a GitHub

Nosotros ya tenemos el proyecto creado en la computadora, así que seguiremos las instrucciones de la segunda opción.

Abre la terminal y ubícate en el directorio raíz de tu proyecto. Después ejecuta estos comandos, uno por uno.

1. Iniciar el repositorio de Git:

git init

2. Añadir todos los archivos y carpetas del proyecto:

git add -A

3. Confirmar los cambios con un mensaje descriptivo de lo que se hizo:

git commit -m "Inicio de mi proyecto en GitHub"

4. Nombrar la rama principal. GitHub usa main como nombre por defecto:

git branch -M main

5. Enlazar tu proyecto local con el repositorio de la nube. Esta línea te la da GitHub al crear el repositorio; cambia la URL por la tuya:

git remote add origin https://github.com/NorvicSoftware/tutoriales_php.git

6. Subir todo:

git push -u origin main

Si todo está correcto, empezarán a subirse los archivos. En el navegador puedes verificar que llegaron, y GitHub te mostrará además el detalle del registro: la rama, la fecha y el mensaje del cambio.

La autenticación: por qué tu contraseña no funciona

Aquí es donde se traba mucha gente, y donde la información antigua confunde más.

GitHub ya no acepta tu contraseña para las operaciones de Git. Si al hacer git push intentas ingresar el usuario y la contraseña de tu cuenta, va a fallar. Tienes dos caminos:

Token de acceso personal. Entra a tu perfil de GitHub → Settings → Developer settings → Personal access tokens, y genera uno. Cuando Git te pida la contraseña, pegas el token en su lugar. Guárdalo apenas lo generes, porque no se puede volver a ver.

Clave SSH. Más cómodo a largo plazo, porque no vuelve a pedirte nada. Generas la clave en tu máquina, cargas la parte pública en Settings → SSH and GPG keys, y usas la URL en formato SSH en lugar de la que empieza con https.

En Windows es habitual que se abra directamente una ventana del navegador para autorizar la sesión. Si te aparece, ese es el camino más simple.

Qué no subir nunca: el .gitignore

Antes del primer git push, dedícale un minuto a esto. Es el error más caro de este tutorial.

Un archivo llamado .gitignore, en la raíz del proyecto, le dice a Git qué debe ignorar. Como mínimo:

/vendor
/node_modules
.env
*.log

Por qué cada uno:

• .env guarda las contraseñas de tu base de datos y las claves de tus servicios. Si lo subes a un repositorio público, esas credenciales quedan expuestas, y hay programas rastreando GitHub justamente en busca de eso.
• /vendor y /node_modules son dependencias que se reconstruyen con un comando. Miles de archivos que no escribiste.

Y algo importante que casi nadie advierte: si ya subiste un archivo, agregarlo después al .gitignore no lo borra del historial. Sigue ahí, accesible, aunque no lo veas en la última versión. Si se te escapó una contraseña, cámbiala; no basta con borrar el archivo.

Trabajar con ramas

Hasta aquí subiste el proyecto. A partir de ahora, la forma sana de seguir trabajando es no tocar main directamente.

Creas una rama para cada cosa nueva:

git switch -c formulario-contacto

Trabajas ahí, haces tus commits, y cuando esté lista la subes:

git push -u origin formulario-contacto

En GitHub aparecerá un botón para abrir un Pull Request, que es la forma de proponer que esa rama se una a main. Ahí tu equipo puede revisar el código antes de que entre.

Por qué conviene: main debería tener siempre una versión que funciona. Si todos trabajan directamente sobre ella, cualquier cosa a medio terminar bloquea al resto.

Cuando aparece un conflicto

Un conflicto ocurre cuando dos personas modificaron las mismas líneas del mismo archivo y Git no puede decidir cuál vale. No es un error: es Git pidiéndote que elijas.

Lo primero, siempre, antes de empezar a trabajar:

git pull

Si aparece el conflicto, Git marca el archivo así:

<<<<<<< HEAD
el código que tenías tú
=======
el código que trajo el otro
>>>>>>> rama-del-companero

Abres el archivo, decides qué queda —puede ser lo tuyo, lo del otro, o una mezcla—, borras las tres líneas de marcas y guardas. Después:

git add .
git commit -m "Resuelve conflicto en el formulario"

El consejo que más ayuda: los conflictos se evitan haciendo pull seguido y commits pequeños. Cuanto más tiempo pasa una rama sin integrarse, peor el choque.

Errores comunes

• Marcar «Add a README» al crear el repositorio y después intentar subir un proyecto existente. GitHub rechaza el envío porque las historias no coinciden. Por eso no marcamos ninguna casilla.
• Intentar autenticarse con la contraseña. Ya no funciona: token o SSH.
• Subir el .env. Cambia las credenciales de inmediato si te pasó.
• Olvidar el .gitignore y subir vendor o node_modules. Miles de archivos y un repositorio pesadísimo.
• Confundir commit con push. El commit guarda en tu máquina; hasta que no haces push, en GitHub no hay nada.

Para cerrar

Eso es todo por este tutorial de cómo subir un proyecto a GitHub. El resumen en una línea: init, add, commit, branch, remote add y push. La primera vez cuesta; de la segunda en adelante son treinta segundos.

Para cualquier comentario o duda puedes dejar un mensaje. Y si tu empresa necesita un sistema a medida, en Norvic Software lo desarrollamos entregando siempre el código fuente al cliente.

Saludos y éxitos.