`clean` & `smudge` 필터

소개

Git은 버전 관리 시스템으로서 파일 내용을 저장소(repository)에 저장하기 전과 작업 디렉토리(working directory)로 가져올 때 내용을 변환할 수 있는 강력한 필터 메커니즘을 제공한다. 이 문서에서는 Git의 clean과 smudge 필터의 개념, 작동 방식, 그리고 실제 적용 사례에 대해 설명한다.

`clean`과 `smudge` 필터의 개념

Git 속성 필터는 두 가지 주요 방향으로 작동한다:

clean 필터: 작업 디렉토리에서 Git 저장소(스테이징 영역)로 파일이 이동할 때 적용된다. git add 명령을 실행하면 파일 내용이 clean 필터를 통과한 후 저장소에 저장된다.
smudge 필터: Git 저장소에서 작업 디렉토리로 파일이 이동할 때 적용된다. git checkout이나 git clone 명령으로 파일을 작업 디렉토리로 가져올 때 smudge 필터를 통과한다.

이 두 필터의 이름은 Git의 내부 설계 철학을 반영한다. “clean”은 파일을 저장소에 저장하기 위해 “깨끗하게” 만드는 과정을 의미하며, “smudge”는 저장소에서 꺼낸 파일을 작업 환경에 맞게 변환하여 일종의 “얼룩”을 추가하는 과정을 의미한다.

작동 방식

Git 필터의 작동 방식은 다음과 같다:

필터 설정: .gitattributes 파일에서 특정 파일 패턴에 필터를 적용하도록 지정한다.
```
*.md filter=my-filter
```

필터 명령 정의: Git 설정에서 clean과 smudge 필터 명령을 정의한다.

git config filter.my-filter.clean 'command-to-clean'
git config filter.my-filter.smudge 'command-to-smudge'

양방향 변환:
- 파일을 커밋할 때: 작업 디렉토리 → clean 필터 → 저장소
- 파일을 체크아웃할 때: 저장소 → smudge 필터 → 작업 디렉토리

실제 적용 사례: HTML 주석 필터링

Obsidian 같은 도구에서 HTML 주석으로 저장된 개인 데이터를 저장소에서 제외하는 예시를 살펴본다:

.gitattributes 파일 설정:

echo "*.md filter=html-comments" >> .gitattributes
# 위의 "html-comments"는 임의로 변경 가능한 필터 식별자 변수

필터 명령 정의:

# 앞서 정의한 필터 식별자를 대입
git config filter.html-comments.clean 'sed -e "/<!--/,/-->/d"'
git config filter.html-comments.smudge 'cat'

결과:
- 커밋 시: HTML 주석이 제거된 상태로 저장소에 저장된다.
- 체크아웃 시: 저장소의 파일이 변환 없이 작업 디렉토리로 가져온다.

`clean`과 `smudge` 필터 구현 시 고려사항

1. 필터의 완전성

Git 필터는 일반적으로 clean과 smudge 한 쌍으로 정의한다. smudge 필터가 필수적이지 않은 경우에도 cat 명령으로 명시적으로 설정하는 것이 좋은 관행이다. 이유는 다음과 같다:

명시적인 설정: 양방향 필터의 완전한 정의를 제공한다.
향후 확장성: 추후 smudge 필터를 수정하기 쉽다.
디버깅 용이성: 문제 발생 시 필터 설정을 확인하기 쉽다.

이런 접근법은 “방어적 프로그래밍(Defensive Programming)“의 한 형태로, 잠재적 문제를 예방하는 접근 방식이다.

2. 필터 적용 시 주의사항

개인 Git 설정: 필터 명령은 개인 Git 설정이므로 저장소를 새로 클론하면 다시 설정해야 한다.
기존 파일에 적용: 기존 파일에 필터를 적용하려면 git add --renormalize . 명령을 사용한다.
GitHub UI: GitHub 웹 인터페이스에서 파일을 편집할 경우 필터가 적용되지 않는다.

Git 속성 필터 vs Git 훅(Hook)

Git 속성 필터와 Git 훅은 모두 파일 내용을 변환할 수 있지만 다음과 같은 차이점이 있다:

