git clean 안전 사용법: 미추적 파일 정리 전 -n 프리뷰로 삭제 사고 막기

git clean 안전 사용법: 미추적 파일 정리 전 -n 프리뷰로 삭제 사고 막기

git clean은 untracked 파일을 빠르게 정리해 작업 디렉터리를 깨끗하게 만든다. 삭제형 명령어라 미리보기 습관이 필수다. 초보~중급 개발자가 바로 적용할 수 있도록 명령어 흐름, 옵션 선택 기준, 복구 절차를 실무 중심으로 설명한다.

공식 Git 로고 (출처: git-scm.com)

git clean 기본 사용 패턴

git clean -nd
git clean -fd
git clean -fdX

자주 쓰는 옵션 3~6개

항목	의미	언제 쓰는지(실무 상황)
-n	삭제 예정 항목 미리보기	실제 삭제 전 영향 범위를 확인할 때
-f	강제 삭제 실행	정리 대상 검증 후 실제 삭제할 때
-d	미추적 디렉터리까지 삭제	빌드 산출 폴더를 함께 정리할 때
-x	ignore된 파일도 포함 삭제	완전 초기화 빌드가 필요할 때
-X	ignore된 파일만 삭제	캐시 정리만 수행할 때

실무 적용 순서

1) 실행 전 상태 확인

git status와 git log로 현재 위치를 확인한다. 특히 원격 공유 브랜치인지, 로컬 전용 브랜치인지 먼저 판단해야 안전하다.

2) 목적에 맞는 옵션 선택

동일 명령어라도 옵션에 따라 이력 보존, 충돌 위험, 협업 영향이 달라진다. 팀 정책과 배포 단계에 맞춰 옵션을 고른다.

3) 실행 후 검증

명령 실행 뒤에는 status, diff, 테스트를 통해 결과를 검증한다. 필요하면 즉시 복구 명령(reflog, revert, stash)을 연계한다.

문제 상황 1개

상황: clean 후 필요했던 로컬 샘플 파일이 삭제됐다.
원인: -n 확인 없이 -fdx를 바로 실행했다.
해결: 복구 가능한 백업/스토리지에서 파일을 복원하고 ignore 정책을 재검토한다.
예방 팁: clean은 항상 -n으로 시작하고 중요 로컬 파일은 별도 디렉터리에 분리한다.

참고/출처

공식 문서: git-clean manual
공식 문서: Pro Git - Stashing and Cleaning
신뢰 자료: Atlassian - git clean