git error: pathspec did not match any file — что это значит

Сообщение, которое каждый видел и не один раз:

error: pathspec 'feature/login' did not match any file(s) known to git

Git не нашёл то, что ты ему указал. Pathspec — это аргумент команды, описывающий, что именно нужно затронуть. В роли pathspec может быть имя ветки, файл, тег или коммит. Конкретное сообщение нужно читать с привязкой к команде, которую ты запустил.

Топ-сценарии, в которых это всплывает

1. Чекаут несуществующей ветки

$ git checkout feature/login
error: pathspec 'feature/login' did not match any file(s) known to git

У тебя локально нет ветки feature/login. Возможные причины:

• Ветка существует только на удалённом репо. git fetch и попробуй снова.
• Ты не подтянул изменения, ветку коллега запушил позже.
• Опечатка в имени.
• Ветку удалили.

Современный git позволяет одной командой создать локальную копию удалённой ветки:

git fetch origin
git checkout feature/login

Git сам поймёт, что есть origin/feature/login, и создаст локальную ветку, отслеживающую её. Но только если ветка одна. Если в нескольких remote есть одинаковое имя — придётся писать явно:

git checkout -b feature/login origin/feature/login

2. Чекаут несуществующего файла

$ git checkout -- src/Header.tsx
error: pathspec 'src/Header.tsx' did not match any file(s) known to git

Ты пытаешься откатить изменения в файле, которого git не видит. Вероятные причины:

• Файл новый, ещё не добавлен в индекс — git checkout не работает для неотслеживаемых.
• Ты ошибся путём — например, забыл, что файл в подкаталоге.
• Файл был переименован, и ты пытаешься откатить старое имя.

Чтобы посмотреть текущее состояние:

git status
git ls-files | grep -i header

Если файл новый — для возврата к чистоте либо git clean -f src/Header.tsx (удалить), либо просто оставить как есть.

3. Регистр в имени ветки или файла

Git case-sensitive. Feature/Login и feature/login — разные ветки. Если получаешь pathspec did not match именно после копирования имени из чата или письма — проверь, нет ли там скрытых вариаций.

На macOS файловая система по умолчанию case-insensitive. Локально файл Header.tsx и header.tsx один и тот же, но в репозитории git видит их как разные. Из-за этого иногда после переименования файла git ругается, что не находит — потому что внутреннее имя не совпало.

4. git rm файла, которого нет в индексе

$ git rm src/old.tsx
fatal: pathspec 'src/old.tsx' did not match any files

Файл не отслеживается. git rm работает только для того, что уже в репозитории. Для неотслеживаемого файла достаточно обычного rm.

5. Неправильный коммит для checkout

$ git checkout abc123def
error: pathspec 'abc123def' did not match any file(s) known to git

Хеш не существует в репозитории. Возможно ты скопировал хеш из другого репо или из чата с обрезанным префиксом. git log --oneline | head -20 покажет последние коммиты — оттуда возьмёшь актуальный хеш.

6. Запутался с двойным дефисом

$ git checkout feature/login src/Header.tsx

Эта команда говорит git: «возьми файл src/Header.tsx с ветки feature/login». Если ветки feature/login нет — pathspec ругается. Если файла на этой ветке нет — то же самое. Двойной дефис помогает разделить имя ветки и путь, чтобы git не путался:

git checkout feature/login -- src/Header.tsx

Алгоритм, по которому я разбираю ошибку

• Прочитал команду — что она хотела сделать?
• Что в ней — pathspec? Имя ветки, файл, хеш?
• Существует ли это в текущем репозитории? Проверь git branch -a, git ls-files, git log.
• Сделал ли я git fetch, прежде чем работать с удалёнными ветками?
• Не ошибся ли в регистре или префиксе?

Тонкость про fetch и pruning

Если коллега удалил ветку, у тебя локально она всё ещё может маячить как origin/feature/login. git fetch по умолчанию не удаляет такие следы. Если хочется чистоты:

git fetch --prune

Это синхронизирует локальные ссылки на удалённые ветки и удалит те, что уже не существуют. Прописать в конфиг автоматический prune:

git config --global fetch.prune true

После этого каждый git fetch сам подметает за собой.

Когда виноват симлинк или подмодуль

Если в репо есть подмодули и ты пытаешься сделать git checkout на путь внутри подмодуля без его инициализации, тоже может прилететь pathspec did not match. Лечится через git submodule update --init --recursive.

Чек-лист

• Что я указал? Имя ветки, файл, хеш — что-то одно.
• Сделал ли я git fetch?
• Существует ли это сейчас в репо? git branch -a, git ls-files.
• Не путаю ли регистр?
• Использую ли я -- для отделения имени ветки от пути?

Pathspec did not match — это всегда «не нашёл то, что просили». Дальше дело на пять минут: понять, что именно git не видит, и либо подтянуть, либо поправить путь. Никаких ритуалов и волшебных команд — просто прочитать сообщение и отреагировать.