Tecnología · GUÍA PRÁCTICA
¿Git dice “pathspec did not match”? Clasifica primero el argumento
Demuestra si el argumento debía ser una rama local, rama remota, commit o ruta seguida antes de obtener, crear, cambiar o restaurar nada.
El mensaje “pathspec did not match any file(s) known to git” no revela si querías nombrar una rama, un commit o una ruta seguida. Conserva primero el comando exacto y el estado del repositorio.
Esta guía comprueba refs, objetos, índice y árboles sin modificar nada antes de fetch, creación de ramas, restore, reset o clean. Detente si no está claro el repositorio o el objetivo.
Conserva el repositorio y el comando exacto
Copia el comando, error, directorio, ortografía y comillas del shell. Antes de cambiar refs o archivos registra git rev-parse --show-toplevel, git status --short --branch, git remote -v y git --version.
No empieces con git reset --hard, git clean, un fetch amplio ni una rama inventada. Puedes borrar evidencia u ocultar el error sin resolver la intención original.
Decide qué sustantivo debía nombrar el argumento
Anota un tipo esperado: rama local existente, rama remota, rama nueva, commit o etiqueta, o ruta seguida. checkout tiene varios modos y un token cambia de significado según refs, índice, árbol y --.
Es una hipótesis, no una solución. Un nombre parecido a rama no prueba su existencia, uno parecido a archivo no prueba seguimiento y un hash corto no prueba un objeto local.
Demuestra el estado de las ramas locales y remotas
Para una rama local usa git show-ref --verify refs/heads/NAME y git branch --all --no-color. Consulta una rama remota sin mutar con git ls-remote --heads REMOTE NAME y registra el estado.
Si solo existe remotamente, obtén ese ref exacto y crea deliberadamente una rama de seguimiento. Para una rama nueva usa git switch -c NAME START únicamente tras probar START.
Demuestra un commit o una etiqueta antes del checkout
Usa git rev-parse --verify --end-of-options ARG^{commit} para probar que el argumento resuelve a un commit local. El fallo solo indica que no resuelve localmente; no demuestra qué remoto lo contiene.
Antes de fetch identifica la fuente prometida: ref remoto, etiqueta, ref de PR, registro de submódulo u otro repositorio. Obtén el ref mínimo verificado.
Demuestra una ruta seguida en el índice u otro árbol
Usa git ls-files --error-unmatch -- PATH para probar el índice sin modificarlo. En otro árbol usa git ls-tree -r --name-only TREE -- PATH. Revisa mayúsculas, separadores, forma relativa y expansión del shell.
Cuando pretendes una ruta, usa git restore --source=TREE -- PATH o el flujo antiguo git checkout TREE -- PATH. El separador fuerza la interpretación como ruta.
Asocia la evidencia con una sola acción limitada
Cambia a una rama local existente; crea una nueva desde un inicio probado; obtén y sigue una rama solo remota; usa detached checkout solo si es intencional; restaura una ruta probada con --.
Si ningún espacio contiene el argumento, vuelve a su origen: documentación, ticket, variable CI, script o persona. La ausencia es el hallazgo; submódulos, sparse checkout y clones shallow requieren pruebas separadas.
Verifica el resultado y conserva evidencia de reversión
Repite la intención con el comando explícito corregido y verifica git status --short --branch, git rev-parse --verify HEAD y la evidencia de rama o ruta necesaria.
Registra refs creados, ref exacto obtenido, ruta restaurada, HEAD anterior y comando. Borra una rama accidental solo tras probar que no tiene trabajo único y restaura desde un árbol verificado.
