GitHub에 올리면 안 되는 파일, “.gitignore” 하나로 막을 수 있습니다

들어가며

Git을 사용해서 프로젝트를 관리하다 보면 어느 순간 이런 상황을 만나게 됩니다.

git add .

그리고 커밋하려고 확인했는데 생각보다 엄청나게 많은 파일이 잡힙니다.

빌드하면서 생성된 파일부터 IDE 설정 파일, 로그 파일, 운영체제가 자동으로 만든 파일까지 전부 Git에 올라가려고 합니다.

처음에는 그냥 같이 올려도 되는 것처럼 보이지만 프로젝트가 커질수록 상당히 귀찮아집니다.

특히 .env 같은 환경설정 파일이나 개인 PC에서만 사용하는 설정 파일이 실수로 GitHub에 올라가는 경우는 더 조심해야 합니다.

이럴 때 사용하는 것이 바로 **.gitignore**입니다.

.gitignore란?

.gitignore는 말 그대로 Git이 특정 파일이나 폴더를 추적하지 않도록 설정하는 파일입니다.

파일 이름은 정확하게 .gitignore입니다.

보통 프로젝트의 최상위 디렉터리에 만들어 놓습니다.

예를 들어 Java 프로젝트라면 다음과 같은 구조가 될 수 있습니다.

my-project/
├── .git/
├── .gitignore
├── src/
├── build/
├── README.md
└── pom.xml

여기서 .gitignore에 특정 파일이나 디렉터리를 등록하면 Git이 해당 파일을 기본적으로 추적 대상에서 제외합니다.

왜 .gitignore가 필요한가?

개발하면서 생성되는 모든 파일이 Git에 필요한 것은 아닙니다.

예를 들어 Java 프로젝트를 개발하다 보면 컴파일 과정에서 target이나 build 같은 디렉터리가 만들어질 수 있습니다.

Node.js 프로젝트라면 node_modules가 대표적입니다.

IDE를 사용한다면 IntelliJ IDEA나 VS Code 등의 개인 설정 파일이 생성될 수도 있습니다.

이런 파일들은 프로젝트 소스 자체가 아니라 개발 환경에서 자동으로 생성되거나 개인적으로 사용하는 파일인 경우가 많습니다.

그래서 Git 저장소에는 필요한 소스 코드와 설정만 관리하고, 불필요한 파일은 .gitignore로 제외하는 것이 일반적입니다.

가장 기본적인 .gitignore 작성 방법

예를 들어 다음과 같이 작성할 수 있습니다.

# 로그 파일
*.log

# 환경설정
.env

# 빌드 결과
build/
target/

# IDE
.idea/
.vscode/

# 운영체제
.DS_Store
Thumbs.db

주석은 #으로 작성합니다.

*.log처럼 작성하면 확장자가 .log인 파일을 제외할 수 있습니다.

build/처럼 디렉터리 이름 뒤에 /를 붙이면 해당 디렉터리를 대상으로 지정할 수 있습니다.

node_modules는 왜 제외할까?

Node.js 프로젝트를 사용한다면 .gitignore에서 자주 볼 수 있는 것이 바로 node_modules입니다.

node_modules/

npm install을 실행하면 package.json에 정의된 패키지들이 node_modules에 설치됩니다.

그런데 이 디렉터리는 파일 개수가 상당히 많아질 수 있습니다.

따라서 일반적으로 node_modules 자체를 Git에 올리지 않고 package.json과 package-lock.json 등을 관리합니다.

다른 개발자가 프로젝트를 내려받은 후 npm install을 실행하면 필요한 패키지를 다시 설치할 수 있기 때문입니다.

Java 프로젝트에서는 어떻게 사용할까?

Spring Boot나 일반적인 Java 프로젝트에서는 빌드 결과물을 제외하는 경우가 많습니다.

Maven이라면 보통 다음과 같이 작성합니다.

target/

Gradle을 사용한다면 다음과 같이 작성할 수 있습니다.

.gradle/
build/

IntelliJ IDEA를 사용한다면 개인 IDE 설정 파일을 제외하기 위해 다음과 같은 항목도 자주 사용합니다.

.idea/
*.iml

프로젝트 환경에 따라 필요한 항목만 추가하면 됩니다.

.env 파일은 특히 주의해야 한다

개인적으로 .gitignore에서 가장 중요하게 생각하는 부분 중 하나가 .env입니다.

개발하다 보면 데이터베이스 비밀번호나 API Key, 각종 환경설정 값을 .env 파일에 넣는 경우가 있습니다.

예를 들어 다음과 같은 형태입니다.

DB_USERNAME=myuser
DB_PASSWORD=mypassword
API_KEY=xxxxxxxx

