core.autocrlf 설정, 그리고 팀 프로젝트에서 가장 완벽하게 해결하는 .gitattributes 파일 작성법까지 알기 쉽게 정리해 드립니다! 💡
팀 프로젝트를 시작하고 설레는 마음으로 코드를 커밋하려는데, 터미널 가득 노란색 경고 문구가 주르륵 뜨면서 식은땀 흘려보신 적 있으신가요? warning: LF will be replaced by CRLF in ... 같은 메시지 말이에요. 저도 개발 초기에 윈도우 노트북을 쓰면서 맥북을 쓰는 팀원과 깃허브로 협업할 때 이 에러를 마주하고 정말 멘붕에 빠졌던 기억이 생생해요. 한 줄 고쳤을 뿐인데 파일 전체가 수정되었다고 뜨거나, 깃 충돌이 와르르 발생하기도 했죠. 😊
“그냥 빨간 에러가 아니라 워닝(Warning)이니까 무시해도 되려나?” 하고 넘기시는 분들도 계실 텐데요. 솔직히 말씀드리면 이 줄 바꿈 문제를 초기에 제대로 잡아두지 않으면 나중에 코드 리뷰할 때 수백 줄의 의미 없는 변경 사항이 생기고, 리눅스 서버에 배포했을 때 셸 스크립트가 실행되지 않는 대참사가 벌어지기도 한답니다. 오늘은 윈도우와 맥 양쪽 환경에서 아주 깔끔하게 Git 줄 바꿈 에러를 방지하는 실전 가이드를 완벽하게 파헤쳐 볼게요!
1. 도대체 왜 이런 에러가 발생할까요? CRLF vs LF 완벽 이해 🤔
이 문제를 근본적으로 해결하려면 먼저 우리가 키보드에서 Enter(엔터키)를 눌렀을 때 컴퓨터 내부에서 어떤 일이 일어나는지 알아야 해요. 사람이 보기에는 똑같이 다음 줄로 넘어가는 것이지만, 운영체제(OS)마다 줄을 바꾸는 문자 규칙이 완전히 다르거든요.
타자기 시절을 떠올려보시면 쉬워요. 타자기는 글자를 찍는 캐리지(Carriage)를 맨 앞으로 되돌리는 동작과, 종이를 한 줄 위로 올리는 피드(Feed) 동작이 분리되어 있었어요. 바로 여기서 두 가지 방식이 유래했습니다.
- CRLF (Carriage Return + Line Feed, \r\n): 윈도우(Windows) 운영체제에서 사용하는 기본 줄 바꿈 방식이에요. 커서를 맨 앞으로 보내고(CR) 다음 줄로 내려가는(LF) 2개의 문자를 합쳐서 1번의 줄 바꿈으로 인식합니다.
- LF (Line Feed, \n): 맥(macOS)과 리눅스(Linux) 환경에서 사용하는 표준 줄 바꿈 방식이에요. 단순히 한 줄 아래로 내리는(LF) 1개의 문자만 사용합니다.
문제는 여기서 생겨요. 맥에서 작업한 파일(LF)을 윈도우 환경에서 열어 수정하면 윈도우 편집기가 이를 CRLF로 바꿔버리고, 반대로 윈도우에서 만든 파일이 맥이나 리눅스 환경으로 넘어가면 보이지 않는 \r 문자가 남아 오류를 뿜어내는 것이죠. Git은 이 차이를 감지해서 개발자에게 “너의 작업 환경에 맞춰 줄 바꿈을 자동으로 변환할 텐데 괜찮겠어?”라고 친절하게 경고를 날려주는 것이랍니다.
리눅스 기반 서버(우분투, CentOS, AWS EC2 등)나 도커(Docker) 컨테이너에서는 셸 스크립트(
.sh)에 윈도우의 CRLF가 포함되어 있으면 /bin/bash^M: bad interpreter 같은 오류를 내며 아예 실행되지 않아요. 줄 바꿈 관리는 단순한 코드 정리를 넘어 배포 안정성과 직결됩니다!
2. core.autocrlf 설정으로 내 컴퓨터 환경 세팅하기 📊
Git에서는 이러한 OS 간의 차이를 자동으로 조율해 주는 core.autocrlf라는 강력한 옵션을 제공하고 있어요. 원리는 아주 간단하고 명쾌합니다. 원격 저장소(GitHub)에는 무조건 LF로 통일해서 올리고, 내 로컬 컴퓨터로 내려받을 때는 내 OS에 맞는 형식으로 변환해 주는 방식이에요.
OS별 core.autocrlf 설정 비교표
| 운영체제 (OS) | 추천 설정값 | 동작 방식 (체크아웃 / 커밋) | 터미널 명령어 |
|---|---|---|---|
| 윈도우 (Windows) | true |
받을 때 CRLF로 변환, 올릴 때 LF로 자동 변환 | git config --global core.autocrlf true |
| 맥 / 리눅스 (macOS / Linux) | input |
받을 때는 그대로 LF 유지, 혹시 모를 커밋 때만 LF로 변환 | git config --global core.autocrlf input |
| 비추천 (공통) | false |
아무 변환도 하지 않음 (협업 시 충돌 유발 위험 100%) | git config --global core.autocrlf false |
맥이나 리눅스를 쓰면서
core.autocrlf true로 설정하면 절대 안 돼요! 맥 환경인데도 파일을 다운로드할 때마다 강제로 CRLF로 바꿔버려서 에디터마다 줄 바꿈 경고가 쏟아지고 깃 상태가 엉망진창이 됩니다. 맥 유저는 반드시 input 옵션을 사용해야 합니다.
3. 내 작업 환경 맞춤 Git 명령어 생성기 🧮
“그래서 지금 당장 내 터미널에 뭘 쳐야 하지?” 헷갈리시는 분들을 위해 준비했어요! 여러분이 사용하시는 OS와 에러 발생 상황을 선택하시면 복사해서 바로 쓸 수 있는 명령어를 즉시 알려드립니다. 아래에서 직접 선택해 보세요. 😊
🔢 내 환경 맞춤 Git 설정 명령어 생성기
4. 팀 프로젝트의 끝판왕: .gitattributes 로 영구 해결하기 👩💼👨💻
하지만 솔직히 말씀드려서 core.autocrlf는 각 팀원의 개인 컴퓨터 로컬 설정에 의존한다는 치명적인 단점이 있어요. 새로 합류한 팀원이 이 설정을 깜빡하고 커밋해 버리면 저장소는 또다시 CRLF와 LF가 뒤섞여 엉망이 되거든요. 개인의 설정과 무관하게 저장소 레벨에서 모든 팀원에게 강제로 규칙을 적용하는 가장 확실한 방법이 바로 .gitattributes 파일입니다.
프로젝트 최상위 루트 디렉터리에 .gitattributes라는 이름으로 파일을 하나 만들고 아래 내용을 채워 넣어주세요.
📝 실무 추천 .gitattributes 템플릿
# 1. 모든 텍스트 파일은 Git이 자동으로 줄바꿈을 LF로 정규화
* text=auto
# 2. 소스 코드 파일은 명시적으로 LF 줄바꿈 강제
*.js text eol=lf
*.ts text eol=lf
*.jsx text eol=lf
*.tsx text eol=lf
*.py text eol=lf
*.java text eol=lf
*.html text eol=lf
*.css text eol=lf
*.json text eol=lf
# 3. 셸 스크립트는 리눅스 실행을 위해 반드시 LF 강제
*.sh text eol=lf
# 4. 윈도우 배치 스크립트는 CRLF 강제
*.bat text eol=crlf
*.cmd text eol=crlf
# 5. 이미지, 바이너리 파일은 변환 제외
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.pdf binary* text=auto를 맨 위에 선언하면 Git이 파일 내용을 분석해서 텍스트 파일인 경우 자동으로 저장소에 LF로 커밋합니다. 그리고 리눅스 서버에서 구동되는 *.sh 파일이나 바이너리 파일들은 명시적으로 제외/지정해 주는 것이 프로페셔널한 실무 팁이에요!
5. 실전 예시: 이미 줄 바꿈이 꼬여버린 프로젝트 한 방에 복구하기 📚
“아뿔싸! 저희 프로젝트는 이미 수십 개 파일의 줄 바꿈이 뒤섞여서 파일마다 변경 사항이 수백 줄씩 떠요. 어떡하죠?” 걱정하지 마세요. Git의 --renormalize 명령어를 사용하면 기존 파일들의 줄 바꿈을 깔끔하게 재정규화할 수 있습니다.
💡 기존 저장소 줄 바꿈 3단계 복구 프로세스
- 1단계: 현재 작업 중이던 모든 미커밋 파일들을 먼저 커밋하거나
git stash로 임시 보관합니다. - 2단계: 프로젝트 루트에 위의
.gitattributes파일을 생성하고 저장합니다. - 3단계: 터미널에서 아래 재정규화 명령어를 실행합니다:
git commit -m “chore: .gitattributes 추가 및 줄 바꿈(LF) 재정규화”
이렇게 한 번 커밋해 두면 지금까지 꼬여있던 모든 텍스트 파일이 .gitattributes 규칙에 맞춰 일괄 LF로 정리되며, 이후 다른 팀원이 pull 받아도 줄 바꿈 차이로 인한 유령 변경 사항이 완벽히 사라지게 됩니다! ✨
마무리: 핵심 내용 요약 📝
윈도우와 맥의 줄 바꿈 차이는 단순한 OS 특성이지만, 협업 시에는 꽤나 골치 아픈 충돌의 주범이 되곤 합니다. 오늘 다룬 핵심 내용을 빠르게 정리해 볼게요.
- 원인: 윈도우는 CRLF(
\r\n), 맥/리눅스는 LF(\n) 방식을 사용하기 때문에 생기는 경고예요. - 개인 로컬 설정: 윈도우는
core.autocrlf true, 맥은core.autocrlf input을 터미널에서 설정해 주세요. - 팀 협업 표준: 프로젝트 루트에
.gitattributes를 생성해 저장소 차원에서 일관된 LF 규칙을 강제하는 것이 가장 안전합니다. - 기존 파일 복구: 꼬여버린 파일들은
git add --renormalize .명령어로 한 번에 깔끔하게 청소할 수 있습니다.
Git 줄 바꿈(CRLF/LF) 3줄 요약 카드
자주 묻는 질문 ❓
files.eol 값을 \n으로 지정하면 새로 만드는 파일의 기본값을 LF로 고정할 수도 있습니다..gitattributes 파일의 설정이 개인 PC의 core.autocrlf 설정보다 우선순위가 훨씬 높습니다. 따라서 팀 프로젝트에서는 개인 설정을 일일이 확인하지 않아도 프로젝트 내의 .gitattributes 파일 하나로 모든 규칙을 완벽하게 통일할 수 있습니다.core.safecrlf 옵션이 true로 켜져 있어서 되돌릴 수 없는 줄 바꿈 변환을 Git이 원천 차단하기 때문입니다. 터미널에 git config --global core.safecrlf warn을 실행하여 차단 대신 경고만 띄우도록 변경하시면 정상 커밋이 가능합니다..gitattributes에 *.png binary처럼 명시적으로 바이너리 설정을 적어두는 것이 매우 중요합니다.
줄 바꿈 하나 때문에 터미널에서 경고를 마주하면 처음엔 번거롭게 느껴지지만, 원리를 알고 나면 몇 줄의 설정만으로 영원히 작별할 수 있는 문제랍니다. 여러분의 팀 프로젝트도 이번 기회에 .gitattributes 파일 하나로 깔끔하게 정리해 보세요! 혹시 진행하시면서 막히는 부분이나 다른 에러가 발생한다면 언제든 댓글로 편하게 물어봐주세요~ 😊