gitignore 작성법, 무조건 써야 하는 이유가 있습니다

 

프로젝트를 진행하면서 버전 관리 시스템을 사용할 때 가장 먼저 신경 써야 할 부분 중 하나는 바로 gitignore 설정입니다. 저 역시 개발 초기에 이 설정을 소홀히 했다가 불필요한 파일들이 원격 저장소에 그대로 올라가 곤란을 겪었던 적이 있습니다. 특히 API 키나 데이터베이스 비밀번호가 담긴 비밀파일이 실수로 커밋되거나, 실행 과정에서 끊임없이 생성되는 방대한 로그 파일들이 추적 대상에 포함되면 심각한 보안 사고와 저장소 용량 및 충돌 문제로 이어지게 됩니다.

"gitignore 이거 꼭 만들어야 하나?" ".env 파일 깃허브에 올라갔는데 어떡하지?" "log 파일 때문에 저장소가 너무 무거워졌어" "gitignore 썼는데 왜 계속 올라가지?"

따라서 저는 이번 글을 통해 이러한 비밀파일 유출과 로그 파일 누적 문제를 예방하기 위한 체계적인 파일 제외 관리의 범위를 다루어 보고자 합니다. 단순히 특정 확장자를 막는 수준을 넘어, 로컬 환경 설정 파일부터 런타임에 동적으로 쌓이는 각종 시스템 로그, 그리고 프로젝트 전반의 보안 자격 증명 파일에 이르기까지 어떤 대상을 어디까지 추적에서 배제해야 안전한 개발 환경을 유지할 수 있는지 그 구체적인 기준과 적용 범위를 차례대로 살펴보겠습니다.

목차

1. .gitignore가 뭐길래 무조건 알아야 하나
2. 이유 1. 보안 - 비밀 파일이 인터넷에 박제됩니다
3. 이유 2. 로그 파일 - 저장소가 쓰레기장이 됩니다
4. 만드는 법 - 파일 하나면 끝
5. 문법은 5가지만 알면 됩니다
6. 복붙해서 쓰는 기본 예시
7. 자동으로 만들어주는 사이트
8. 이미 커밋한 파일은 무시되지 않습니다
9. 커밋 전 습관 하나만 들이면 됩니다

1. .gitignore가 뭐길래 무조건 알아야 하나

.gitignore는 "이 파일들은 깃이 추적하지 마라"라고 적어두는 목록 파일입니다. 프로젝트 폴더 맨 위에 이 이름 그대로 만들어 두면, 깃이 커밋 대상을 고를 때 목록에 적힌 파일을 아예 없는 것처럼 취급합니다.

깃은 기본적으로 폴더 안의 모든 파일을 올릴 후보로 봅니다. 문제는 프로젝트 폴더에는 코드만 있는 게 아니라는 점이에요. 비밀번호가 든 설정 파일, 서버가 뱉어낸 로그, 빌드 결과물 같은 것들이 함께 삽니다.

이 중에서 특히 보안 파일과 로그 파일, 이 둘 때문에 .gitignore는 선택이 아니라 필수가 됩니다. 하나씩 볼게요.

2. 이유 1. 보안 - 비밀 파일이 인터넷에 박제됩니다

대부분의 프로젝트에는 데이터베이스 비밀번호, API 키(외부 서비스 인증용 열쇠) 같은 비밀 값을 모아둔 파일이 있습니다. 흔히 .env라는 이름을 씁니다.

이 파일이 커밋에 섞여 공개 저장소에 올라가면, 그 순간부터 전 세계 누구나 볼 수 있습니다. 실제로 공개 저장소에 올라온 API 키를 자동으로 긁어가는 봇들이 항상 돌고 있어서, 유출된 클라우드 키로 몇 시간 만에 요금 폭탄을 맞는 사고가 반복적으로 일어납니다.

더 무서운 건 깃의 특성입니다. 깃은 모든 기록을 남기는 도구라서, 나중에 파일을 지우고 다시 커밋해도 과거 커밋 기록에는 비밀 값이 그대로 남아 있습니다. 지웠다고 끝난 게 아니라는 뜻이에요.

📌 핵심 비밀 값이 한 번이라도 커밋되면 "삭제 커밋"으로는 기록에서 사라지지 않습니다. 애초에 올라가지 않게 막는 것, 그게 .gitignore의 역할입니다.

3. 이유 2. 로그 파일 - 저장소가 쓰레기장이 됩니다

로그 파일은 프로그램이 돌면서 자동으로 쌓이는 기록입니다. 개발 중에도 계속 생기고, 크기가 수백 MB까지 자라는 경우도 흔합니다.

