초보자를 위한 .gitignore 사용법 완벽 정리

초보자를 위한 .gitignore 사용법 완벽 정리

📌 이 글의 핵심 요약

• .gitignore는 Git이 추적하지 않을 파일과 폴더를 지정하는 설정 파일이다
• 프로젝트 루트에 생성하고 패턴 문법으로 제외 대상을 작성한다
• 이미 커밋된 파일은 .gitignore만으로 제외되지 않으며 별도 처리가 필요하다
• gitignore.io 사이트에서 언어·환경별 템플릿을 바로 생성할 수 있다

📋 목차

1. .gitignore가 필요한 이유
2. .gitignore 파일 생성과 기본 문법
3. 언어·환경별 필수 제외 항목
4. 이미 추적 중인 파일 제외하는 방법
5. 실전 팁과 자주 하는 실수
6. 정리 및 결론

.gitignore가 필요한 이유

Git을 처음 쓰다 보면 node_modules 폴더 전체나 .env 파일이 GitHub에 올라가는 상황을 겪는다. node_modules는 수만 개 파일이 담긴 디렉터리라 저장소 크기가 폭발적으로 늘어나고, .env에는 API 키나 DB 비밀번호 같은 민감한 정보가 담겨 있어 노출되면 보안 사고로 이어진다.

.gitignore 파일은 Git이 처음부터 아예 바라보지 않을 파일과 폴더를 지정한다. 한 번 등록해두면 git add를 실행해도 해당 파일은 스테이징 대상에서 제외된다. 프로젝트를 시작할 때 .gitignore를 먼저 만드는 것이 Git 워크플로의 기본 습관이다.

---

.gitignore 파일 생성과 기본 문법

파일 이름은 정확히 .gitignore다. 확장자 없이 점으로 시작하는 숨김 파일 형태로, 프로젝트 루트 디렉터리에 위치시킨다. VS Code 탐색기나 터미널에서 직접 생성하면 된다.

# 특정 파일 제외 .env secret.json # 특정 폴더 전체 제외 node_modules/ .next/ dist/ # 확장자로 제외 *.log *.tmp # 특정 경로만 제외 config/secrets.json # 예외 처리 (앞에 !) *.env !.env.example

📝 .gitignore 패턴 문법 정리

• # — 주석. 해당 줄은 무시된다
• 폴더명/ — 끝에 슬래시를 붙이면 디렉터리 전체를 제외
• *.확장자 — 해당 확장자를 가진 모든 파일 제외
• !파일명 — 앞서 제외한 패턴에서 해당 파일만 예외 처리
• **/패턴 — 하위 모든 경로에서 해당 패턴 제외

---

언어·환경별 필수 제외 항목

프로젝트 유형마다 반드시 제외해야 할 파일과 폴더가 다르다. 언어와 프레임워크에 따라 아래 항목을 참고해 .gitignore를 구성하면 된다.

🗂 환경별 주요 제외 항목

• Node.js / Next.js — node_modules/, .next/, dist/, .env, .env.local
• Python — __pycache__/, *.pyc, .venv/, venv/, .env
• Java / Spring — target/, *.class, *.jar, .gradle/, build/
• 공통 — .DS_Store(맥), Thumbs.db(윈도우), *.log, .idea/, .vscode/

💡 gitignore.io 활용법

gitignore.io 사이트에서 사용하는 언어, OS, 에디터를 입력하면 검증된 .gitignore 템플릿을 즉시 생성해준다. 직접 작성하는 것보다 빠르고 놓치는 항목이 없어서 첫 프로젝트 세팅에 특히 유용하다.

---

이미 추적 중인 파일 제외하는 방법

나중에 .gitignore에 추가했더라도 이미 한 번이라도 커밋된 파일은 Git이 계속 추적한다. .gitignore는 새로 추가되는 파일에만 적용되고 기존 추적 이력은 건드리지 않기 때문이다.

⚠️ 이미 올라간 파일 제거 방법
Git 추적에서만 제거하고 실제 파일은 로컬에 유지하려면 git rm --cached 명령을 써야 한다. 파일 자체를 삭제하지 않으면서 Git 인덱스에서만 제거하는 방식이다.

# 특정 파일을 추적에서만 제거 git rm --cached .env # 폴더 전체를 추적에서만 제거 git rm -r --cached node_modules/ # 이후 커밋으로 변경사항 반영 git add . git commit -m "remove tracked files from git"

이 과정을 거치고 나면 .gitignore에 등록된 파일이 이후 커밋에서 더 이상 나타나지 않는다. 단, 협업 중이라면 팀원들도 동일하게 처리해야 충돌이 생기지 않는다.

---

실전 팁과 자주 하는 실수

슬래시 위치에 따른 차이

폴더를 제외할 때 끝에 슬래시를 붙이는 게 중요하다. dist와 dist/는 동작이 다르다. 슬래시 없이 작성하면 같은 이름의 파일까지 제외할 수 있고, 의도치 않은 결과가 생긴다. 폴더를 제외할 때는 반드시 dist/처럼 슬래시를 붙이는 습관을 들인다.

🚫 자주 하는 실수 정리

• .gitignore 파일 자체를 .gitignore에 등록하는 실수 — 이 파일은 Git이 추적해야 한다
• 프로젝트 루트가 아닌 하위 폴더에 .gitignore를 만들어 전체 적용이 안 되는 경우
• .env는 등록했지만 .env.local, .env.production 변형은 빠뜨리는 경우
• 이미 커밋된 파일을 .gitignore만 추가하고 git rm --cached 없이 끝내는 경우

---

정리 및 결론

.gitignore 핵심 정리

• 프로젝트 루트에 .gitignore 생성, 민감 파일과 불필요한 폴더를 패턴으로 등록
• node_modules/, .env, *.log, .DS_Store는 거의 모든 프로젝트에서 제외 대상
• gitignore.io로 언어·환경별 검증된 템플릿을 바로 가져다 쓸 수 있다
• 이미 추적된 파일은 git rm --cached 후 커밋해야 제외가 적용된다
• 폴더 제외 시 슬래시(/) 필수, .env 변형 파일도 빠짐없이 등록한다

.gitignore 하나를 제대로 관리하는 것만으로 보안 사고 예방과 저장소 경량화를 동시에 잡을 수 있다. 프로젝트 시작과 동시에 .gitignore를 만드는 것을 체크리스트의 첫 번째 항목으로 고정해두면 나중에 번거로운 상황을 피할 수 있다.