git checkout

Ramas y merges

Cambiar de rama o restaurar archivos del árbol de trabajo

git checkout es un comando versátil que cambia de rama, crea ramas nuevas, restaura archivos de commits concretos y puede dejar tu repositorio en estado «HEAD separado» (detached HEAD). Aunque las versiones recientes de Git repartieron parte de sus funciones entre «git switch» y «git restore», checkout sigue siendo muy usado y conocido.

Sinopsis

git checkout <branch>
git checkout -b <new-branch> [<start-point>]
git checkout -B <branch> [<start-point>]
git checkout --detach [<branch>]
git checkout [--] <pathspec>...
git checkout <commit> -- <pathspec>...
[ ] opcional| o<arg> valor a sustituir... repetible--flag opción

Opciones

Haz clic en una opción para desplegarla

Principiante (3)

Crear una rama nueva y cambiarte a ella de inmediato. Equivale a ejecutar git branch <name> y después git checkout <name>.

RecomendadoCrea y cambia en un paso (forma moderna: git switch -c)

Ejemplo

git checkout -b feature-login

Descartar los cambios sin preparar de los archivos indicados, restaurándolos desde el área de preparación (el índice), no desde HEAD. Los cambios preparados se conservan. El -- separa las rutas de archivo de los nombres de rama.

Cuando haga faltaDescarta para siempre los cambios sin preparar; git restore <file> es la forma moderna

Ejemplo

git checkout -- src/app.js

Silenciar los mensajes informativos. Útil en scripts donde no necesitas las confirmaciones «Switched to branch».

Cuando haga faltaSuprime los mensajes; sobre todo para scripts

Ejemplo

git checkout -q main

Intermedio (8)

Crear una rama nueva, o reiniciarla si ya existe, y cambiarte a ella. Útil para reiniciar una rama en el commit actual.

No recomendadoRestablece sin avisar una rama existente y puede dejar huérfanos sus commits

Ejemplo

git checkout -B feature-login

Al crear una rama nueva, configurar el seguimiento de la rama upstream. Permite git pull/push sin indicar el remoto.

RecomendadoCrea una rama local enlazada con una rama remota

Ejemplo

git checkout --track origin/feature

Al crear una rama nueva desde una rama de seguimiento remoto, no configurar el seguimiento. La rama será independiente.

Cuando haga faltaCrea una rama a partir de una remota sin enlazarla como upstream

Ejemplo

git checkout --no-track -b feature origin/main

Separar HEAD en el commit indicado. Puedes revisar código antiguo o experimentar sin afectar a ninguna rama.

Cuando haga faltaInspeccionar un commit antiguo; crea una rama antes de hacer commit ahí

Ejemplo

git checkout --detach v1.0.0

Restaurar un archivo a su estado en un commit concreto. El archivo queda tanto en tu directorio de trabajo como en el área de preparación.

Cuando haga faltaRecupera la versión antigua de un archivo, preparada, sin cambiar de rama

Ejemplo

git checkout a1b2c3d -- src/app.js

Forzar el checkout aunque haya cambios sin commit. Descarta TODAS las modificaciones locales de los archivos con seguimiento (no solo las que chocan) y cualquier archivo sin seguimiento que estorbe.

No recomendadoTira todos los cambios sin commit de los archivos con seguimiento; mejor usa stash

Ejemplo

git checkout -f main

Durante un conflicto de merge, hacer checkout de nuestra versión (la rama en la que estabas) del archivo en conflicto. Útil para resolver eligiendo un lado. Ojo: durante un rebase, ours/theirs se invierten.

Cuando haga faltaResuelve un archivo en conflicto quedándote con tu lado (los lados se invierten en un rebase)

Ejemplo

git checkout --ours config.js

Durante un conflicto de merge, hacer checkout de su versión (la rama que se está integrando) del archivo en conflicto. Acepta los cambios entrantes. Ojo: durante un rebase, ours/theirs se invierten.

Cuando haga faltaResuelve un archivo en conflicto quedándote con el lado que llega

