Git 기록에서 특정 파일을 완벽히 삭제하는 방법: git filter-branch

 

Git/Github(깃허브)를 사용하다 보면 민감한 정보나 대용량 파일을 실수로 커밋하는 경우가 있습니다. 단순히 파일을 삭제하는 것만으로는 충분하지 않은데, 그 이유는 해당 파일의 기록이 여전히 Git 히스토리에 남아 있기 때문입니다. 이를 위해 이 글에서는 git filter-branch를 사용하여 특정 파일의 모든 커밋 기록을 Git 저장소에서 완전히 제거하는 방법을 단계별로 설명해보려고 합니다.

⚠️ 주의: git filter-branch는 강력한 도구로, Git 기록을 영구적으로 변경합니다. 작업 전에 반드시 저장소를 백업하고 신중하게 진행하세요.

---

목차

1. 왜 git filter-branch를 사용해야 할까?
2. git filter-branch 사용하기
3. 강제 푸시로 원격 저장소에 반영하기
4. 주의사항
5. 마무리

---

1. 왜 git filter-branch를 사용해야 할까?

git filter-branch는 Git 기록을 재작성하여 특정 파일이나 폴더를 완전히 제거하는 데 유용한 명령어입니다. 이 명령어를 사용하면 특정 파일과 관련된 모든 커밋을 수정하여 Git 기록에서 파일을 완전히 삭제할 수 있습니다.

• 기록 수정: 파일을 추가하거나 삭제한 모든 커밋을 수정하여 파일이 포함되지 않게 합니다.
• 완전한 삭제: 원격 저장소에도 수정된 기록을 반영하여 GitHub나 다른 플랫폼에서도 파일을 다시 확인할 수 없게 만듭니다.

🔍 참고: git filter-branch는 복잡하고 시간이 많이 소요될 수 있으며, 최신 프로젝트에서는 git filter-repo나 BFG Repo-Cleaner 같은 도구가 더 빠르고 효율적일 수 있습니다.

---

2. git filter-branch 사용하기

특정 파일을 Git 기록에서 완전히 제거하기 위해 git filter-branch 명령어를 사용합니다. 아래는 test.py 파일을 모든 브랜치에서 제거하는 예제입니다.

특정 파일 기록 삭제 명령어

git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch test.py' --prune-empty --tag-name-filter cat -- --all

• --force: 기존의 필터링된 브랜치를 덮어씁니다.
• --index-filter 'git rm --cached --ignore-unmatch test.py': 인덱스에서 파일을 삭제하고, 파일이 없을 경우에도 무시합니다.
• --prune-empty: 파일 삭제 후 발생하는 빈 커밋을 자동으로 제거합니다.
• --tag-name-filter cat: 태그를 수정하지 않습니다.
• -- --all: 이 작업이 모든 브랜치에 적용되도록 합니다.

캐시된 파일도 함께 제거

필요 시 Git에서 캐시된 파일도 삭제합니다.

git rm --cached test.py

---

3. 강제 푸시로 원격 저장소에 반영하기

로컬에서 기록이 수정된 후, 원격 저장소에도 수정된 기록을 반영해야 합니다. 이를 위해 강제 푸시를 사용합니다.

git push --force --all

• --force: 원격 저장소의 기존 기록을 덮어씁니다.
• --all: 모든 브랜치에서 수정된 Git 기록을 원격 저장소에 강제로 푸시합니다.

⚠️ 주의: 강제 푸시는 원격 저장소의 기록을 변경하므로, 협업 중인 다른 사용자에게 영향을 줄 수 있습니다. 반드시 협업자들과 사전에 상의하세요.

---

4. 주의사항

혹시 모를 사항을 대비하는 작업입니다. (선택사항)

• 백업: Git 기록을 수정하는 작업은 되돌리기 어렵기 때문에 작업 전에 저장소를 백업하는 것이 중요합니다.
• git clone --mirror https://your-repo-url.git
• 협업자 주의: 이 작업은 Git 기록을 수정하기 때문에, 협업자들은 로컬 저장소를 다시 동기화해야 합니다. 작업 후 협업자들에게 알려주세요.
• git fetch --all git reset --hard origin/main
• 브라우저 캐시 확인: GitHub에서 파일이 여전히 보일 경우, 브라우저 캐시 문제일 수 있습니다. 브라우저 캐시를 지우거나 시크릿 모드에서 확인해 보세요.

---

5. 마무리

이렇게 git filter-branch 명령어를 살펴보았습니다. git filter-branch는 Git 기록에서 파일을 완전히 제거하는 데 유용하게 사용할 수 있지만, 아주 위험한 도구이기 때문에 혹시 모를 불상사를 막기 위해 작업 전에 반드시 백업을 하는게 좋습니다.

 

git filter-repo나 BFG Repo-Cleaner 같은 선택지도 있습니다. 다만 제가 사용했을 때 기록의 완전한 삭제가 안 이루어져 git filter-branch로 글을 작성하게 되었습니다. 감사합니다!