이런 파일을 실수로 GitHub에 올리면 상당히 곤란한 상황이 발생할 수 있습니다.

그래서 다음처럼 등록하는 경우가 많습니다.

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

다만 중요한 점이 하나 있습니다.

.gitignore에 추가했다고 해서 이미 Git이 추적하고 있는 파일까지 자동으로 삭제되는 것은 아닙니다.

이 부분을 처음 접하면 상당히 많이 헷갈립니다.

.gitignore에 추가했는데 파일이 계속 보인다면?

예를 들어 이미 다음과 같이 파일을 Git에 추가했다고 생각해보겠습니다.

git add .env
git commit -m "add env"

그 후 .gitignore에 다음을 추가합니다.

.env

그런데도 Git에서 .env가 계속 추적되는 것처럼 보일 수 있습니다.

이유는 간단합니다.

.gitignore는 기본적으로 아직 추적하지 않는 파일을 무시하기 위한 규칙이기 때문입니다.

이미 Git이 관리하고 있는 파일은 별도로 추적을 해제해야 합니다.

예를 들어 다음과 같이 할 수 있습니다.

git rm --cached .env

그리고 커밋합니다.

git add .gitignore
git commit -m "update gitignore"

이렇게 하면 로컬에 있는 .env 파일은 그대로 두면서 Git의 추적 대상에서는 제외할 수 있습니다.

gitignore.io 같은 도구를 활용해도 좋다

프로젝트를 새로 만들 때마다 .gitignore를 처음부터 작성하는 것이 번거롭다면 개발 환경에 맞는 .gitignore 템플릿을 활용하는 것도 좋은 방법입니다.

예를 들어 Java, Spring, Node.js, Python, IntelliJ IDEA 등 프로젝트에 사용하는 기술을 기준으로 필요한 항목을 구성할 수 있습니다.

다만 자동으로 만들어진 .gitignore를 그대로 사용하기보다는 현재 프로젝트에서 실제로 필요한 항목인지 한 번 확인하는 습관을 추천합니다.

.gitignore에서 자주 사용하는 패턴

몇 가지 패턴만 알아도 대부분의 상황에서 활용할 수 있습니다.

*.log

모든 .log 파일을 무시합니다.

temp/

temp 디렉터리를 무시합니다.

.env

특정 파일을 무시합니다.

*.class

Java 컴파일 결과인 .class 파일을 무시할 수 있습니다.

!important.log

앞에서 무시한 규칙 중 특정 파일을 다시 포함시키는 예외 규칙도 사용할 수 있습니다.

.gitignore는 프로젝트 시작할 때 만드는 것이 가장 편하다

개발을 어느 정도 진행한 뒤 .gitignore를 추가하는 것보다 Git 저장소를 처음 만들 때부터 .gitignore를 구성하는 것이 가장 편합니다.

특히 node_modules, 빌드 결과물, IDE 설정 파일, 로그 파일처럼 처음부터 Git에 올릴 필요가 없는 파일은 프로젝트 생성 직후 정리해두는 것이 좋습니다.

개인적으로는 새로운 프로젝트를 시작하면 소스 코드를 작성하기 전에 .gitignore부터 한 번 확인하는 편이 편합니다.

나중에 git status를 실행했을 때 수백 개의 불필요한 파일이 등장하는 상황을 피할 수 있기 때문입니다.

마무리

.gitignore는 복잡한 기능처럼 보이지만 기본 개념은 아주 단순합니다.

Git으로 관리할 필요가 없는 파일을 미리 지정해 놓는 파일이라고 생각하면 됩니다.

특히 개발 프로젝트에서는 빌드 결과물, 로그, IDE 설정, 운영체제 생성 파일, node_modules, 환경변수 파일 등을 제외하는 경우가 많습니다.

그리고 가장 중요한 부분은 이것입니다.

.gitignore에 파일을 추가했다고 해서 이미 Git이 추적 중인 파일까지 자동으로 사라지는 것은 아닙니다.

이미 추적되고 있는 파일이라면 git rm --cached 등을 이용해 Git의 추적을 별도로 해제해야 합니다.

Git을 처음 사용할 때는 git add .만 알고 무작정 커밋하기 쉽습니다.

하지만 프로젝트를 실제로 운영하다 보면 .gitignore가 단순한 설정 파일이 아니라 Git 저장소를 깔끔하게 유지하고 불필요한 파일이나 민감한 설정이 올라가는 실수를 줄여주는 기본 장치라는 것을 알게 됩니다.

그래서 새로운 프로젝트를 시작한다면 git init과 함께 .gitignore도 한 번 확인하는 습관을 들여두는 것을 추천합니다.