Ejemplo

git checkout --theirs config.js

Avanzado (3)

Crear una rama nueva sin nacer y sin historial de commits. Los archivos actuales se quedan en el árbol de trabajo y en el área de preparación; el primer commit de esta rama no tendrá padre, lo que crea un historial independiente.

Cuando haga faltaEmpieza un historial independiente (gh-pages, docs); casi nunca hace falta

Ejemplo

git checkout --orphan gh-pages

Al cambiar de rama con cambios locales en archivos que difieren entre las dos ramas, llevárselos con un merge a tres bandas en lugar de negarse; los conflictos se quedan en el árbol de trabajo para resolverlos. Desde Git 2.55 los cambios locales se guardan antes en una entrada de stash, así que un cambio de rama con conflictos ya no puede perderlos.

Cuando haga faltaLleva los cambios locales a otra rama; puede dejar conflictos

Ejemplo

git checkout -m feature

Elegir de forma interactiva qué fragmentos descartar del directorio de trabajo. Te permite conservar unos cambios y revertir otros en el mismo archivo.

Cuando haga faltaSolo descarta los hunks elegidos: revisa bien cada pregunta

Ejemplo

git checkout -p -- app.js

Elegir la opción adecuada

Crear ramas

Distintas formas de crear una rama nueva y cambiarte a ella

ComandoSi la rama existeHistorialIdeal para
-b <name>Falla con un errorNormal (conectada)Trabajo habitual en una funcionalidad nueva
-B <name>Se reinicia en el commit actualNormal (conectada)Empezar una rama desde cero
--orphan <name>Falla con un errorNinguno (desconectada)gh-pages, docs, empezar de cero

Cambiar de rama con cambios sin commit

Qué pasa con tus cambios locales al cambiar de rama

ComandoCambios sin commitNivel de riesgoCuándo usarla
git checkout <branch>Bloqueado si hay conflictoSeguroComportamiento por defecto: evita accidentes
git checkout -f <branch>Se descartan para siemprePeligrosoAbandonar a propósito todos los cambios locales
git checkout -m <branch>Se integran con un merge a tres bandasMediaLlevarte los cambios a otra rama
git stash + checkoutGuardados para despuésSeguroCambio de contexto temporal

Restaurar archivos

Descartar o restaurar el contenido de archivos desde distintas fuentes

ComandoOrigenAfecta a la preparaciónRecuperable
-- <file>Índice (versión preparada)NoNo: los cambios se pierden para siempre
<commit> -- <file>Un commit concretoSí (preparado)No, pero queda preparado para revisar
-p -- <file>Índice (interactivo)NoParcial: eliges los fragmentos

Seguimiento de ramas remotas

Controlar la relación entre ramas locales y remotas

ComandoCrea seguimientoCaso de usogit push/pull
--track origin/featSí (automático)Trabajar en la rama de un compañeroFunciona sin argumentos
--no-track -b exp origin/mainNo (independiente)Experimentar sin riesgoExige indicar el remoto
<remote-branch>Sí (si no hay ambigüedad)Checkout rápido de una rama remotaFunciona sin argumentos

Resolver conflictos de merge

Elegir un lado durante un conflicto de merge

ComandoConservaDescartaCuándo usarla
--ours <file>La versión de tu ramaCambios entrantesTus cambios son los correctos
--theirs <file>Versión entranteTus cambiosAceptar su implementación
(manual edit)Resultado combinadoNadaNecesitas partes de ambos lados

checkout frente a los comandos modernos

Git 2.23+ dividió checkout en comandos específicos

ComandoCambia de ramaRestaura archivosRecomendado para
git checkoutSíSíCostumbre, versiones antiguas de Git
git switchSíNoIntención clara: solo operaciones de ramas
git restoreNoSíIntención clara: solo operaciones de archivos

Ejemplos de flujos de trabajo

1
git stash

Guardar el trabajo actual sin commit

2
git checkout other-branch

Cambiarse a la otra rama

3
(review or make quick fix)

Hacer el trabajo necesario en esta rama

