Git clean 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Git clean 사용법

git clean은 Git이 추적하지 않는 파일과 디렉터리를 작업 트리에서 제거할 때 쓰는 명령이다. 2026년 6월 18일 기준 Git 공식 문서는 이 명령이 기본적으로 untracked 파일만 지우고, -x나 -X 옵션에 따라 ignored 파일 처리 범위가 달라진다고 설명한다.

실무에서 핵심은 세 가지다. 실제 삭제 전에는 -n으로 범위를 먼저 확인할 것, 디렉터리까지 지우려면 -d가 필요하다는 점, 그리고 ignored 파일까지 지우는 -x와 ignored 파일만 지우는 -X를 혼동하지 않는 것이다. 이 글은 Git 공식 문서를 기준으로 git clean을 언제 어떻게 써야 하는지 정리한다.

Git clean은 무엇을 지울까?

Git 공식 문서의 설명에 따르면 git clean은 현재 디렉터리부터 시작해 버전 관리 대상이 아닌 파일을 재귀적으로 정리한다. 다만 기본 동작은 보수적이어서, 아무 옵션 없이 실행하면 untracked 디렉터리까지 깊게 들어가 지우지 않는다.

즉 생성 산출물, 임시 로그, 실험용 파일처럼 아직 Git에 추가하지 않은 파일을 정리할 때 적합하다. 반대로 이미 추적 중인 파일 변경분을 되돌리는 명령은 아니므로, tracked 파일 복원은 git restore나 git reset 계열로 구분해야 한다.

왜 -f 없이 바로 지워지지 않을까?

Git 공식 문서는 clean.requireForce가 기본적으로 true라서, -f 없이 파일이나 디렉터리를 삭제하지 않는다고 설명한다. 이는 실수로 로컬 파일을 잃는 상황을 막기 위한 안전장치다.

또한 문서상 중첩된 Git 저장소처럼 별도 .git 디렉터리를 가진 untracked 디렉터리는 더 보수적으로 다뤄진다. 이런 디렉터리를 지우려면 두 번째 -f가 필요할 수 있으므로, 외부 저장소를 임시로 복사해 둔 작업 디렉터리에서는 특히 주의해야 한다.

가장 먼저 써야 하는 명령은 무엇일까?

상황	권장 명령	이유
무엇이 지워질지 먼저 보고 싶다	git clean -n	삭제 없이 대상만 출력한다.
untracked 파일만 실제로 지우고 싶다	git clean -f	기본 안전장치를 해제하고 파일만 삭제한다.
untracked 디렉터리까지 함께 지우고 싶다	git clean -fd	디렉터리 재귀 삭제를 명시한다.
빌드 산출물 등 ignored 파일까지 모두 지우고 싶다	git clean -fdx	ignore 규칙을 무시하고 untracked 전체를 정리한다.
ignored 파일만 지우고 수동 파일은 남기고 싶다	git clean -fdX	Git이 무시하는 파일만 대상으로 삼는다.

대부분의 사고는 -n을 건너뛰고 바로 삭제했을 때 발생한다. 문서 기준으로 --dry-run은 실제 삭제를 하지 않으므로, CI 실패 재현이나 깨끗한 빌드 테스트 전에도 먼저 범위를 확인하는 습관이 안전하다.

-x와 -X는 어떻게 나눠야 할까?

-x는 표준 ignore 규칙을 사용하지 않고, 명령행의 -e 예외 패턴만 유지한 채 untracked 파일을 정리한다. Git 공식 문서는 이 옵션이 build product를 모두 지워 깨끗한 작업 디렉터리를 만들 때 유용하다고 설명한다.

반면 -X는 ignored 파일만 제거한다. 따라서 .env.local처럼 ignore되지 않은 개인 메모 파일을 남기고, dist/나 __pycache__/처럼 ignore된 산출물만 정리하려면 -X가 더 보수적인 선택이다.

 

 