이게 커밋에 섞이면 세 가지 문제가 생깁니다. 저장소가 무거워져 클론과 푸시가 느려지고, 커밋 내역이 로그 변경으로 도배돼 정작 코드 변경을 찾기 어려워지고, 로그 안에 섞인 접속 IP나 사용자 정보가 함께 노출될 수 있습니다.

같은 이유로 막아야 하는 것들이 더 있습니다. 패키지 폴더(Node.js의 node_modules처럼 명령 한 번이면 다시 받아지는 것), 빌드 결과물, 운영체제가 몰래 만드는 파일(macOS의 .DS_Store 등)이 대표적입니다. 전부 "내가 쓴 코드가 아닌 것"이라는 공통점이 있어요.

4. 만드는 법 - 파일 하나면 끝

만드는 방법은 정말 단순합니다. 프로젝트 최상위 폴더에 .gitignore라는 이름의 텍스트 파일을 만들면 끝입니다. 확장자 없이 점으로 시작하는 이름 그대로예요.

# 프로젝트 폴더에서
touch .gitignore

 

윈도우 탐색기에서는 점으로 시작하는 파일명을 거부할 때가 있는데, 그 경우 에디터(VS Code 등)에서 새 파일로 만들면 문제없이 생성됩니다.

이 파일 안에 무시할 파일 이름을 한 줄에 하나씩 적으면 됩니다. 시점은 빠를수록 좋습니다. 프로젝트를 시작하고 첫 커밋을 하기 전에 만드는 게 정석이에요.

5. 문법은 5가지만 알면 됩니다

.gitignore 문법은 공식 문서를 보면 규칙이 많지만, 실무에서 쓰는 건 사실상 다섯 가지입니다.

쓰는 법	의미	예시
파일명 그대로	그 이름의 파일 무시	.env
별표 *	패턴 일치 전부 무시	*.log
이름 뒤 /	폴더 통째로 무시	logs/
느낌표 !	무시 목록에서 예외	!.env.example
샵 #	주석 (설명 메모)	# 로그 파일

느낌표 예외가 유용한 상황을 하나만 짚으면, .env는 막되 값이 비어 있는 견본 파일 .env.example은 팀원 공유용으로 올리고 싶을 때입니다. 두 줄이면 해결됩니다.

반응형

6. 복붙해서 쓰는 기본 예시

어떤 프로젝트든 거의 그대로 쓸 수 있는 공통 뼈대입니다. 보안과 로그, 그리고 앞서 말한 단골 손님들을 전부 막는 구성이에요.

# 보안 - 비밀 값 파일
.env
.env.*
!.env.example
*.pem
*.key

# 로그 파일
*.log
logs/

# 패키지·빌드 결과물
node_modules/
dist/
build/

# 운영체제·에디터 파일
.DS_Store
Thumbs.db
.vscode/
.idea/

 

파이썬 프로젝트라면 여기에 __pycache__/, venv/ 정도를 더하고, 언어별 세부 항목은 다음 섹션의 도구로 채우면 됩니다.

참고로 .gitignore 파일 자체는 커밋해서 올리는 게 맞습니다. 팀원 모두가 같은 무시 규칙을 공유해야 하니까요.

7. 자동으로 만들어주는 사이트

언어·프레임워크·에디터별로 무시할 파일을 일일이 아는 건 무리입니다. 그래서 조합을 입력하면 .gitignore를 만들어주는 도구가 있습니다.

대표적인 것이 gitignore.io입니다(2026년 현재 toptal.com/developers/gitignore 주소로 운영). 검색창에 "Node", "Python", "macOS", "VisualStudioCode"처럼 자기 환경을 넣으면 합쳐진 결과를 바로 줍니다.

깃허브도 언어별 공식 .gitignore 템플릿 모음을 저장소로 관리하고 있어서, 깃허브에서 새 저장소를 만들 때 템플릿을 선택하면 자동으로 깔아줍니다. 어느 쪽이든 자동 생성 결과를 기본으로 깔고, 프로젝트 고유 항목(자체 로그 폴더 등)만 손으로 추가하는 방식이 편합니다.

8. 이미 커밋한 파일은 무시되지 않습니다

.gitignore를 쓰다 가장 많이 막히는 지점입니다. 규칙을 추가했는데도 파일이 계속 커밋 대상에 뜨는 경우인데, 이유는 하나입니다. .gitignore는 아직 추적을 시작하지 않은 파일에만 적용되기 때문입니다.