4
git checkout -

Volver a la rama anterior (atajo)

5
git stash pop

Recuperar el trabajo guardado

1
git checkout main

Cambiarse a la rama main

2
git pull origin main

Traer los últimos cambios del remoto

3
git checkout -b feature-name

Crear la nueva rama de funcionalidad y cambiarse a ella

4
(make changes and commits)

Trabajar en la funcionalidad

5
git push -u origin feature-name

Subir la rama y configurar el seguimiento

1
git status

Ver qué archivos se han modificado

2
git diff file.js

Revisar los cambios que vas a descartar

3
git checkout -- file.js

Descartar los cambios de un archivo concreto

4
git checkout -- .

O descartar TODOS los cambios sin preparar de los archivos con seguimiento

1
git log --oneline

Encontrar el hash del commit que necesitas

2
git checkout <commit-hash>

Hacer checkout de ese commit concreto (HEAD separado)

3
(inspect, test, or debug)

Investigar el código antiguo

4
git checkout main

Volver a la rama main al terminar

1
git log --oneline -- file.js

Encontrar los commits que cambiaron este archivo

2
git show <commit>:file.js

Ver la versión antigua

3
git checkout <commit> -- file.js

Restaurar el archivo desde ese commit (queda preparado)

4
git commit -m 'Restore file.js'

Hacer commit de la versión restaurada

1
git fetch origin

Traer la información más reciente de las ramas remotas

2
git branch -r

Ver las ramas remotas disponibles

3
git checkout --track origin/feature

Crear una rama local que sigue a la remota

4
git pull

Ahora pull funciona sin indicar el remoto

Solución de problemas

error: Your local changes to the following files would be overwritten by checkout

Causa: Tienes cambios sin commit que chocan con la rama de destino

Haz commit de tus cambios, guárdalos con stash o usa -f para forzar (descarta los cambios)

git stash && git checkout branch && git stash pop

error: pathspec 'branch-name' did not match any file(s) known to git

Causa: La rama no existe, o quizá escribiste mal el nombre

Consulta las ramas disponibles con git branch -a, o crea la rama con -b

git branch -a | grep branch-name

You are in 'detached HEAD' state

Causa: Hiciste checkout de un hash de commit o de una etiqueta en lugar de un nombre de rama

Si quieres seguir trabajando, crea una rama. Si no, haz checkout de una rama existente

git checkout -b new-branch-name

Se pierden los commits hechos con HEAD separado

Causa: Hiciste commits con HEAD separado y luego te cambiaste a otra rama

Encuentra los commits con el reflog y crea una rama para conservarlos

git reflog && git branch recovered-work <commit-hash>

No se puede hacer checkout: se sobrescribiría un archivo sin seguimiento

Causa: Tienes archivos sin seguimiento que existen en la rama de destino

Borra, mueve o guarda con stash primero esos archivos sin seguimiento

git stash --include-untracked && git checkout branch

Descartaste cambios sin querer con checkout --

Causa: git checkout -- <file> elimina para siempre los cambios sin commit

Por desgracia, Git no puede recuperarlos. Revisa el historial local de tu editor

(check IDE local history if available)

fatal: 'name' could be both a local file and a tracking branch

Causa: Un archivo o carpeta tiene el mismo nombre que la rama remota de la que quieres hacer checkout

Añade un -- al final para indicar a Git que el nombre es una rama, o usa git switch

git checkout branch-name --

La rama no se actualiza tras el checkout

Causa: Puede que hayas hecho checkout directamente de una rama de seguimiento remoto

Crea una rama local de seguimiento en lugar de hacer checkout directo de origin/branch

git checkout --track origin/branch-name

Consejos y trampas