-e 예외 패턴은 언제 쓸까?

Git 공식 문서는 -e <pattern>이 표준 ignore 규칙에 추가되는 exclude 패턴이라고 설명한다. 이 옵션을 쓰면 대량 정리 중에도 특정 파일이나 디렉터리를 남겨 둘 수 있다.

예를 들어 git clean -fdx -e .env.local처럼 실행하면 ignored 파일을 폭넓게 지우면서도 로컬 환경 파일은 보존하는 식의 운영이 가능하다. 빌드 캐시를 지우되 로컬 비밀값 파일은 남겨야 하는 저장소에서 유용하다.

interactive 모드는 언제 더 안전할까?

git clean -i는 삭제 대상을 보여 준 뒤 interactive loop로 들어간다. Git 공식 문서는 이 모드에서는 clean.requireForce를 무시하지만, 대신 사용자가 직접 선택하거나 패턴으로 걸러낼 수 있어 자체적인 안전장치가 된다고 설명한다.

한 번에 여러 파일을 정리해야 하지만 경로가 애매할 때는 -i가 실수 확률을 줄인다. 특히 오래된 브랜치 작업 디렉터리에서 어떤 파일이 임시 산출물인지 확신이 없을 때 일괄 삭제보다 interactive 선택이 낫다.

ignored 파일 규칙과는 어떤 관계가 있을까?

Git 공식 문서의 gitignore 설명에 따르면 ignore 규칙은 .gitignore, $GIT_DIR/info/exclude, core.excludesFile 등 여러 소스에서 읽힌다. git clean 기본 동작은 이런 표준 ignore 규칙을 존중하므로, ignore된 파일은 기본적으로 남는다.

그래서 "왜 git clean -fd를 했는데 node_modules/는 안 지워지지?" 같은 상황이 생길 수 있다. 이 경우는 대부분 node_modules/가 ignore 대상이라서이고, 모두 지우고 싶다면 -x를 써야 한다.

실무 기본값은 무엇이 무난할까?

대부분의 저장소에서는 바로 삭제보다 git clean -nd로 확인하고, 문제가 없을 때 git clean -fd로 진행하는 2단계가 무난하다. 빌드 환경을 완전히 초기화해야 할 때만 -fdx를 쓰는 편이 안전하다.

-fdX는 ignore 규칙이 잘 정리된 저장소에서 특히 유용하다. 개발자가 수동으로 만든 비추적 파일은 남기고, Git이 이미 산출물로 분류한 파일만 비우기 때문에 삭제 범위를 상대적으로 예측하기 쉽다.

FAQ

Q. git clean은 tracked 파일 수정분도 같이 되돌리나?

아니다. Git 공식 문서 기준으로 git clean은 untracked 파일과 디렉터리 정리용이다. tracked 파일 복원은 별도 명령으로 처리해야 한다.

Q. git clean -fdx는 왜 위험하다고 하나?

ignore 규칙까지 무시하고 untracked 파일을 폭넓게 지우기 때문이다. 빌드 산출물 정리에는 유용하지만, 로컬에서만 쓰는 비추적 설정 파일도 함께 삭제될 수 있다.

Q. ignored 파일만 지우고 싶으면 무엇을 쓰면 될까?

이 경우는 git clean -fdX가 더 맞다. Git 공식 문서는 -X가 ignored 파일만 제거한다고 설명한다.

정리

git clean의 선택 기준은 단순하다. 먼저 -n으로 범위를 확인하고, 디렉터리 삭제가 필요하면 -d를 추가하며, ignore 규칙을 유지할지 여부에 따라 -x와 -X를 고르면 된다.

한 줄 기준으로 줄이면 이렇다. 일반 정리는 git clean -fd, 깨끗한 빌드 재현은 git clean -fdx, ignored 파일만 청소할 때는 git clean -fdX를 우선 검토하면 된다.

참고 자료

• Git Documentation: git-clean
• Git Documentation: gitignore