기술 · 실용 가이드

Git의 “pathspec did not match” 오류는 먼저 인수 유형을 증명하세요

실패한 인수가 로컬 브랜치, 원격 브랜치, 커밋, 추적 경로 중 무엇인지 확인한 뒤 가져오기·생성·전환·복원을 실행합니다.

작성 Watch at Ease News · 5 분 읽기발행 2026. 10. 17. 오전 10:25 UTC

“pathspec did not match any file(s) known to git” 메시지만으로는 의도한 대상이 브랜치, 커밋, 추적 경로인지 알 수 없습니다. 먼저 원래 명령과 저장소 상태를 보존해야 합니다.

이 가이드는 fetch, 브랜치 생성, restore, reset, clean 전에 ref, 객체, 인덱스, 트리를 읽기 전용으로 검사합니다. 저장소 루트나 대상이 불확실하면 중단합니다.

저장소와 정확한 명령 보존

전체 명령, 오류, 작업 디렉터리, 철자, 셸 인용을 복사합니다. ref나 파일을 바꾸기 전에 git rev-parse --show-toplevel, git status --short --branch, git remote -v, git --version을 기록합니다.

git reset --hard, git clean, 광범위 fetch, 추측한 브랜치 생성부터 시작하지 마세요. 증거를 없애거나 원래 의도를 해결하지 않고 오류만 숨길 수 있습니다.

기존 로컬 브랜치, 원격 브랜치, 새 브랜치, 커밋·태그, 추적 경로 중 예상 유형 하나를 적습니다. checkout은 여러 모드를 가지며 refs, 인덱스, 트리, --에 따라 의미가 달라집니다.

이 선언은 가설이지 해결책이 아닙니다. 브랜치 같은 이름은 존재를, 파일 같은 이름은 추적 여부를, 짧은 해시는 로컬 객체를 증명하지 않습니다.

로컬 브랜치는 git show-ref --verify refs/heads/NAME과 git branch --all --no-color로 확인합니다. 원격은 git ls-remote --heads REMOTE NAME으로 변경 없이 조회하고 상태를 기록합니다.

원격에만 있으면 해당 ref를 정확히 fetch한 뒤 추적 브랜치를 만듭니다. 새 브랜치라면 START를 증명한 후 git switch -c NAME START를 사용하며, 생성을 진단 지름길로 쓰지 않습니다.

git rev-parse --verify --end-of-options ARG^{commit}으로 현재 객체 데이터베이스의 커밋인지 확인합니다. 실패는 로컬에서 해석되지 않는다는 뜻이며 어느 원격에 있는지는 증명하지 않습니다.

fetch 전에 원격 ref, 태그, PR ref, 서브모듈 기록, 다른 저장소 등 출처를 확인합니다. 검증된 최소 ref만 가져옵니다.

git ls-files --error-unmatch -- PATH로 인덱스를 바꾸지 않고 검사합니다. 다른 트리는 git ls-tree -r --name-only TREE -- PATH로 확인하고 대소문자, 구분자, 상대 표기, 셸 확장을 점검합니다.

경로라면 git restore --source=TREE -- PATH처럼 --를 둡니다. 예전 절차는 git checkout TREE -- PATH를 사용해 경로 해석을 강제합니다.

기존 로컬은 전환하고, 새 브랜치는 증명된 시작점에서 생성하며, 원격 전용은 정확히 가져와 추적합니다. 커밋은 의도한 경우만 detached checkout하고, 경로는 --로 복원합니다.

어느 네임스페이스에도 없으면 문서, 티켓, CI 변수, 스크립트 등 이름의 출처로 돌아갑니다. 부재가 결론이며 서브모듈, sparse checkout, shallow clone은 별도로 조사합니다.

수정된 명시적 명령으로 의도를 다시 실행하고 git status --short --branch, git rev-parse --verify HEAD와 필요한 branch 또는 path 증거를 확인합니다.

생성 ref, fetch ref, 복원 경로, 이전 HEAD, 명령을 기록합니다. 고유 작업이 없음을 증명한 후 잘못 만든 브랜치를 삭제하고 검증된 트리에서만 복원합니다.