git status를 쳤는데 한글 파일 이름이 이렇게 나온다면:
?? "\355\232\214\354\235\230\353\241\235.txt"
파일이 깨진 것이 아닙니다. git이 한글 같은 비영어 글자를 일부러 숫자 코드로 바꿔 보여 주는 것이고, 설정 한 줄이면 제대로 보입니다.
git config --global core.quotepath false
이 글에서는 이 설정의 정확한 의미와 함께, 맥에서 만든 한글 파일이 윈도우·리눅스에서 "같은 이름 파일 두 개"로 보이는 문제(자소 분리)까지 정리했습니다. 아래 출력은 모두 2026년 11월 15일 git 2.43에서 직접 실행한 결과입니다.

1. 한글 파일명이 숫자로 나오는 이유
git 공식 문서에 따르면 core.quotePath가 켜져 있으면(기본값 true) 파일 이름을 출력하는 명령은 0x80보다 큰 바이트를 "특이한 글자"로 보고 \302\265 같은 8진수로 바꿔 씁니다. 한글은 UTF-8에서 한 글자가 3바이트이고 모두 0x80보다 크기 때문에, "회의록.txt"가 \355\232\214\354\235\230\353\241\235.txt처럼 9개의 숫자 묶음으로 나옵니다.
직접 해 본 결과입니다. 한글 파일 두 개를 만들고 git status --short를 실행하면:
?? "\353\263\264\352\263\240\354\204\234 \354\265\234\354\242\205.md"
?? "\355\232\214\354\235\230\353\241\235.txt"
git ls-files, git diff --stat, git log --stat도 똑같이 나옵니다. 반면 커밋 메시지("첫 커밋")는 그대로 한글로 보입니다. 이 설정은 파일 경로에만 적용되기 때문입니다.
2. 해결: core.quotepath false
git config --global core.quotepath false
공식 문서 설명대로 이 값을 false로 바꾸면 0x80보다 큰 바이트를 더 이상 특이한 글자로 보지 않습니다. 같은 저장소에서 git status --short를 다시 실행하면:
?? "보고서 최종.md"
?? 회의록.txt
'보고서 최종.md'처럼 띄어쓰기가 들어간 이름은 git status --short에서 큰따옴표로 감싸져 나옵니다. 숫자 대신 한글이 보이면 정상적으로 고쳐진 것입니다.
--global을 빼면 지금 저장소에만 적용됩니다.- 큰따옴표, 역슬래시, 제어 문자는 이 설정과 상관없이 계속 이스케이프됩니다. 띄어쓰기는 이스케이프 대상이 아니라서
ls-files나diff에서는 따옴표 없이 나오고,status에서만 이름 전체를 따옴표로 감싸 보여 줍니다. - 한 번만 보고 싶다면 설정을 바꾸지 않고
git -c core.quotepath=false status처럼 쓸 수도 있습니다. - 스크립트에서 파일 이름을 다룬다면
-z옵션이 더 안전합니다. 공식 문서에 따르면-z를 쓰면 많은 명령이 경로를 가공 없이 그대로 출력합니다.
이 설정을 바꿔도 화면에서 계속 깨져 보인다면, git이 아니라 터미널 글꼴이나 인코딩 문제입니다. 이때는 터미널이 UTF-8로 설정돼 있는지부터 확인하세요.
3. 맥에서 만든 한글 파일이 두 개로 보일 때 (자소 분리)
두 번째 문제는 더 헷갈립니다. 맥에서 올린 저장소를 윈도우나 리눅스에서 받았더니,
- 같은 이름의 한글 파일이 두 개 있거나
- 파일 이름이 'ㅎㅚㅇㅢㄹㅗㄱ'처럼 자음·모음으로 풀려 보이거나
- 수정한 적 없는 한글 파일이 계속 "새 파일"로 잡히는 경우입니다.
원인은 유니코드 정규화 방식입니다. 한글 '회'는 완성형 글자 하나(NFC)로 저장할 수도 있고, 'ㅎ+ㅚ' 두 조각(NFD)으로 저장할 수도 있습니다. 예전 맥 파일 시스템(HFS+)은 파일 이름을 NFD로 바꿔 저장했고, 지금의 APFS는 받은 이름을 그대로 저장하지만 맥에서 만든 파일 이름이 NFD로 들어오는 경우가 여전히 많습니다. 윈도우와 리눅스는 보통 NFC를 씁니다. 눈에는 똑같아 보여도 컴퓨터에게는 다른 이름입니다.
직접 재현해 봤습니다. 리눅스에서 NFD 이름과 NFC 이름으로 "회의록.txt"를 하나씩 만들면 둘 다 따로 생깁니다. 파이썬으로 이름 길이를 세 보면 NFD 쪽은 11글자, NFC 쪽은 7글자입니다. git status에도 똑같아 보이는 "회의록.txt"가 두 줄 나오고, 둘 다 커밋됩니다.
맥 쪽에서 막기
공식 문서에 따르면 core.precomposeUnicode는 맥용 git에서만 쓰는 설정이고, true로 두면 맥이 분해한 파일 이름을 git이 다시 합쳐서(NFC) 다룹니다. 맥과 윈도우·리눅스가 저장소를 같이 쓸 때 유용하다고 설명합니다. 맥에서 아래처럼 켜 두세요.
git config --global core.precomposeunicode true
저장소마다 이 값이 따로(local) 저장돼 있으면 그쪽이 우선합니다. 켰는데도 그대로라면 저장소 폴더에서 git config --show-origin core.precomposeunicode로 어느 설정 파일의 값이 쓰이는지 확인해 보세요.
이미 NFD로 올라간 파일 고치기
이미 저장소에 NFD 이름으로 들어간 파일은 이름을 NFC로 바꿔서 다시 커밋해야 합니다. 윈도우나 리눅스 PC의 저장소 맨 위 폴더에서 아래 파이썬 코드를 실행하면, 맨 위 폴더의 NFD 이름 파일을 찾아 git mv로 바꿉니다(하위 폴더까지 하려면 os.walk로 넓히면 됩니다).
import os, subprocess, unicodedata
for name in os.listdir('.'):
if name.startswith('.'):
continue
nfc = unicodedata.normalize('NFC', name)
if nfc != name:
subprocess.run(['git', 'mv', name, nfc], check=True)
print('바꿈:', nfc)
직접 실행하면 git status에 R 회의록.txt -> 회의록.txt처럼 같은 이름으로 "이름 바꿈"이 잡힙니다. 이상해 보여도 정상입니다. 겉모양은 같지만 NFD에서 NFC로 바뀐 것이고, 커밋한 뒤 다시 확인하면 NFC 이름 하나만 남아 있습니다. 같은 이름의 NFC 파일이 이미 따로 있다면 git mv가 막히니, 두 파일 내용을 비교해 하나를 지운 뒤 실행하세요.
4. 한 줄 요약
| 증상 | 원인 | 해결 |
|---|---|---|
한글 파일명이 \355\232\214… 숫자로 나옴 |
core.quotePath 기본값(true) | git config --global core.quotepath false |
| 같은 한글 파일이 두 개 / 자음·모음으로 풀림 | 맥의 NFD 파일 이름 | 맥에서 core.precomposeunicode true, 이미 올라간 파일은 NFC로 git mv |
| 설정을 바꿔도 화면이 깨짐 | 터미널 인코딩·글꼴 | 터미널을 UTF-8로 설정 |
2026년 11월 15일 리눅스의 git 2.43.0과 파이썬 3.13으로 직접 실행해 확인했습니다. 맥 전용 설정(core.precomposeUnicode)은 맥에서 직접 시험하지 못해 git 공식 문서 설명을 기준으로 적었습니다.
초안 작성과 검수에 AI를 사용했고, 글의 명령과 출력은 모두 직접 실행해 대조했습니다.
출처
- git-config 공식 문서 (core.quotePath, core.precomposeUnicode): https://git-scm.com/docs/git-config
- 유니코드 정규화 형식 (Unicode Standard Annex #15): https://unicode.org/reports/tr15/
'개발 오류 해결' 카테고리의 다른 글
| 파이썬 'cp949' codec can't decode 오류 해결: 한글 깨짐 5가지 경우와 파이썬 3.15에서 달라진 점 (0) | 2026.11.16 |
|---|