git switch para coding agents: cambiar de rama, no restaurar archivos

git switch solo cambia de rama. El man (Git 2.50.1 / Apple Git-155; página actualizada en 2.55.0, HTTP 200 2026-09-03): actualiza working tree e index para coincidir con la rama. Los commits nuevos van al tip de esa rama.

git checkout hace dos cosas: cambiar de rama y restaurar paths. El man de checkout lo dice en la primera línea. Un agente que corre git checkout -- file “para deshacer” o git checkout main “para ver” mezcla modos. Por eso existe switch (ramas) y restore (paths) desde Git 2.23.

Esta guía no sustituye worktrees ni PRs con gh. El contrato: cuándo un agente puede switch, qué flags están prohibidas, y por qué no usa checkout.

Switch no es restore

Sin argumentos extra, git switch <branch> aborta si el cambio perdería ediciones locales. El man: no hace falta un árbol limpio; aborta solo si hay pérdida, salvo --discard-changes o --merge.

Eso no es reset. Reset mueve HEAD y puede tirar el árbol. Switch mueve HEAD a otra rama. Restore copia un path.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
Ir a una rama local	git switch <branch>	Si hay pérdida de edits, aborta. No fuerces
Rama nueva	git switch -c <nueva> [<start>]	Transaccional: si el switch falla, no crea la rama
Volver a la anterior	git switch -	- = @{-1}. No es “undo de commits”
Inspeccionar un SHA	Worktree, o switch --detach solo en worktree propio	Detached HEAD en el checkout del humano
Tracking de un remote	git switch <name> (guess)	Default --guess. Ambiguo con 2 remotes → checkout.defaultRemote

Prohibido en autónomo:

• git checkout para ramas o para files. El man de checkout: dos modos y desambiguación. Un path que parece rama, o una rama que parece path, cambia el contrato. Usa switch o restore.
• -f / --discard-changes. El man: alias. Tira index y working tree al target. Equivale a perder el trabajo local. Un agente no descarta el árbol del humano.
• -C / --force-create. Si la rama ya existe, la resetea al start-point (git branch -f + switch). Reescribe la ref. No.
• --ignore-other-worktrees. Switch se niega si otro worktree ya tiene esa rama. Eludir eso deja dos checkouts de la misma ref. Usa otro worktree.
• --orphan autónomo. El man: rama unborn; borra todos los tracked. No es “branch limpia”.
• --merge / -m en headless. Three-way merge de edits locales vs la rama destino. Conflictos quedan unmerged. El agente no resuelve a ciegas.
• Switch del checkout del humano. Cada switch reescribe el working tree. Un editor abierto pelea. Worktree propio.
• Commit o force-push desde detached HEAD de un --detach de inspección.

--guess es el default (checkout.guess). git switch feat sin rama local crea -c feat --track origin/feat si hay exactamente un remote con ese nombre. Con dos remotes, configura checkout.defaultRemote=origin o pasa el remote explícito. --no-guess desactiva el atajo.

Receta (60 segundos)

Solo en un worktree propio:

git status -sb                 # limpio; no MERGE_HEAD / rebase / BISECT
git switch -c feat/foo origin/main
# ... trabajo ...
git switch main                # o: git switch -

Rama remota que aún no existe en local:

git fetch origin
git switch feat/foo            # guess: -c + track origin/feat/foo

Inspección de un SHA sin crear rama — worktree, no detach en el árbol del humano:

git worktree add /tmp/inspect abc1234
# leer, testear; luego:
git worktree remove /tmp/inspect

Si el switch aborta (local changes to 'frotz'; not switching):

• No -f.
• Stash solo si el humano lo pidió (stash).
• O worktree nuevo desde el target.

Cero git checkout -b. Cero git checkout -- ..

-c vs -C, guess y worktrees

-c / --create: crea y cambia. El man: equivalente transaccional de git branch + git switch. Si el switch falla (rama en otro worktree, pérdida de files), no deja la rama a medias ni la resetea.

-C / --force-create: si existe, branch -f al start-point. Un agente que “reusa el nombre” pisa historial local. Crea otro nombre o usa el worktree que ya la tiene.

--detach: HEAD apunta al commit, no a una rama. El man de checkout documenta DETACHED HEAD. Commits huérfanos hasta que alguien los nombra. Inspección = worktree, no detach en el árbol compartido.

--recurse-submodules: actualiza el contenido de submodules al commit del superproyecto y detachea HEAD de cada submodule. Default: no. No lo actives “por si acaso”.

Git 2.23 partió checkout en switch + restore precisamente para este contrato. El man de checkout sigue existiendo; no es un alias. Un agente que “solo conoce checkout” mezcla restore de un file con cambio de rama.

Checklist

• Worktree propio. git status -sb limpio. No switch del árbol del humano.
• git switch <rama> o git switch -c <nueva> [<start>]. Cero checkout.
• Cero -f / --discard-changes / -C / --ignore-other-worktrees / --orphan.
• Guess: un remote. Si hay dos, checkout.defaultRemote o nombre explícito.
• Switch abortó por edits locales → worktree o stash pedido, no force.
• Paths se deshacen con restore, no con switch ni checkout.
• La rama nueva va a PR (gh), no a push de main.

FAQ

¿git switch - deshace el último commit? No. Vuelve a la rama/commit anterior del switch. Undo de commit es reset (con criterio) o revert.

¿Puedo switch -f “un segundo” para correr tests? No. -f restaura index y working tree al target. Pierdes edits. Worktree.

¿checkout -b es lo mismo que switch -c? Casi para el caso feliz. Checkout sigue pudiendo restaurar paths si la línea de comandos se parsea mal. Switch no tiene modo path. Usa switch.

¿La rama está en otro worktree? El man: switch se niega. No --ignore-other-worktrees. Trabaja en ese worktree o crea otra rama.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. Switch no es sandbox (sandboxing) ni deshacer untracked (clean).

Verificado 2026-09-03 contra git-switch(1) (Git 2.50.1 / Apple Git-155; git-scm.com/docs/git-switch HTTP 200, last updated 2.55.0) y git-checkout(1) (HTTP 200).