.gitignore 사용법과 이미 올라간 파일 제외하는 법

.gitignore 사용법, 왜 필요한가

.gitignore는 Git이 추적하지 말아야 할 파일을 적어두는 목록 파일입니다. node_modules, 빌드 결과물, .env 같은 비밀 파일을 올리지 않게 해줍니다. 그런데 입문자가 가장 많이 막히는 지점은 이미 한 번 add/commit된 파일은 .gitignore에 적어도 계속 추적된다는 점입니다. 이 글에서 .gitignore 사용법과 이미 올라간 파일을 제외하는 법을 함께 정리합니다.

1단계: .gitignore 파일 만들기

프로젝트 최상위(저장소 루트)에 .gitignore라는 이름으로 파일을 만듭니다.

# 의존성 폴더
node_modules/

# 환경 변수 (비밀)
.env
.env.local

# 빌드 결과물
dist/
build/

# 로그와 OS 파일
*.log
.DS_Store

2단계: .gitignore 패턴 작성법

#으로 시작하는 줄은 주석, !는 "무시 규칙에서 제외(다시 포함)"를 뜻합니다.

3단계: 이미 올라간 파일을 추적에서 제외하기 (핵심)

.gitignore에 적었는데도 계속 변경이 잡힌다면, 그 파일이 이미 Git에 추적되고 있기 때문입니다. 추적만 끊고 파일은 디스크에 남기려면 --cached를 씁니다.

# 파일 하나를 추적에서 제외 (파일은 남음)
git rm --cached .env

# 폴더를 추적에서 제외 (파일은 남음)
git rm -r --cached node_modules/

# 변경 사항을 커밋
git commit -m "Stop tracking ignored files"

주의: --cached를 빼고 git rm만 쓰면 디스크의 실제 파일까지 삭제됩니다. 추적만 끊을 때는 반드시 --cached를 붙이세요.

.gitignore 전체를 다시 적용하고 싶을 때

여러 파일이 이미 추적 중이라 한꺼번에 .gitignore를 적용하려면 캐시를 비우고 다시 추가합니다.

git rm -r --cached .
git add .
git commit -m "Apply .gitignore"

이 방법은 디스크 파일은 그대로 두고, .gitignore에 해당하는 것만 추적에서 빠지게 합니다.

주의점: 비밀 파일은 이미 노출됐을 수 있다

.env처럼 비밀번호가 든 파일을 이미 push했다면, git rm --cached로 빼도 과거 커밋 히스토리에는 그대로 남습니다. 진짜 비밀이라면 다음을 하세요.

• 노출된 비밀번호·토큰·키를 즉시 폐기하고 새로 발급
• 히스토리에서 완전히 지우려면 git filter-repo 같은 도구 사용(공유 저장소면 협업자와 조율 필요)

특정 파일이 무시되는지 확인하기

# 이 파일이 어떤 규칙으로 무시되는지 점검
git check-ignore -v config.json

주의점 정리

• .gitignore는 "앞으로 add될 파일"에만 적용됩니다
• 이미 추적 중인 파일은 git rm --cached로 추적을 끊어야 합니다
• 비밀 파일은 처음부터 커밋하지 않는 것이 최선입니다

자주 묻는 질문

Q1. .gitignore에 추가했는데도 파일이 계속 변경 목록에 떠요.

그 파일이 이미 Git에 추적되고 있기 때문입니다. git rm --cached 파일명으로 추적을 끊은 뒤 커밋하면 이후로는 무시됩니다. 디스크의 실제 파일은 --cached 덕분에 그대로 남습니다.

Q2. git rm --cached를 하면 내 파일이 삭제되나요?

아닙니다. --cached는 Git의 추적에서만 제거하고 디스크 파일은 보존합니다. 다만 협업자가 그 변경을 pull하면 그들 쪽에서는 파일이 사라질 수 있으니, 공유 파일이라면 팀과 상의 후 진행하세요.

Q3. node_modules처럼 큰 폴더는 어떻게 한 번에 제외하나요?

.gitignore에 node_modules/를 추가하고, 이미 올라갔다면 git rm -r --cached node_modules/ 후 커밋하면 됩니다. 처음 프로젝트를 만들 때부터 .gitignore를 먼저 작성해 두면 이런 정리 작업 자체가 필요 없습니다.