[Git] .gitignore 완벽 가이드

목차 (OPEN)

• .gitignore란
• Git에서 .gitignore의 역할
• .gitignore 파일 생성하기
• 터미널에서 직접 생성하는 방법
• IntelliJ IDEA에서 직접 생성하는 방법
• 자동 생성 사이트를 이용하는 방법 (gitignore.io)
• .gitignore 문법 이해하기
• 주석
• 특정 파일 / 디렉토리 무시하기
• 패턴 매칭
• .gitignore 적용 방법
• 이미 커밋된 파일에 .gitignore 적용하기
• 글로벌 .gitignore 설정하기
• .gitignore 관련 문제 해결 방법
• .gitignore 파일이 동작하지 않을 때
• 결론

 

 

 

.gitignore란

.gitignore는 Git에서 특정 파일이나 디렉토리를 버전관리에서 제외하기 위해 사용하는 설정 파일이다.

이 파일은 프로젝트 루트 디렉토리에 위치하며, 무시하자 하는 파일이나 폴더의 경로나 패턴을 정의할 수 있다.

 

Git에서 .gitignore의 역할

Git은 기본적으로 프로젝트의 모든 파일을 추적하려고 한다.

하지만 추적이 불필요하거나 원하지 않는 파일까지 포함되면 아래와 같은 문제가 발생할 수 있다.

• 불필요한 파일 추적 ⚠️
  빌드 결과물 (*.class, *.jar)이나 캐시 파일 (*.log, .DS_Store) 등은 버전 관리에서 제외하는 것이 좋다.
  (필요 시 재생성 가능하고, 레포지토리 크기를 불필요하게 증가시키며, 협업 시 충돌을 유발할 수 있기 때문)
• 민감 정보 유출 🔐
  API 키, 데이터베이스 비밀번호 등이 포함된 설정 파일 (.env, application.properties)이 잘못 추적되면 보안 문제가 발생할 수 있다.
• 협업 시 혼란 🤯
  IDE 관련 파일 (.idea/, *.iml)이나 OS에서 생성하는 메타 데이터 (thumbs.db, .DS_Store)는 협업 중 불필요한 커밋 충돌을 유발할 수 있다.

👉 .gitignore는 이러한 문제를 방지하기 위해, 특정 파일과 디렉토리를 Git이 추적하지 않도록 설정하는 역할을 하는 것이다.

 

 

 

 

.gitignore 파일 생성하기

터미널에서 직접 생성하는 방법

터미널에서 다음 명령어를 입력해서 생성하면 된다.

touch .gitignore

 

생성된 .gitignore 파일은 루트 디렉토리에 위치하게 된다.

 

IntelliJ IDEA에서 직접 생성하는 방법

파일 > 새로 만들기 > 파일을 클릭한 뒤, 파일 이름을 .gitignore로 입력하면 된다.

 

만약 Intellij IDEA가 Git과 연동된 프로젝트라면, 자동으로 .gitignore 파일을 감지해준다.

 

자동 생성 사이트를 이용하는 방법 (gitignore.io)

gitignore.io는 프로젝트에 필요한 .gitignore 파일을 자동으로 생성해 주는 무료 웹 서비스이다.

 

http://gitignore.io

gitignore.io

 

위의 사이트로 이동해서 사용 중인 기술 스택을 입력한 후, 생성 버튼을 클릭하면 .gitignore 파일 내용이 생성된다.

 

 

 

 

 

.gitignore 문법 이해하기

주석

#로 시작하는 줄은 주석으로 간주되어 .gitignore 파일에 설명을 추가할 때 유용하다.

# 빌드 결과물 무시
*.class

 

특정 파일 / 디렉토리 무시하기

특정 파일 이름을 작성하면 해당 파일이 Git에서 무시된다.

# log 파일 무시
debug.log

# 특정 설정 파일 무시
application.properties

 

디렉토리 이름 뒤에 / 를 붙이면 해당 디렉토리와 내부 모든 파일이 무시된다.

# 빌드 디렉토리 무시
build/

# IntelliJ 설정 디렉토리 무시
.idea/

 

디렉토리 경로를 포함하여 특정 디렉토리의 파일을 무시할 수 있다.

# src/main/log 디렉토리의 모든 파일 무시
src/main/log/

 

패턴 매칭

와일드카드 (*)는 모든 문자와 일치한다.

# 모든 .log 파일 무시
*.log

# 모든 tmp 파일 무시
*.tmp

 

** 는 중첩된 디렉토리를 포함하여 모든 경로에서 일치한다.

# 어떤 위치에 있어도 tmp 디렉토리 무시
**/tmp/

 

