git checkout

Qué hace git checkout

git checkout es uno de los comandos más versátiles de Git. Realiza dos tareas distintas:

1. Cambiar de rama — mueve HEAD para apuntar a otra rama y actualiza los archivos de tu directorio de trabajo para que coincidan con el último commit de esa rama.
2. Restaurar archivos — sobreescribe archivos en tu directorio de trabajo (o en el área de preparación) con una versión de un commit, una rama o el índice.

HEAD es el puntero de Git a "dónde estás ahora" — normalmente el extremo de la rama que tienes actualmente activa. Cuando ejecutas git checkout, Git mueve HEAD y reescribe tus archivos rastreados para que el árbol de trabajo refleje el destino.

Debido a que el comando tiene múltiples funciones, Git moderno (2.23+) dividió sus dos roles en dos comandos más claros: git switch para moverse entre ramas y git restore para descartar cambios en archivos. git checkout sigue funcionando exactamente igual que antes y se muestra a lo largo de esta página, con los equivalentes modernos indicados donde resulta útil.

Esta página cubre cómo hacer checkout de ramas existentes y nuevas, cómo trabajar con ramas remotas, cómo restaurar archivos y el estado de "HEAD desconectado".

Hacer checkout de una rama existente

Si un repositorio ya contiene varias ramas, git checkout <branch> cambia a una de ellas. Ejecuta primero git branch para listar las ramas disponibles; la rama actual está marcada con un asterisco:

Listar ramas y cambiar a una de ellas

$ git branch
* master
  test_branch
  feature_branch

$ git checkout feature_branch
Switched to branch 'feature_branch'

Después del cambio, tu directorio de trabajo coincide con el último commit en feature_branch, y los nuevos commits que crees se registrarán allí. El equivalente moderno es git switch feature_branch.

Git se negará a cambiar si tienes cambios sin confirmar que serían sobreescritos por la rama de destino. En ese caso, confírmalos, guárdalos temporalmente o descártalos primero.

Crear y hacer checkout de una nueva rama

Para crear una rama y cambiar a ella en un solo paso, usa el indicador -b:

git checkout -b

git checkout -b new_branch

El indicador -b le dice a Git que ejecute git branch new_branch (crear la rama desde el HEAD actual) y luego haga inmediatamente git checkout new_branch. Es equivalente a:

git branch new_branch
git checkout new_branch

De forma predeterminada, la nueva rama parte de tu HEAD actual. Para basarla en una rama o commit diferente, especifica un punto de inicio:

git checkout -b desde un punto de inicio específico

git checkout -b new_branch existing_branch

Aquí new_branch se crea en el extremo de existing_branch en lugar de en el HEAD actual. El equivalente moderno es git switch -c new_branch existing_branch.

Cambiar de rama y HEAD

Ejecutar git checkout <branch> apunta HEAD al extremo de esa rama:

git checkout main

Si cambias por error o pierdes el rastro de dónde ha estado HEAD, el comando git reflog lista cada posición que ha tenido HEAD, para que puedas volver a un estado anterior.

Hacer checkout de una rama remota

Cuando trabajas en equipo, el repositorio remoto contiene ramas que otras personas han subido. Para verlas y hacer checkout de ellas, primero descarga los datos remotos más recientes con git fetch:

git fetch --all

Git moderno puede entonces hacer checkout de una rama remota por su nombre corto. Git crea automáticamente una rama local que rastrea la rama remota correspondiente:

git checkout feature_branch

Esto funciona solo cuando exactamente un remoto tiene una rama con ese nombre. Si el nombre es ambiguo, o quieres ser explícito, crea una rama local de seguimiento desde la referencia de seguimiento remoto:

Crear una rama local desde una remota

git checkout -b feature_branch origin/feature_branch

El indicador -b es obligatorio aquí — la nueva rama local feature_branch se crea en, y se configura para rastrear, origin/feature_branch. Para forzar que una rama local existente coincida exactamente con el extremo remoto, usa git reset:

git reset --hard origin/feature_branch

git reset --hard descarta los commits locales y los cambios sin confirmar en esa rama, así que úsalo solo cuando tengas intención de descartar el trabajo local.

Restaurar archivos con git checkout

Además de cambiar de rama, git checkout puede reemplazar archivos en tu árbol de trabajo con una versión del índice o de otro commit.

Descarta los cambios sin confirmar en un solo archivo y restaura la versión del último commit:

Descartar cambios en un archivo

git checkout -- file.txt

El -- separa las opciones del comando de la ruta del archivo, lo que evita ambigüedades cuando un archivo y una rama comparten el mismo nombre. El equivalente moderno es git restore file.txt.

Restaura un archivo tal como existía en un commit o rama específicos, sin cambiar de rama:

Restaurar un archivo desde otro commit

git checkout <commit> -- file.txt

Esto actualiza file.txt en tu directorio de trabajo y área de preparación con su contenido en <commit>, mientras que HEAD permanece en tu rama actual. Consulta git restore para ver la sintaxis moderna más clara.

Estado de HEAD desconectado

Hacer checkout de un commit específico (en lugar de una rama) te pone en un estado de HEAD desconectado:

git checkout a1b2c3d

Normalmente HEAD apunta a una rama, que a su vez apunta a un commit. Cuando haces checkout de un commit directamente, HEAD apunta directamente a ese commit sin ninguna rama adjunta — eso es lo que significa "desconectado". Es útil para examinar o probar un estado antiguo del proyecto.

El riesgo es que cualquier commit que hagas en este estado no está en ninguna rama. En cuanto hagas checkout de otra rama, esos commits no tienen ninguna referencia que apunte a ellos y se vuelven difíciles de encontrar (Git eventualmente los eliminará mediante recolección de basura). Si decides conservar el trabajo realizado en un HEAD desconectado, dale una rama antes de salir:

git switch -c new_branch

Entonces: examinar un commit antiguo en un HEAD desconectado es perfectamente seguro, pero realiza cualquier desarrollo nuevo en una rama real para que tus commits permanezcan accesibles. El git reflog también puede ayudarte a recuperar commits si te olvidas.

Práctica