Git 기초편 6편 — .gitignore 제대로 쓰기

"Git을 공부하면서 쓰는 시리즈" 6편입니다.

---

시작하면서

GitHub에 코드를 올리다가 실수로 올리면 안 되는 파일을 같이 올린 경험이 있습니다. 데이터베이스 비밀번호가 담긴 설정 파일이나, 수백 MB짜리 라이브러리 폴더 같은 것들이요.

올리고 나서야 알아차리는 경우가 많습니다. 커밋 기록에도 남고, 이미 공개된 저장소라면 누군가 봤을 수도 있습니다. 이걸 사전에 막는 게 .gitignore입니다.

---

.gitignore가 하는 일

.gitignore는 프로젝트 루트에 두는 텍스트 파일입니다. 여기에 적힌 파일이나 폴더는 Git이 아예 없는 것처럼 무시합니다. git status에도 안 뜨고, git add .를 해도 포함되지 않습니다.

만들어봅니다.

touch .gitignore

---

기본 패턴

파일 이름 그대로 적기

.env
secret.txt

이름이 정확히 일치하는 파일을 무시합니다.

확장자로 묶기

*.log
*.tmp
*.DS_Store

*는 "아무 문자열"을 뜻합니다. *.log는 확장자가 .log인 모든 파일을 무시합니다.

폴더 무시하기

node_modules/
dist/
.gradle/

폴더 이름 뒤에 /를 붙이면 그 폴더 전체를 무시합니다. /를 안 붙여도 동작은 하지만, 폴더라는 걸 명시적으로 표현하기 위해 붙이는 게 관례입니다.

특정 경로만 무시하기

/config.yml

맨 앞에 /를 붙이면 프로젝트 루트 기준으로만 적용됩니다. 하위 폴더에 있는 같은 이름의 파일은 무시하지 않습니다.

예외 처리 — 무시하지 않기

*.log
!important.log

!를 앞에 붙이면 "이건 무시하지 말아라"는 뜻입니다. *.log로 전체를 무시하되, important.log만 예외로 추적합니다.

---

실제로 자주 쓰는 패턴

프로젝트 종류에 따라 무시해야 하는 파일이 다릅니다. 자주 쓰이는 것들입니다.

환경 설정 파일 — API 키, 비밀번호, 토큰이 담기는 경우가 많습니다.

.env
.env.local
.env.*.local

의존성 폴더 — 패키지 매니저로 언제든 다시 설치할 수 있어서 올릴 필요가 없습니다.

node_modules/
vendor/

빌드 결과물 — 소스코드로 다시 생성할 수 있는 파일들입니다.

dist/
build/
*.class
*.pyc

에디터 설정 파일 — 개인 환경에 따라 다르기 때문에 저장소에 포함하지 않는 게 일반적입니다.

.vscode/
.idea/
*.swp

OS가 자동으로 만드는 파일

.DS_Store        # macOS
Thumbs.db        # Windows

---

gitignore.io — 자동으로 만들어주는 사이트

언어, 프레임워크, 에디터를 입력하면 .gitignore 내용을 자동으로 만들어주는 사이트가 있습니다.

gitignore.io

예를 들어 Node, macOS, VSCode를 입력하면 세 환경에 맞는 패턴을 합쳐서 보여줍니다. 처음 프로젝트를 시작할 때 여기서 생성해서 붙여넣는 게 편합니다.

---

이미 추적 중인 파일을 뒤늦게 제외하려면

여기서 많이 막힙니다. .gitignore에 추가했는데도 파일이 계속 git status에 뜨는 경우입니다.

이건 .gitignore가 잘못된 게 아닙니다. 이미 Git이 추적 중인 파일은 .gitignore가 무시하지 못합니다. 이미 한 번이라도 git add된 파일은 Git의 관리 목록에 올라가 있어서, .gitignore에 추가해도 소용이 없습니다.

해결 방법은 Git의 추적 목록에서 제거하는 겁니다. 파일 자체는 삭제하지 않고요.

git rm --cached <파일이름>

--cached가 핵심입니다. 로컬 파일은 그대로 두고, Git의 추적만 끊습니다.

폴더 전체를 한 번에 제거하려면 -r을 추가합니다.

git rm --cached -r node_modules/

이후 .gitignore에 해당 파일/폴더를 추가하고 커밋하면 됩니다.

echo "node_modules/" >> .gitignore
git add .gitignore
git commit -m "node_modules를 gitignore에 추가"

---

전역 .gitignore 설정하기

.DS_Store나 에디터 설정 파일처럼 모든 프로젝트에서 항상 무시하고 싶은 파일이 있습니다. 프로젝트마다 .gitignore에 추가하는 건 번거롭습니다.

이런 경우 전역 .gitignore를 만들어두면 됩니다.

git config --global core.excludesfile ~/.gitignore_global

~/.gitignore_global 파일을 만들고 거기에 패턴을 추가합니다.

echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global

이제 이 컴퓨터의 모든 Git 저장소에서 해당 파일들이 무시됩니다.

---

.gitignore가 잘 동작하는지 확인하기

.gitignore에 추가했는데 제대로 무시되는지 확인하고 싶을 때 쓸 수 있는 명령어가 있습니다.

git check-ignore -v <파일이름>

git check-ignore -v .env

.gitignore:1:.env   .env

.gitignore 몇 번째 줄의 어떤 패턴에 걸려서 무시되는지 알려줍니다. 패턴이 여러 개 있을 때 어느 규칙이 적용되는지 확인하기 좋습니다.

무시되지 않는 파일을 넣으면 아무 출력도 나오지 않습니다.

---

이번 편 정리

패턴	의미
secret.txt	해당 이름의 파일 무시
*.log	확장자가 .log인 모든 파일 무시
dist/	dist 폴더 전체 무시
/config.yml	루트의 config.yml만 무시
!important.log	해당 파일은 예외로 무시하지 않음

명령어	하는 일
git rm --cached <파일>	로컬 파일은 두고 Git 추적만 끊기
git rm --cached -r <폴더>	폴더 전체 추적 끊기
git check-ignore -v <파일>	어떤 규칙에 걸려 무시되는지 확인

핵심

• .gitignore는 아직 추적되지 않은 파일에만 적용된다.
• 이미 추적 중인 파일은 git rm --cached로 먼저 추적을 끊어야 한다.

---

다음 편 예고

작업하다 보면 "이 브랜치는 잠깐 놔두고 다른 브랜치로 급하게 이동해야 하는데, 커밋하기엔 아직 덜 됐다"는 상황이 생깁니다. 다음 편에서는 작업 중인 변경사항을 임시로 저장해두는 git stash를 다룹니다.