gitattributes

Git에서 파일의 속성을 정의하는 방법

.gitattributes 파일은 Git 저장소에서 파일별 속성을 정의해 주는 설정 파일이다. 브랜치 전략이나 .gitignore처럼 눈에 잘 드러나진 않지만, 저장소를 팀과 함께 사용할 때 텍스트 인코딩·필터·병합 전략·줄 끝(EOL)·바이너리 처리를 세밀하게 통제할 수 있는 핵심 도구다. Git은 소스 관리 시점에 “텍스트냐 바이너리냐”를 자동 판별하지만, 프로젝트마다 규칙이 달라서 오류가 생기는 경우가 많다. gitattributes는 각 파일의 의도된 속성을 명시해 “Git이 알아서 잘 해 주겠지”라는 불확실성을 줄여 준다.

EOL 문제의 본질

운영체제마다 줄바꿈 문자는 다르다.

LF( \n ) — 유닉스·리눅스·macOS
CRLF( \r\n ) — Windows

같은 파일을 서로 다른 OS에서 편집하면 줄바꿈 문자가 뒤섞여 “변경점(diff)이 전부 줄바꿈”으로 표시되거나, 스크립트 실행이 실패하기도 한다. Git에는 core.autocrlf 라는 전역 옵션이 있지만, 팀·레포·파일 단위로는 세밀하지 않다. 그래서 gitattributes의 eol 속성을 이용해 “저장소 안에서는 언제나 LF로, 체크아웃할 때만 OS에 맞게 변환” 같은 정책을 구현한다.

eol 속성 예시

# 기본 정책: 텍스트 파일은 항상 LF로 저장
* text eol=lf
# 윈도우 전용 배치 스크립트는 CRLF를 유지
*.bat text eol=crlf
# Bash 스크립트는 무조건 LF
*.sh  text eol=lf

위 규칙은 “커밋 시 LF로 변환 → 체크아웃 시 각자 환경에 맞게 변환”이라는 흐름을 만들어 줄바꿈 분쟁을 최소화한다.

바이너리 파일 관리

소스 코드뿐 아니라 이미지·폰트·실행 파일·압축 파일 같은 바이너리 자산도 저장소에 포함된다. 텍스트 전용 설정만으로는 다음과 같은 문제를 피할 수 없다.

텍스트로 오인되어 EOL 변환이 일어나 데이터가 깨질 수 있다.
Git이 차이를 분석(diff)·병합(merge)하려 하면서 처리 속도가 느려지거나 충돌이 난다.
대용량 파일이 과거 커밋마다 조금씩 바뀌면 저장소가 폭발적으로 커진다.

`binary`·`-text` 속성

가장 단순한 해법은 해당 확장자를 바이너리로 지정해 Git이 절대 EOL 변환이나 자동 머지를 시도하지 못 하게 하는 것이다.

# 이미지·폰트·압축 파일 등은 모두 바이너리로 취급
*.png  binary
*.jpg  binary
*.ttf  binary
*.zip  binary
*.7z   binary
# `binary`는 내부적으로 `-text diff`와 동일

속성 설명

속성	의미
`binary`	텍스트 속성을 끄고(`-text`) diff 기능도 끈다.
`-text`	텍스트 변환(EOL 포함)만 끈다. diff/merge는 그대로 둘 수 있다.

binary와 -text 모두 “CRLF ↔ LF 변환 금지”가 핵심이다. 다만 -text diff처럼 두 속성을 조합해 세밀하게 제어할 수도 있다.

Git LFS와의 연동

대용량 자산이 많아지면 **Git LFS( Large File Storage )**를 고려하게 된다. gitattributes는 LFS와 맞물려 필수적인 역할을 한다.

# 10 MB 이상인 PSD 파일은 LFS로 관리
*.psd filter=lfs diff=lfs merge=lfs -text

위처럼 filter=lfs를 지정하면 커밋할 때 실제 데이터 대신 작은 포인터 파일만 저장된다. LFS 서버에 실제 바이너리가 보관되어 저장소 크기를 최소화할 수 있다.

core.autocrlf와의 관계

core.autocrlf=false (권장) : 줄바꿈 변환을 gitattributes만으로 통제하겠다는 뜻이다.
core.autocrlf=true 또는 input : 전역 설정이 활성화돼 있으면 .gitattributes 규칙과 충돌할 수 있다. 팀원에게 혼란을 주지 않으려면, 저장소 레벨에서 EOL·바이너리 정책을 명시하고 **전원에게 core.autocrlf=false**를 안내하는 편이 안전하다.

실무 체크리스트

새 저장소를 만들 때 .gitattributes에 기본 EOL·바이너리 정책을 문서화한다.
기존 레포에 도입할 경우, 대규모 줄바꿈·바이너리 속성 변경 커밋이 발생하므로 미리 공지한다.
IDE에서 “저장 시 줄바꿈 자동 변경” 옵션이 켜져 있지 않은지, 또한 바이너리 확장자를 텍스트로 오인하지 않는지 확인한다.
CI 파이프라인에서 git config --global core.autocrlf false를 명시하고, 필요하면 Git LFS를 함께 배포한다.

마무리

줄바꿈(EOL)과 바이너리 파일 관리는 “작동은 하는데 Diff가 지저분하다” 정도의 불편으로 시작해, 빌드 실패·저장소 비대화 같은 예기치 못한 문제로 이어질 수 있다. .gitattributes로 EOL과 바이너리 정책을 선언하고, 팀·CI·IDE를 한목소리로 맞추는 것이 가장 확실한 예방책이다. 한 번 설정해 두면 “줄바꿈 때문에 디버그”하거나 “바이너리 깨져서 복구”하는 난감한 상황을 크게 줄일 수 있다.