특성	Git 속성 필터	Git 훅
작동 원리	파일이 저장소와 작업 디렉토리 사이 이동 시 변환	특정 Git 이벤트 발생 시 스크립트 실행
설정 방법	`.gitattributes` + `git config`	스크립트 + `git config core.hooksPath`
처리 시점	모든 Git 작업에서 일관되게 처리	특정 이벤트(예: 커밋 전)에만 처리
로직 복잡성	단순 패턴 매칭과 텍스트 변환에 제한	복잡한 조건부 로직과 처리 가능
양방향 변환	기본적으로 양방향(clean/smudge) 지원	기본적으로 단방향(추가 구현 필요)

결론

Git의 clean과 smudge 필터는 파일이 저장소와 작업 디렉토리 사이에서 이동할 때 내용을 자동으로 변환하는 강력한 메커니즘이다. 이를 통해 민감한 정보 제거, 파일 형식 변환, 개인 설정 필터링 등 다양한 작업을 자동화할 수 있다. 필터를 설정할 때는 양방향 모두 명시적으로 정의하고, 팀원 간 설정 공유를 위한 문서화와 안내가 중요하다.

이 필터 메커니즘을 적절히 활용하면 팀 협업과 개인화된 작업 환경 사이의 균형을 효과적으로 유지할 수 있다.

— 보충 —

`clean`과 `smudge` 필터의 관계와 설정의 필요성

clean과 smudge 필터는 Git에서 상호 보완적인 관계로 설계되었다. 두 필터가 가진 관계성과 양쪽 모두 설정해야 하는 이유는 다음과 같다:

상호 보완적 관계

clean과 smudge 필터는 Git의 데이터 흐름에서 서로 반대 방향으로 작용한다:

clean: 작업 디렉토리 → 저장소
smudge: 저장소 → 작업 디렉토리

이 두 과정은 데이터의 일관성을 유지하는 데 중요한 역할을 한다. 이상적으로는 “clean 후 smudge” 과정을 거친 파일이 원본과 동일하게 유지되어야 한다(필터의 목적이 특별히 다른 경우 제외).

`smudge` 필터를 반드시 설정해야 하는 이유

일부 시나리오에서는 clean 필터만 필요하고 smudge는 아무 작업을 하지 않아도 될 수 있다. 예를 들어, HTML 주석을 제거하는 경우가 그렇다. 그러나 smudge 필터를 cat과 같은 명령으로 명시적으로 설정하는 것이 여러 이유로 권장된다:

명시적 설정의 완전성: Git 필터 시스템에서 clean만 설정하고 smudge를 설정하지 않으면 예상치 못한 동작이 발생할 수 있다. 명시적으로 cat을 사용하여 “아무 변환도 하지 않음”을 지정하는 것이 안전하다.
Git의 내부 일관성: Git은 필터를 쌍으로 처리하도록 설계되었다. 일부만 설정하면 Git의 내부 로직과 충돌할 가능성이 있다.
미래 호환성: Git 버전이 업데이트되면서 smudge 필터가 정의되지 않았을 때의 기본 동작이 변경될 수 있다. 명시적 설정이 이러한 변화에 대비한다.
팀 협업의 일관성: 모든 팀원이 동일한 설정을 사용할 수 있도록 clean과 smudge 모두 명시적으로 문서화하는 것이 협업에 도움이 된다.
디버깅 용이성: 문제가 발생했을 때 “반쪽짜리” 설정보다는 완전한 설정이 디버깅에 유리하다.

방어적 접근법의 예시

smudge 필터를 설정하는 것은 “방어적 프로그래밍”의 좋은 예시이다. 현재 필요하지 않더라도 명시적으로 설정함으로써 미래에 발생할 수 있는 문제를 예방한다. 이는 소프트웨어 개발에서 중요한 원칙으로, Git 설정에도 동일하게 적용된다.

# 완전한 설정 (권장)
git config filter.html-comments.clean 'sed -e "/<!--/,/-->/d"'
git config filter.html-comments.smudge 'cat'

# 불완전한 설정 (권장하지 않음)
git config filter.html-comments.clean 'sed -e "/<!--/,/-->/d"'

이러한 완전한 설정은 Git의 작동 방식에 대한 이해를 보여주며, 장기적으로 안정적인 워크플로우를 구축하는 데 도움이 된다.