GitHub desde local

1. Requisitos previos

Antes de subir un proyecto a GitHub, verificar:

• Tener una cuenta de GitHub.
• Tener Git instalado.
• Tener acceso al repositorio remoto.
• Tener definido si el repositorio será privado o público.
• Tener claro el nombre del repositorio.
• Tener un archivo .gitignore adecuado para el stack del proyecto.
• No subir archivos sensibles: .env, claves privadas, tokens, certificados, backups, dumps de base de datos o configuraciones con credenciales.

Validar instalación:

git --version

Configurar identidad local:

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

Ver configuración actual:

git config --list

---

2. Estructura recomendada antes de subir

Ejemplo base:

mi-proyecto/
  src/
  docs/
  tests/
  README.md
  .gitignore

Archivos mínimos recomendados:

README.md
.gitignore

Para proyectos .NET:

bin/
obj/
.vs/
*.user
*.suo
appsettings.*.json
!appsettings.example.json

Para proyectos Node/Astro:

node_modules/
dist/
.env
.env.*
!.env.example

Para proyectos generales:

.DS_Store
Thumbs.db
*.log

---

3. Caso A — Subir un proyecto local nuevo a GitHub

Este caso aplica cuando tienes una carpeta local que todavía no está versionada con Git.

3.1 Entrar al proyecto

cd ruta/del/proyecto

3.2 Inicializar Git

git init

3.3 Crear .gitignore

Crear o validar el archivo:

touch .gitignore

Agregar exclusiones según el tipo de proyecto.

3.4 Revisar archivos detectados

git status

3.5 Agregar archivos al staging

git add .

3.6 Crear primer commit

git commit -m "Initial commit"

3.7 Crear repositorio en GitHub

Desde GitHub:

1. Crear un nuevo repository.
2. Definir nombre.
3. Elegir private o public.
4. No inicializar con README si ya existe localmente.
5. Copiar la URL del repositorio.

Ejemplo HTTPS:

https://github.com/ORG_OR_USER/NOMBRE_REPO.git

Ejemplo SSH:

git@github.com:ORG_OR_USER/NOMBRE_REPO.git

3.8 Vincular repositorio remoto

git remote add origin https://github.com/ORG_OR_USER/NOMBRE_REPO.git

Validar remote:

git remote -v

3.9 Renombrar rama principal a main

git branch -M main

3.10 Subir a GitHub

git push -u origin main

El parámetro -u deja vinculada la rama local main con origin/main, por lo que luego bastará con usar:

git push

---

4. Caso B — Subir un proyecto local que ya tiene Git

Este caso aplica cuando la carpeta ya tiene .git.

4.1 Verificar estado

git status

4.2 Verificar remote actual

git remote -v

Si no existe remote:

git remote add origin https://github.com/ORG_OR_USER/NOMBRE_REPO.git

Si existe pero apunta a otro origen:

git remote set-url origin https://github.com/ORG_OR_USER/NOMBRE_REPO.git

4.3 Confirmar rama actual

git branch

Si se quiere usar main:

git branch -M main

4.4 Subir cambios

git push -u origin main

---

5. Caso C — Clonar un repositorio existente

Este caso aplica cuando el proyecto ya existe en GitHub y se quiere traer a local.

5.1 Clonar

HTTPS:

git clone https://github.com/ORG_OR_USER/NOMBRE_REPO.git

SSH:

git clone git@github.com:ORG_OR_USER/NOMBRE_REPO.git

5.2 Entrar al proyecto

cd NOMBRE_REPO

5.3 Verificar estado

git status

5.4 Instalar dependencias

Depende del stack.

Node/Astro:

npm install

.NET:

dotnet restore

---

6. Flujo normal de actualización

Este es el flujo diario recomendado para trabajar localmente y subir cambios.

6.1 Actualizar la rama local antes de trabajar

git pull

Si el equipo usa rebase:

git pull --rebase

6.2 Revisar cambios locales

git status

6.3 Ver diferencias

git diff

6.4 Agregar cambios

Todos los archivos:

git add .

Archivo específico:

git add ruta/archivo.ext

6.5 Crear commit

git commit -m "Descripción clara del cambio"

Ejemplos de mensajes:

Add catalog fragment generation
Fix R2 asset path validation
Update deployment documentation
Refactor publisher service

6.6 Subir cambios

git push

---

7. Trabajo con ramas

Para no trabajar directamente sobre main, usar ramas por feature, fix o documentación.

7.1 Crear rama nueva

git checkout -b feature/nombre-cambio

Ejemplos:

git checkout -b feature/catalog-fragments
git checkout -b fix/r2-prefix-validation
git checkout -b docs/github-guide

7.2 Subir rama al remoto

git push -u origin feature/nombre-cambio

7.3 Cambiar de rama

git checkout main

O:

git switch main

7.4 Ver ramas

Locales:

git branch

Locales y remotas:

git branch -a

---

8. Pull Request recomendado

Para equipos, lo ideal es no subir directamente a main.

Flujo recomendado:

crear rama
→ hacer cambios
→ commit
→ push
→ abrir Pull Request
→ revisión
→ merge a main

Ventajas:

• Permite revisión de código.
• Reduce errores en main.
• Deja historial claro.
• Facilita integración con CI/CD.
• Permite bloquear merges si fallan tests.

---

9. Actualizar una rama con cambios de main

Si estás trabajando en una rama y main avanzó:

git checkout main
git pull
git checkout feature/nombre-cambio
git merge main

Alternativa con rebase:

git checkout feature/nombre-cambio
git fetch origin
git rebase origin/main