이미 한 번 커밋된 파일은 깃이 계속 추적합니다. 이때는 추적 목록에서 빼주는 명령이 필요합니다. 파일은 컴퓨터에 그대로 두고 깃 추적에서만 제거하는 방식이에요.

이미 커밋된 파일이 .gitignore에 넣어도 무시되지 않는 이유

프로젝트 초기 설정을 하다 보면 실수로 환경 변수 파일인 .env나 빌드 산출물을 먼저 커밋한 뒤, 뒤늦게 .gitignore에 추가하는 경우가 종종 있습니다. 저도 예전에 .gitignore에 분명히 파일명을 적었는데 계속 git status의 수정 목록에 올라와서 당황했던 경험이 있습니다.

원인은 Git의 추적(Track) 메커니즘에 있습니다. Git 공식 gitignore 문서에 명시된 것처럼, .gitignore의 목적은 아직 Git이 추적하지 않는 파일(Untracked files)이 실수로 추적 대상에 포함되는 것을 막는 것입니다. 즉, 이미 한 번이라도 git add와 커밋을 거쳐 인덱스(Staging Area)에 등록된 파일은 .gitignore 규칙의 영향을 받지 않고 계속 변경 사항이 추적됩니다.

제가 2026년 10월 20일(KST) 기준으로 로컬 테스트 저장소에서 직접 재현해 본 결과는 다음과 같습니다.

# 1. .env 파일을 먼저 생성하고 커밋한 상태
$ git add .env && git commit -m "chore: add env"

# 2. 뒤늦게 .gitignore의 첫 번째 줄에 .env 추가
$ echo ".env" > .gitignore

# 3. 무시 여부 확인 (추적 중이므로 아무 출력도 나오지 않음 - not ignored)
$ git check-ignore -v .env

이처럼 이미 버전 관리에 포함된 민감 정보 파일이 무시되지 않은 채 원격에 올라가면 보안 사고로 이어질 수 있습니다. 로컬 저장소와 원격 서비스의 구조적 차이가 궁금하신 분들은 제가 이전에 정리한 Git과 GitHub의 차이 및 호스팅 서비스 비교 글을 함께 참고해 보시기 바랍니다.

# 파일은 남기고 깃 추적에서만 제거
## 파일인 경우
git rm --cached .env
## 디렉토리 경우
git rm -r --cached logs/

# 이후 커밋하면 다음부터 무시됨
git commit -m "chore: 추적 제외 파일 정리"

 

git rm --cached 명령어로 안전하게 추적만 해제하기

이미 추적 중인 파일을 .gitignore 규칙에 적용하려면, 작업 디렉터리(내 컴퓨터의 실제 파일)에서는 파일을 그대로 유지하면서 Git의 인덱스(캐시)에서만 제거해 주어야 합니다. 이때 사용하는 핵심 옵션이 바로 git rm --cached입니다.

만약 --cached 옵션 없이 그냥 git rm .env를 실행하면 내 로컬 디스크에 있는 실제 .env 파일까지 삭제되므로 주의하셔야 합니다. 저는 실무에서 단일 파일이나 폴더의 추적을 끊을 때 아래 순서대로 진행합니다.

# 1. 로컬 파일은 남기고 Git 인덱스(추적 목록)에서만 .env 제거
$ git rm --cached .env
rm '.env'

# 2. 폴더 전체의 추적을 해제해야 할 때는 -r 옵션 추가
# $ git rm -r --cached dist/

# 3. 추적 해제 내역을 커밋하여 확정
$ git commit -m "chore: stop tracking .env file"

이렇게 인덱스에서 제거하고 커밋까지 마치고 나면, 비로소 .env는 Untracked 상태가 되는 동시에 .gitignore 규칙이 즉시 작동하여 git status 목록에서 깔끔하게 사라집니다. 추적 해제 이력을 남길 때 어떤 커밋 접두사를 써야 할지 고민되신다면 제가 작성해 둔 Git 커밋 메시지 작성 규칙 정리 포스팅을 확인해 보셔도 좋습니다.

단, 앞서 말했듯 과거 커밋 기록에는 파일이 여전히 남아 있습니다. 일반 파일이면 여기까지로 충분하지만, 비밀 값이 들어 있던 파일이라면 기록 제거와 별개로 해당 비밀번호·API 키를 반드시 새로 발급받아 교체해야 합니다. 기록을 지우는 것보다 키를 바꾸는 게 먼저입니다.

9. 커밋 전 습관 하나만 들이면 됩니다

마지막으로 사고를 막는 습관 하나. 커밋하기 전에 git status로 올라갈 파일 목록을 한 번 훑는 것입니다.