Buenas prácticas

  • ✓Usa 'git stash' antes de cambiar de rama si tienes trabajo sin commit que quieres conservar
  • ✓Mejor 'git checkout -b' que 'git branch' + 'git checkout' por separado para crear una rama y cambiarte a ella
  • ✓Usa '--' para separar claramente las rutas de archivo de los nombres de rama: 'git checkout -- file.txt'
  • ✓Plantéate usar los comandos modernos 'git switch' para ramas y 'git restore' para archivos: la intención queda más clara
  • ✓Usa 'git checkout -' para volver rápido a la rama anterior (como 'cd -')
  • ✓Antes de usar '-f' para forzar el checkout, asegúrate de que de verdad quieres descartar tus cambios
  • ✓Con HEAD separado (detached), crea una rama enseguida si piensas hacer commits
  • ✓Usa '--track' al hacer checkout de ramas remotas para configurar push/pull automáticamente
  • ✓Usa 'git checkout <commit> -- <file>' para restaurar archivos concretos sin cambiar de rama
  • ✓Evita hacer checkout de commits directamente salvo para investigar: usa nombres de rama para el trabajo normal
  • ✓Usa '-p' (modo patch) cuando quieras descartar solo algunos cambios de un archivo
  • ✓Comprueba siempre que estás en la rama correcta con 'git branch' o 'git status' antes de ponerte a trabajar

Errores comunes

  • ✗Intentar un checkout con cambios sin commit. Git se niega a cambiar si eso sobrescribiría tus cambios: haz commit, stash o usa -f para forzar (descarta los cambios).
  • ✗Confundir checkout para ramas con checkout para archivos. Restaurar archivos sin querer al intentar cambiar de rama: pon -- antes de las rutas: git checkout -- file.txt
  • ✗Hacer commits con HEAD separado (detached). Esos commits quedan huérfanos al hacer checkout de otra rama: crea antes una rama: git checkout -b my-branch
  • ✗Usar -B sin entender que sobrescribe. Puede hacerte perder la posición de la rama existente: usa -b para ramas nuevas y -B solo cuando quieras reiniciarla a propósito.

Preguntas frecuentes

A:

'git switch' es un comando más nuevo (Git 2.23+) que solo sirve para cambiar de rama, así que es más claro y seguro. 'git checkout' puede tanto cambiar de rama COMO restaurar archivos, lo que puede confundir. Usa 'git switch' para ramas y 'git restore' para archivos si prefieres el enfoque moderno.

A:

Por desgracia, con Git solo no se puede: los cambios se descartan para siempre. Algunos IDE tienen historial local que puede ayudar. Por eso hay que tener cuidado con este comando.

A:

HEAD separado (detached) significa que has hecho checkout de un commit concreto en lugar de una rama. Puedes curiosear y hacer commits, pero no pertenecerán a ninguna rama. Crea una rama con 'git checkout -b name' para guardar tu trabajo.

A:

'-b' crea una rama nueva y falla si ya existe. '-B' crea una rama nueva o reinicia una existente en la posición actual. Usa '-B' cuando quieras reiniciar una rama a propósito.

A:

Usa 'git checkout other-branch -- path/to/file'. Copia el archivo de esa rama a tu directorio de trabajo y al área de preparación. Después puedes hacer commit en tu rama actual.

A:

Git te protege de perder trabajo. Si cambiar de rama sobrescribiría tus cambios, se niega. Haz commit de tus cambios, guárdalos con 'git stash' o usa 'git checkout -f' para forzar (lo que descarta los cambios).

A:

Te cambia a la rama en la que estabas antes, como 'cd -' en la shell. Es una forma rápida de alternar entre dos ramas en las que trabajas.

A:

Primero haz 'git fetch origin' y luego 'git checkout branch-name' (Git crea automáticamente una rama de seguimiento si existe origin/branch-name) o, de forma explícita, 'git checkout --track origin/branch-name'.

A:

Sí: usa 'git checkout -p <commit> -- <file>' para el modo interactivo, o simplemente 'git checkout <commit> -- <specific-files>' para restaurar solo ciertos archivos de ese commit.

A:

Porque hace dos cosas muy distintas: cambiar de rama Y restaurar archivos. Git 2.23 introdujo 'git switch' y 'git restore' para separar esas tareas. 'git checkout' sigue funcionando y se usa muchísimo.