Guía práctica en español para aprender Git desde los fundamentos y trabajar con GitHub usando flujos profesionales, seguros y mantenibles.
Autor: Alejandro Di Stefano
Este repositorio no es una lista aislada de comandos. Está organizado como una guía de estudio, referencia y operación diaria para entender Git, colaborar en GitHub y resolver problemas habituales sin depender de recetas memorizadas.
Incluye:
- fundamentos de Git y su modelo de objetos;
- instalación y configuración inicial;
- working tree, staging area, commits y
HEAD; - branches y estrategias de integración;
- remotes, fetch, pull y push;
- merge, rebase y cherry-pick;
- stash, restore, reset y revert;
- resolución de conflictos;
- tags y releases;
- forks y Pull Requests;
- autenticación SSH;
.gitignorey manejo de secretos;- GitHub CLI;
- Conventional Commits;
- GitHub Actions y automatización;
- recuperación ante errores;
- troubleshooting;
- cheat sheet de uso diario.
La guía prioriza comandos actuales como
git switchygit restore, sin omitirgit checkoutcuando sigue siendo útil o aparece en proyectos existentes.
| Capítulo | Contenido |
|---|---|
| 01 — Fundamentos y configuración | Modelo mental, instalación, config, init, clone y estructura interna |
| 02 — Flujo diario y commits | status, add, diff, commit, restore, log y buenas prácticas |
| 03 — Branches e integración | branches, merge, rebase, cherry-pick y conflictos |
| 04 — GitHub y colaboración | remotes, PRs, forks, reviews, GitHub CLI y estrategias de equipo |
| 05 — Recuperación y seguridad | reset, revert, reflog, stash, SSH, secretos y errores frecuentes |
| 06 — Automatización y releases | tags, releases, Conventional Commits, SemVer y GitHub Actions |
| Cheat Sheet | Comandos frecuentes para consulta rápida |
| CHANGELOG | Evolución de la guía |
Git es un sistema de control de versiones distribuido. Cada clon contiene el historial del repositorio y permite crear commits, ramas y comparaciones localmente.
El flujo mental más importante es:
Working Tree
↓ git add
Staging Area / Index
↓ git commit
Local Repository
↓ git push
Remote Repository
Tres preguntas resuelven buena parte del trabajo diario:
git status
git diff
git log --oneline --graph --decorate --allgit --version
git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"
git config --global init.defaultBranch mainVer configuración efectiva:
git config --list --show-originConfigurar editor por defecto, por ejemplo VS Code:
git config --global core.editor "code --wait"mkdir mi-proyecto
cd mi-proyecto
git initgit clone https://github.com/usuario/repositorio.gitCon SSH:
git clone git@github.com:usuario/repositorio.gitgit statusgit diffgit diff --stagedgit add archivo.txt
git add src/
git add .Para seleccionar cambios por fragmentos:
git add -pgit commit -m "feat: agregar validación de usuarios"Un commit profesional debería representar una unidad lógica de cambio. Evitá commits gigantes con múltiples objetivos no relacionados.
Una convención simple ayuda a leer el historial y automatizar releases.
feat: nueva funcionalidad
fix: corrección de bug
docs: documentación
refactor: cambio interno sin alterar comportamiento
test: pruebas
chore: mantenimiento
ci: integración continua
perf: performance
Ejemplos:
git commit -m "feat(auth): add password reset flow"
git commit -m "fix(api): prevent duplicate requests"
git commit -m "docs: document local setup"Crear una rama y cambiarse a ella:
git switch -c feat/user-profileListar ramas:
git branch
git branch -aCambiar de rama:
git switch mainEliminar una rama local ya integrada:
git branch -d feat/user-profileForzar eliminación local:
git branch -D feat/user-profile
-Ddescarta la protección de Git. Usalo sólo cuando verificaste que no necesitás los commits exclusivos de esa rama.
Listar remotes:
git remote -vAgregar origin:
git remote add origin git@github.com:usuario/repositorio.gitCambiar URL:
git remote set-url origin git@github.com:usuario/repositorio.gitVer información:
git remote show originDescarga referencias remotas sin integrar cambios en tu rama actual.
git fetch originEquivale conceptualmente a descargar e integrar.
git pull --ff-only origin main--ff-only evita merges automáticos inesperados cuando el historial divergió.
Primera publicación de una rama:
git push -u origin feat/user-profileLuego:
git pushDesde la rama que recibe los cambios:
git switch main
git merge feat/user-profileTipos frecuentes:
- fast-forward: Git mueve el puntero de la rama;
- merge commit: crea un commit de integración;
- squash merge: combina los cambios de una rama en un único commit, normalmente desde GitHub.
Actualizar una feature branch sobre el estado actual de main:
git fetch origin
git switch feat/user-profile
git rebase origin/mainSi aparece un conflicto:
# resolver archivos
git add archivo-resuelto
git rebase --continueAbortar:
git rebase --abortEvitá reescribir con rebase commits públicos que otras personas ya estén usando, salvo que el equipo haya acordado explícitamente ese flujo.
Git marca las zonas conflictivas así:
<<<<<<< HEAD
cambio actual
=======
cambio entrante
>>>>>>> otra-rama
Proceso:
git status
# editar y resolver
git add archivoSi estabas haciendo merge:
git commitSi estabas haciendo rebase:
git rebase --continuegit restore archivo.txtgit restore --staged archivo.txtgit revert <sha>revert crea un nuevo commit inverso y suele ser la opción correcta en ramas compartidas.
git reset --soft HEAD~1
git reset --mixed HEAD~1
git reset --hard HEAD~1--hard modifica índice y working tree. Puede eliminar trabajo no guardado.
Si moviste una rama o hiciste un reset incorrecto:
git reflogLuego podés inspeccionar o recuperar un commit:
git switch -c recovery/<nombre> <sha>En muchos casos un commit “perdido” sigue siendo recuperable mientras permanezca referenciado por el reflog.
Guardar cambios temporales:
git stash push -m "wip: formulario"Listar:
git stash listRecuperar y eliminar del stash:
git stash popAplicar sin eliminar:
git stash apply stash@{0}Aplicar un commit puntual sobre otra rama:
git cherry-pick <sha>Es útil para hotfixes o para trasladar un cambio aislado. No debería convertirse en el mecanismo normal de integración de ramas enteras.
Un flujo habitual:
git switch main
git pull --ff-only
git switch -c feat/nueva-funcionalidad
# trabajar
git add .
git commit -m "feat: implement new feature"
git push -u origin feat/nueva-funcionalidadLuego se crea un Pull Request hacia main.
Un PR profesional debería explicar:
- problema u objetivo;
- solución implementada;
- alcance;
- riesgos;
- cómo probarlo;
- screenshots si modifica UI;
- migraciones o variables de entorno si corresponden.
Configurar el repositorio original como upstream:
git remote add upstream git@github.com:organizacion/proyecto.git
git fetch upstreamActualizar tu main:
git switch main
git merge --ff-only upstream/main
git push origin mainAutenticarse:
gh auth loginCrear PR:
gh pr create --fillVer PRs:
gh pr listRevisar checks:
gh pr checksVer PR actual:
gh pr view --webCrear tag anotado:
git tag -a v2.0.0 -m "Release v2.0.0"Publicarlo:
git push origin v2.0.0Versionado SemVer:
MAJOR.MINOR.PATCH
MAJOR: cambios incompatibles o reestructuración mayor;MINOR: nuevas funcionalidades compatibles;PATCH: correcciones compatibles.
Los tags identifican commits. Los GitHub Releases agregan metadata, notas, assets y una presentación orientada a usuarios.
Recomendado actualmente:
ssh-keygen -t ed25519 -C "tu@email.com"Iniciar agente:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519Ver clave pública:
cat ~/.ssh/id_ed25519.pubProbar conexión:
ssh -T git@github.comNunca compartas la clave privada.
Ejemplo genérico:
.env
.env.*
node_modules/
dist/
build/
coverage/
*.log
.DS_Store
.vscode/
.gitignoreno elimina archivos que ya están versionados.
Para dejar de trackear uno sin borrarlo localmente:
git rm --cached .envSi un secreto ya fue publicado, borrarlo del último commit no invalida la credencial. Primero hay que rotarla o revocarla y luego limpiar el historial si corresponde.
git log --oneline --graph --decorate --allBuscar por texto del commit:
git log --grep="auth"Buscar commits que agregaron o eliminaron una cadena:
git log -S "TOKEN_AUTH" --onelineVer quién modificó líneas:
git blame archivo.txtgit reset --hard
git clean -fd
git push --force
git branch -D
git rebaseNo son comandos “malos”; simplemente pueden reescribir referencias o destruir cambios si se ejecutan sin entender el estado actual.
Para ramas propias que ya fueron publicadas y reescritas intencionalmente, preferí:
git push --force-with-leaseantes que:
git push --forceUna base pragmática:
main
├── feat/...
├── fix/...
├── refactor/...
└── chore/...
Flujo:
mainsiempre estable;- rama corta por tarea;
- commits pequeños y comprensibles;
- Pull Request obligatorio para cambios importantes;
- CI ejecutándose sobre el PR;
- squash o merge según política del equipo;
- eliminar branch después del merge.
No hace falta imponer GitFlow completo si el producto no necesita ramas de release mantenidas en paralelo.
El recurso original se conserva como referencia:
Modelo mental de Git
↓
status / diff / add / commit
↓
branches
↓
merge y conflictos
↓
remotes / fetch / pull / push
↓
Pull Requests
↓
rebase / cherry-pick
↓
reset / revert / reflog
↓
SSH / seguridad
↓
tags / releases / CI
- Git: https://git-scm.com/
- Pro Git: https://git-scm.com/book/en/v2
- Git Reference: https://git-scm.com/docs
- GitHub Docs: https://docs.github.com/
- GitHub CLI: https://cli.github.com/
- Semantic Versioning: https://semver.org/
- Conventional Commits: https://www.conventionalcommits.org/
Repositorio mantenido como material práctico de referencia y formación sobre Git y GitHub.
Podés utilizar este material como referencia de estudio. Si lo reutilizás públicamente, mantené la atribución correspondiente al autor y al repositorio original.