목록에 .env나 *.log 같은 게 보이면 그 자리에서 .gitignore에 추가하면 됩니다. 5초짜리 확인이 유출 사고와 저장소 청소 작업을 통째로 대체합니다.

습관이 안 들 것 같으면 git add . 대신 올릴 파일을 지정해서 add하는 방식도 좋습니다. 통째로 담는 습관이 사고의 절반쯤을 만듭니다.

git check-ignore -v로 무시 규칙 정상 적용 검증하기

.gitignore 패턴이 복잡해지거나 전역 설정이 섞여 있을 때는 내가 작성한 규칙이 실제로 잘 먹히고 있는지 눈으로 검증하는 습관이 중요합니다. 이때 제가 가장 자주 활용하는 명령어가 git check-ignore -v <파일경로>입니다. -v(--verbose) 옵션을 붙이면 어느 설정 파일의 몇 번째 줄 규칙 때문에 해당 파일이 무시되었는지 정확히 출력해 줍니다.

앞서 2026년 10월 20일(KST) 실측 환경에서 git rm --cached .env 및 커밋을 완료한 직후 다시 검증 명령어를 실행한 결과입니다.

# 추적 해제 커밋 후 다시 확인
$ git check-ignore -v .env
.gitignore:1:.env	.env

# 작업 트리 상태 확인 (.env가 수정되어도 더 이상 목록에 나타나지 않음)
$ git status -s

출력된 .gitignore:1:.env .env는 현재 저장소의 .gitignore 파일 1번째 줄에 적힌 .env 패턴에 의해 .env 파일이 정상적으로 무시(Ignored)되고 있음을 뜻합니다. 만약 앞서 살펴본 것처럼 파일이 여전히 Git에 의해 추적 중이라면 이 명령어를 실행해도 아무런 결과가 나오지 않으므로, 문제의 원인이 패턴 오타인지 캐시 미삭제인지 단번에 구분할 수 있습니다.

팀 단위나 사내 환경에서 이처럼 보안 파일을 철저히 분리하고 저장소를 운영하는 방식이 궁금하시다면 Git 저장소 호스팅 유형과 선택 기준 글도 함께 읽어보시기를 추천합니다.

자주 묻는 질문 (FAQ)

.env 파일을 이미 깃허브에 올렸는데 어떻게 하나요?

순서가 중요합니다. 첫째, 그 안에 있던 비밀번호와 API 키를 전부 새로 발급받아 교체하세요. 이게 가장 급합니다. 둘째, git rm --cached로 추적에서 제거하고 .gitignore에 추가하세요. 기록까지 완전히 지우려면 별도 도구가 필요하지만, 키를 이미 교체했다면 기록 제거는 부차적인 문제가 됩니다.

.gitignore 자체도 커밋해야 하나요?

네, 커밋하는 게 표준입니다. 무시 규칙은 팀 전체가 공유해야 의미가 있습니다. 반대로 나만의 개인 규칙(개인 메모 파일 등)은 저장소의 .gitignore 대신 전역 gitignore라는 개인 설정으로 빼는 방법이 있습니다.

규칙을 추가했는데 적용이 안 됩니다

십중팔구 이미 추적 중인 파일입니다. 8번 섹션의 git rm --cached를 먼저 실행하세요. 그래도 안 되면 파일명 오타, 경로 위치(하위 폴더 파일은 경로 포함 필요)를 확인해 보세요.

파일 하나가 사고 하나를 막습니다

정리하면 이렇습니다. 깃은 폴더 안 모든 파일을 올릴 후보로 보고, 그 안에는 반드시 올라가면 안 되는 보안 파일과 올라갈 필요 없는 로그 파일이 섞여 있습니다. 그래서 깃을 쓴다면 .gitignore는 무조건 함께 가야 합니다.

다행히 배울 건 많지 않습니다. 파일 하나 만들고, 문법 다섯 개 알고, 첫 커밋 전에 깔아두기. 여기에 커밋 전 status 확인 습관까지 더하면, 적어도 유출과 저장소 비대화 두 사고는 원천 차단됩니다.

📚 함께 보면 좋은 글

깃(Git)과 깃허브(GitHub) 차이, 깃 호스팅 4대장 정리 (feat. 죽다 살아난 CodeCommit)

깃허브 깃랩 차이, 무료로 주는 데엔 이유가 있습니다

깃 커밋 메시지 작성법, 실무에선 5개만 쓰는 이유가 있습니다

Git 브랜치 커밋 add 개념, 최대한 쉽게 폴더 파일 예시로 설명합니다

Git 역사, 리누스가 열흘 만에 만든 버전관리 도구