Usar rebase solo si el equipo está alineado con esa práctica.

---

10. Resolver conflictos básicos

Si Git informa conflictos:

git status

Abrir los archivos marcados y buscar:

<<<<<<< HEAD
cambios locales
=======
cambios remotos
>>>>>>> rama

Editar el archivo dejando la versión correcta.

Luego:

git add archivo-con-conflicto.ext
git commit

Si era un rebase:

git rebase --continue

Para cancelar un merge conflict:

git merge --abort

Para cancelar un rebase conflict:

git rebase --abort

---

11. Buenas prácticas de commits

Un commit debe representar una unidad lógica de cambio.

Bueno:

Add R2 fragment pagination
Fix XSS sanitization in catalog fragments
Document Cloudflare operation queue

Evitar:

changes
update
fix
cosas varias

Recomendación:

tipo: descripción corta

Ejemplos:

feat: add catalog fragment pagination
fix: sanitize product descriptions
docs: add github workflow guide
refactor: simplify publisher service

---

12. Archivos que no deben subirse

Nunca subir:

.env
.env.local
appsettings.Production.json
*.pfx
*.pem
*.key
*.bak
*.sql
node_modules/
bin/
obj/
dist/
logs/

En lugar de subir credenciales, crear archivos ejemplo:

.env.example
appsettings.example.json

Ejemplo:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
R2_BUCKET=

---

13. Autenticación con GitHub

GitHub ya no usa contraseña tradicional para operaciones Git por HTTPS. Se debe usar:

• GitHub CLI
• Personal Access Token
• SSH key

Opción A — HTTPS con token

Remote:

git remote set-url origin https://github.com/ORG_OR_USER/NOMBRE_REPO.git

Al pedir password, usar un Personal Access Token.

Opción B — SSH

Generar clave:

ssh-keygen -t ed25519 -C "tu.email@empresa.com"

Ver clave pública:

cat ~/.ssh/id_ed25519.pub

Agregar esa clave pública en GitHub.

Cambiar remote a SSH:

git remote set-url origin git@github.com:ORG_OR_USER/NOMBRE_REPO.git

Probar conexión:

ssh -T git@github.com

---

14. Comandos útiles

Ver estado:

git status

Ver historial:

git log --oneline --graph --decorate --all

Ver remotes:

git remote -v

Ver rama actual:

git branch --show-current

Traer cambios sin mezclar:

git fetch

Descartar cambios de un archivo:

git checkout -- ruta/archivo.ext

O con Git moderno:

git restore ruta/archivo.ext

Guardar cambios temporalmente:

git stash

Recuperar cambios guardados:

git stash pop

---

15. Recuperar errores comunes

Commit con mensaje incorrecto

Si todavía no se hizo push:

git commit --amend -m "Nuevo mensaje"

Agregué un archivo que no debía

Si todavía no se hizo commit:

git restore --staged archivo.ext

Hice commit pero olvidé un archivo

git add archivo.ext
git commit --amend --no-edit

Quiero volver a un commit anterior

Ver historial:

git log --oneline

Crear un commit que revierte otro:

git revert HASH_DEL_COMMIT

Evitar git reset --hard si el cambio ya fue compartido con otros.

---

16. Flujo recomendado para proyectos de Interzone

Para iniciar proyecto

1. Crear carpeta local.
2. Inicializar Git.
3. Crear README.md.
4. Crear .gitignore.
5. Primer commit.
6. Crear repositorio privado en GitHub.
7. Vincular remote.
8. Push a main.

Para trabajar día a día

1. git pull
2. crear rama feature/*
3. desarrollar
4. git status
5. git add
6. git commit
7. git push
8. Pull Request
9. revisión
10. merge a main

Para documentación

Usar ramas:

docs/nombre-documento

Ejemplo:

git checkout -b docs/sites-platform-architecture

---

17. Checklist antes de hacer push

Antes de subir cambios:

[ ] Ejecuté git status
[ ] Revisé git diff
[ ] No estoy subiendo credenciales
[ ] No estoy subiendo bin/, obj/, node_modules/ o dist/
[ ] El .gitignore está correcto
[ ] El proyecto compila o pasa pruebas básicas
[ ] El commit tiene un mensaje claro
[ ] Estoy en la rama correcta

---

18. Checklist antes de merge a main

[ ] Pull Request revisado
[ ] Conflictos resueltos
[ ] Tests ejecutados
[ ] Build validado
[ ] No hay secretos en el diff
[ ] Documentación actualizada si aplica
[ ] Aprobación del responsable

---

19. Comandos rápidos

Subir proyecto nuevo

cd mi-proyecto
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/ORG_OR_USER/NOMBRE_REPO.git
git push -u origin main

Actualizar proyecto existente

git pull
git status
git add .
git commit -m "Descripción del cambio"
git push

Crear rama y subirla

git checkout -b feature/nueva-funcionalidad
git add .
git commit -m "Add new feature"
git push -u origin feature/nueva-funcionalidad

---

20. Reglas de oro

No subir secretos.
No trabajar directo en main si hay equipo.
No hacer push sin revisar git status.
No mezclar muchos cambios distintos en un solo commit.
No ignorar conflictos.
No usar reset --hard sin entender el impacto.
No subir archivos generados salvo que el proyecto lo requiera.

---

Resumen final

GitHub debe usarse como repositorio central de código y documentación. El flujo recomendado es trabajar con ramas, commits pequeños, Pull Requests y revisión antes de integrar a main.

La regla operativa principal es:

main debe representar una versión estable del proyecto.