로컬 머신에 새 파일을 만든 상태에서, 해당 파일을 저장소에 추가하지 않은 채 원격 저장소를 pull하면 nothing added to commit but untracked files present라는 Git 오류가 발생합니다.
이 글에서는 이 오류가 무엇을 의미하는지 살펴보고, 두 가지 해결 방법과 각각의 장단점까지 자세히 안내합니다.
오류가 발생하는 이유
Git은 분산 버전 관리 시스템입니다. 즉, 저장소의 로컬 복사본을 만들어 그 안에서 자유롭게 변경 작업을 할 수 있으며, 변경 사항을 커밋(commit)하기 전까지는 메인 프로젝트에 반영되지 않습니다.
원격 서버에서 코드를 pull할 때는 로컬 머신의 모든 파일이 Git 스테이징 영역(staging area)에 있거나 커밋에 포함되어 있어야 합니다. Git이 어떤 파일이 저장소의 일부인지 알아야 하기 때문입니다.
모든 파일을 스테이징 영역이나 커밋에 추가하지 않은 상태에서 git pull 명령을 실행하면 다음과 같은 오류가 발생합니다:
nothing added to commit but untracked files present
추적되지 않은 파일(Untracked Files)이란?
추적되지 않은 파일(untracked file)이란 Git으로 관리되도록 설정된 프로젝트 안에 있지만, 아직 Git 저장소의 일부가 되지 않은 파일을 말합니다.
파일은 git add 명령으로 추가했을 때에만 저장소의 일부가 됩니다. 덕분에 개발자는 저장소의 개발 라인에 포함시키고 싶지 않은 파일을 로컬에서 자유롭게 생성하고 수정할 수 있습니다.
추적되지 않은 파일은 프로젝트에 추가하거나, .gitignore 파일의 규칙으로 무시(ignore) 처리해 주어야 합니다.
해결 방법 1: 파일을 스테이징 영역에 추가하기
첫 번째 방법은 추적되지 않은 모든 파일을 Git 저장소에 추가하는 것입니다. git add 명령을 사용합니다:
git add file_to_add.md
이 명령은 해당 파일을 스테이징 영역으로 옮깁니다. 스테이징 영역에 추가된 파일은 추적(tracked) 상태가 되며, 제거하지 않는 한 다음 커밋에 포함됩니다. Git이 커밋에 어떤 파일을 포함해야 하는지 알기 위해서는 이렇게 파일을 추적해야 합니다.
해결 방법 2: .gitignore로 파일 무시하기
두 번째 방법은 해당 파일들을 무시하는 것입니다. 생성한 파일을 Git 저장소에 포함하고 싶지 않다면 이 방법이 적합합니다. API 키를 담고 있는 설정 파일이나 로컬 의존성 저장 폴더(node_modules 등)가 대표적인 예입니다.
프로젝트의 .gitignore 파일에 항목을 추가하면 파일을 무시할 수 있습니다:
file_to_add.md directory/
.gitignore 파일은 프로젝트의 어느 디렉터리에든 둘 수 있지만, 접근성을 위해 저장소 루트 폴더에 두는 것이 좋습니다. .gitignore 파일의 모든 규칙은 해당 파일이 위치한 폴더와 그 하위의 파일·폴더에 재귀적으로 적용됩니다.
오류 해결 후 다시 pull하기
오류를 해결했다면 이제 git pull 명령으로 최신 버전의 저장소를 가져올 수 있습니다:
git pull
이제 프로젝트 폴더의 모든 파일이 추적되거나 무시되었기 때문에 이 명령은 정상적으로 실행됩니다.
마무리
nothing added to commit but untracked files present 오류는 저장소의 로컬 작업 복사본에서 새 파일을 만든 뒤, 새 버전을 pull하기 전에 스테이징 영역에 추가하는 것을 잊었을 때 발생합니다.
이 오류를 해결하려면 오류의 원인이 되는 파일을 스테이징 영역에 추가하거나, .gitignore 파일로 무시하면 됩니다. 이제 여러분도 흔히 발생하는 이 Git 오류를 전문가처럼 해결할 수 있습니다.