GitHub는 코드 협업과 저장소 공유 분야의 선두주자로 자리 잡았습니다. GitHub는 본질적으로 버전 관리 소프트웨어로, 사용자에게 분산 버전 관리와 SCM(소스 코드 관리) 기능을 제공하며 전 세계 수많은 기업과 개발팀이 이 플랫폼을 활용하고 있습니다.
다만 이러한 플랫폼에도 고유한 기술적 문제가 존재합니다. 개발자들이 자주 겪는 문제 중 하나가 바로 .gitignore가 작동하지 않는 현상입니다. Git이 .gitignore를 아예 무시하거나, 일부만 부분적으로 적용하는 경우가 발생합니다. 각 상황마다 원인이 조금씩 다를 수 있지만, 이 글에서 소개하는 해결 방법들은 대부분의 경우에 보편적으로 적용할 수 있습니다.
.gitignore란 무엇인가?
Git(GitHub)은 작업 디렉터리 내의 모든 파일을 인식하며, 각 파일을 다음 세 가지 상태 중 하나로 분류합니다.
- Tracked(추적됨): 과거에 커밋되었거나 스테이징된 적이 있는 파일입니다.
- Untracked(추적되지 않음): 아직 스테이징이나 커밋된 적이 없는 파일입니다.
- Ignored(무시됨): 사용자가 Git에게 명시적으로 무시하라고 지정한 파일입니다.
무시 대상 파일은 프로젝트 환경에 따라 달라지지만, 대부분 자동 생성 파일이나 빌드 결과물입니다. 대표적인 예는 다음과 같습니다.
- 컴파일된 코드: .class, .pyc 등의 확장자를 가진 파일
- 숨김 시스템 파일: DS_Store, Thumbs.db처럼 시스템이 사용하지만 화면에 보이지 않는 파일
- 빌드 출력 디렉터리: /bin, /out 등의 디렉터리
- 의존성 캐시: node_modules, packages 등의 모듈 폴더 내용물
- IDE 설정 파일: IDE 소프트웨어가 생성하거나 관리하는 구성 파일
- 런타임 생성 파일: 프로그램 실행 중 자동으로 생성되는 로그나 임시 파일
무시하고 싶은 파일은 .gitignore라는 특수 파일에 기록하며, 이 파일은 일반적으로 작업 저장소의 루트에 위치합니다. GitHub 공식 문서에 따르면 gitignore 전용 명령어는 따로 존재하지 않으며, 무시할 패턴을 담은 파일을 직접 작성·관리해야 합니다. .gitignore에 작성된 패턴은 저장소 내 파일명과 비교되어 특정 파일을 무시할지 여부를 결정하는 데 사용됩니다.
.gitignore가 작동하지 않는 원인
흥미롭게도 .gitignore 기능 자체는 정상적으로 작동하는 경우가 대부분이며, 문제는 사용자의 설정 방식에 있는 경우가 많습니다. 실제 사례들을 분석한 결과, 파일이 올바르게 구성되지 않았거나 Git이 무시를 적용하기 위한 전제 조건이 충족되지 않은 것이 주요 원인이었습니다.
아래에서 상황별 해결 방법을 하나씩 소개합니다. 각 방법이 모든 경우에 적용되는 것은 아니므로, 조건이 맞지 않으면 다음 방법으로 넘어가 시도해 보세요.
해결 방법 1: .gitignore 파일 형식 확인
실제로 .gitignore 파일이 잘못된 인코딩 형식으로 생성되어 문제가 발생한 사례가 있었습니다. Windows의 기본 메모장(Notepad)으로 파일을 만들면, 메모장은 ANSI가 아닌 Unicode 형식으로 저장하기 때문입니다. 이 경우 파일을 올바른 형식으로 다시 저장하면 문제가 해결될 수 있습니다.
참고: 메모장으로 새 파일을 만들 때는 반드시 .txt 확장자를 제거해야 합니다.
- 메모장에서 새 텍스트 문서에 .gitignore 내용을 작성한 뒤, 파일 > 다른 이름으로 저장을 클릭합니다.
- 인코딩 항목에서 ANSI를 선택하고, 파일 확장자 .txt를 제거한 뒤 파일명을 '.gitignore'로 지정하여 저장소 루트 디렉터리에 저장합니다.
- 해당 디렉터리로 이동해 파일이 올바르게 생성되었는지 확인한 후, Git에서 다시 테스트하여 무시 기능이 정상 작동하는지 확인합니다.
개발자라면 Windows 기본 메모장 대신 Notepad++ 같은 프로그래머용 에디터를 사용하는 것이 좋습니다. 이런 에디터에서는 인코딩 문제로 인한 오류를 피할 수 있습니다.
참고: 파일이 이미 UNICODE 형식으로 저장되어 있다면, Git이 정상적으로 인식하도록 내용을 ANSI 형식으로 다시 저장해야 합니다.
해결 방법 2: 무시하려는 파일의 추적 상태 확인
.gitignore가 작동하기 위한 또 다른 핵심 조건은, 해당 파일이 아직 저장소에 추가되지 않은 상태여야 한다는 것입니다. 이미 저장소에 추가된 파일은 .gitignore에 이름이나 규칙을 작성해도 무시되지 않습니다. 즉, Git은 오직 untracked(추적되지 않은) 파일만 무시합니다.
저장소 구조를 살펴보고, 무시하려는 파일이 이미 저장소에 포함되어 있지 않은지 확인하세요. 만약 포함되어 있다면 저장소에서 해당 파일을 먼저 제거하고, 변경 사항을 커밋한 뒤 .gitignore에 규칙을 추가해야 합니다. (파일 내용을 백업해 둔 후 삭제하고, 다른 이름으로 새로 만드는 방법도 활용할 수 있습니다.)
해결 방법 3: 저장소 파일 다시 추가하기
이미 .gitignore에 규칙을 작성했는데 무시하려는 파일들이 이미 저장소에 추가되어 있다면, 파일을 다시 추가(re-add)하는 방법을 사용할 수 있습니다. 이는 Git 인덱스에서 모든 항목을 제거한 후 다시 추가하는 과정으로, 처음부터 파일을 다시 등록하면 .gitignore의 규칙이 적용되어 올바른 파일만 추적됩니다.
참고: 작업 전에 반드시 코드를 다른 곳에 백업해 두세요. 만약을 대비한 백업은 언제나 좋은 습관입니다.
- 아래 명령을 실행하여 Git 인덱스에서 파일 경로를 재귀적으로 언스테이징하고 제거합니다.
git rm -r --cached .
- 이어서 다음 명령을 실행합니다. .gitignore의 규칙에 따라 무시해야 할 파일은 제외되고, 올바른 파일만 다시 추가됩니다.
git add .
- 마지막으로 아래 명령으로 변경 사항을 커밋합니다.
git commit -m ".gitignore is now working"
이후 저장소 상태를 확인하여 문제가 해결되었는지, .gitignore가 의도한 대로 작동하는지 검증하세요.