! 를 사용하면 무시 규칙에서 특정 파일이나 디렉토리를 제외할 수 있다.

# 모든 log 파일 무시
*.log

# exception.log는 무시하지 않음
!exception.log

 

/ 는 파일 또는 디렉토리의 경로를 지정할 때 사용한다.

# 프로젝트 루트에 있는 node_modules 디렉토리만 무시
/node_modules/

# src/ 디렉토리 아래의 모든 파일 무시
src/

 

 

 

 

.gitignore 적용 방법

이미 커밋된 파일에 .gitignore 적용하기

.gitignore는 Git이 아직 추적하지 않은 파일에만 적용된다.

따라서 이미 Git에 커밋된 파일은 .gitignore에 추가해도 자동으로 무시되지 않는다.

 

이럴 땐 아래와 같은 방법으로 해결할 수 있다.

 

1️⃣ .gitignore 파일에 추가할 내용을 작성한다.

# 예시
build/
*.log

 

2️⃣ Git 캐시에서 파일을 제거한다.

git rm -r --cached <파일명 또는 디렉토리>

# 예시로 build/ 디렉토리를 무시하려면
git rm -r --cached build/

 

3️⃣ 변경사항을 커밋한다.

git add .
git commit -m "Apply .gitignore to existing files"

 

글로벌 .gitignore 설정하기

글로벌 .gitignore는 특정 프로젝트가 아니라 모든 Git 프로젝트에 대해 적용되는 것이다.

OS 별 캐시 파일, 개발 환경 관련 파일 등 프로젝트와 무관한 파일을 무시하고자 할 때 주로 사용한다.

 

이는 아래의 방법으로 설정할 수 있다.

 

1️⃣ 글로벌 .gitignore 파일 생성

# 홈 디렉토리에 .gitignore_global 파일 생성
touch ~/.gitignore_global

 

2️⃣ 글로벌 .gitignore 설정

# Git 설정에 .gitignore_global 파일 추가
git config --global core.excludesfile ~/.gitignore_global

 

3️⃣ 글로벌 .gitignore에 내용 추가

# macOS
.DS_Store
._*

# Windows
Thumbs.db
Desktop.ini

# IDE
.idea/
*.iml

 

4️⃣ 설정 확인

# 글로벌 .gitignore 설정이 적용되었는지 확인
git config --global core.excludesfile

 

 

 

 

.gitignore 관련 문제 해결 방법

.gitignore 파일이 동작하지 않을 때

.gitignore 파일이 동작하지 않을 때는 아래와 같은 방법으로 해결할 수 있다.

 

1️⃣ 이미 추적 중인 파일인지 확인한다.

.gitignore는 Git이 추적하지 않는 파일에만 적용된다.

따라서 이미 Git에서 추적 중인 파일은 .gitignore에 추가해도 무시되지 않는다.

"이미 커밋된 파일에 .gitignore 적용하기"를 참고하면 된다.

 

2️⃣  .gitignore 파일의 경로를 확인한다.

.gitignore 파일은 프로젝트의 루트 디렉토리에 있어야 한다.

무시하려는 파일이 다른 하위 디렉토리에 있다면, 정확한 경로를 지정했는지 확인해야 한다.

# 루트 디렉토리에 있는 logs 폴더 무시
logs/

# src 디렉토리 안의 logs 폴더 무시
src/logs/

 

3️⃣  패턴 문법을 확인한다.

위의 두 절차를 진행했음에도 문제가 해결되지 않았다면, .gitignore의 패턴 문법이 올바른지 다시 한 번 확인해봐야 한다.

예를 들어 *.log는 모든 .log 파일을 무시하지만, *.log/ 처럼 잘못된 문법은 작동하지 않는다.

자주 발생하는 실수로는 무시할 디렉토리 뒤에 / 를 빠뜨리는 것이 있으므로 꼼꼼히 확인해봐야 한다.

(이래서 그냥 gitignore.io를 사용하는게 편합니다 ..)

 

4️⃣  Git 캐시를 갱신한다.

.gitignore를 수정한 후에 캐시가 갱신되지 않았다면, .gitignore 규칙이 적용되지 않을 수 있으므로 캐시를 갱신해준다.

git rm -r --cached .
git add .
git commit -m "Refresh .gitignore rules"

 

 

 

 

결론

.gitignore는 단순한 설정 파일이지만, 잘 활용하면 프로젝트의 관리 효율성이 크게 향상된다.
항상 필요한 파일만 깔끔하게 추적하도록 설정하고, 민감 정보 유출이나 협업 중 충돌을 사전에 방지하면 좋을 것 같다.