Introducción

La mayoría de la gente aprende Git de la manera difícil, a través de pequeños desastres. Esta página recopila los errores más frecuentes de principiantes y cómo evitarlos (o recuperarse de ellos). Léela una vez ahora y otra vez después de un mes de uso; la segunda pasada tendrá más sentido.

Commitear con la identidad equivocada

Olvidar establecer user.email por repositorio filtra direcciones personales en commits de trabajo. Siempre establece una identidad por repo en clones de trabajo:

git config user.email "[email protected]"
git log -1 --pretty=format:"%an <%ae>"

Commitear secretos

Las claves de API y archivos .env en commits viven para siempre, incluso después de un "borrado" de seguimiento. Añade una entrada a .gitignore antes del primer commit y rota cualquier credencial filtrada inmediatamente. Herramientas como git-secrets y gitleaks pueden ejecutarse como hooks pre-commit.

Force-pushing sobre tus compañeros

git push --force reescribe el historial en el remoto, eliminando los commits de otras personas. Prefiere --force-with-lease, que se rehúsa a sobrescribir si el remoto ha avanzado:

git push --force-with-lease

Malinterpretando pull

git pull es fetch + merge (o rebase). Ejecutarlo con cambios no commiteados puede producir merge commits sorprendentes. O bien commitea, stashea, o establece un valor predeterminado razonable:

git config --global pull.rebase true
git config --global pull.ff only

Editar HEAD desconectado sin darse cuenta

Hacer checkout de un tag o hash de commit te deja en HEAD desconectado. Los nuevos commits ahí son inalcanzables una vez que cambias. Crea siempre un branch primero:

git switch -c hotfix v1.2.3

Confundir reset, revert y restore

• git restore cambia el árbol de trabajo o el index; seguro.
• git revert crea un nuevo commit que deshace otro; seguro y compartible.
• git reset --hard mueve el branch y descarta trabajo; destructivo.

Commitear archivos enormes

Un video de 500 MB en un commit es permanente. Usa Git LFS para binarios por encima de unos pocos megabytes y mantén los artefactos de build completamente fuera del repositorio.

Kit de recuperación

git reflog
git fsck --lost-found
git stash list

El reflog registra cada movimiento de HEAD durante 90 días por defecto; casi cualquier commit "perdido" se puede recuperar de él.

Malinterpretar status

La salida de git status tiene capas sutiles. "Changes not staged for commit" significa archivos rastreados modificados en el árbol de trabajo. "Changes to be committed" significa staged. "Untracked files" significa que Git nunca los ha visto. Una confusión común: editar un archivo después de stagearlo lo muestra bajo ambas listas con contenido diferente; solo lo que está staged va al commit. Ejecuta git diff (working vs index) y git diff --staged (index vs HEAD) hasta que las tres áreas hagan clic.

git status -sb
git diff --staged --stat

Errores comunes

Entrar en pánico y ejecutar rm -rf .git cuando algo se ve mal. Detente. Haz una copia de seguridad del directorio primero. Casi cualquier error de Git es recuperable mediante el reflog o stash. El hábito más importante para principiantes: ejecuta git status antes y después de cada comando que cambia estado, y ejecuta git log --oneline --all --graph cuando algo se sienta raro.