git filter-repo를 통한 git 커밋 인코딩 변환하기

1. 개요

이 글에서는 원격 저장소에서 깨진 한글 커밋 메시지를 git filter-repo를 통해 정상적으로 보이게 한 과정에 대해 다룹니다.

2. 문제 상황

이전에 작업했던 로컬 환경에서 커밋을 생성 후, 원격 저장소에 push 했을 때 커밋 메시지가 다음과 같이 깨지는 현상이 발생했습니다.

새로운 로컬 작업 환경에서 문제가 발생했던 해당 원격 저장소를 git clone으로 복제한 후, git log --oneline으로 커밋 로그를 조회한 결과, 다음과 같이 확인되었습니다.

3. 문제 원인

해당 현상에 대해 구글링 해본 결과, git의 인코딩 설정이 utf-8이 아닌 다른 문자 인코딩으로 되어 있는 경우 발생하는 것으로 확인되었습니다. 이로 인해 커밋을 생성한 뒤 원격 저장소에서 메시지를 확인하면, 문자가 깨져 보이는 것이였습니다.

git config --global -l 명령어를 사용하면 현재 작업 환경의 인코딩 설정을 확인할 수 있지만, 문제를 발생했던 로컬 환경은 더 이상 사용할 수 없는 상태였습니다.

그래서 깨진 커밋 메시지가 어떤 인코딩으로 저장되어 있는지 확인하기 위해 git cat-file -p <commit-hash> 명령어를 사용해 커밋 객체의 내부 정보를 직접 조회해보았습니다.

조회 결과, 커밋의 인코딩이 utf-8이 아닌 cp949로 저장되어 있었음을 확인할 수 있었습니다.

4. 문제 해결

기존에 생성했던 커밋들의 메시지가 원격 저장소에서 정상적으로 표시되기 위해서는, 커밋 내부의 인코딩을 cp949에서 utf-8로 변경해야 했습니다.

위 문제사항 대해 chatGPT에게 질문한 결과, git filter-branch라는 명령어를 통해 커밋 히스토리를 수정할 수 있다고 답변했습니다.

하지만 Git 공식문서에서 git filter-branch에서는 다음과 같이 설명합니다.

WARNING

git filter-branch has a plethora of pitfalls that can produce non-obvious manglings of the intended history rewrite (and can leave you with little time to investigate such problems since it has such abysmal performance). These safety and performance issues cannot be backward compatibly fixed and as such, its use is not recommended. Please use an alternative history filtering tool such as git filter-repo.

즉, git filter-branch는 사용 시 의도하지 않은 히스토리 훼손이 발생할 수 있고, 성능 또한 매우 저조하기 때문에 안전성과 효율성 모두에서 문제가 있다고 명시하고 있습니다. 이러한 이유로, Git 공식 문서에서는 git filter-branch의 사용을 권장하지 않으며, 그 대신 git filter-repo와 같은 더 나은 히스토리 필터링 도구의 사용을 추천합니다.

4.1. git filter-repo 소개

git filter-repo는 단일 Python 스크립트로 구성되어 있는 도구입니다. git filter-branch와 유사한 기능을 수행하지만, 성능 저하를 유발하는 단점 없이 훨씬 더 많은 기능을 제공하며, 사소한 변경 작업 외에도 사용성을 확장할 수 있도록 설계되었습니다.

4.2. git filter-repo 설치

아래 설치 과정은 Windows 운영체제를 기준으로 설명합니다.

먼저 Python 공식 사이트에서 Python 3.6 이상 버전을 다운로드하여 설치합니다.

설치 후, 다음 커맨드를 통해 제대로 설치되었는지를 확인합니다.

파이썬 설치 첫 화면에서 "Add Python 3.x to PATH"을 선택해줍니다.

"Add Python 3.x to PATH"은 파이썬이 설치된 경로를 시스템이 인식하여 명령 프롬프트 어느 위치에서나 python 명령을 실행할 수 있도록 해줍니다.

python 설치 이후에는 git-filter-repo GitHub 페이지에서 압축 파일 다운로드합니다.

압축파일 안에 git-filter-repo 파일을 본인이 저장하고 싶은 경로에 복사합니다. 저는 다음과 같은 경로를 생성하여 진행했습니다.

C:\Users\사용자명\AppData\Local\Programs\git-filter-repo\

이후, git-filter-repo가 담긴 경로를 시스템 환경 변수편집 → 환경 변수 → 사용자 변수의 "path"에서 git-filter-repo가 저장된 경로를 추가해줍니다.

4.3. git filter-repo 실행

git filter-repo는 git의 history를 직접 수정하므로 실수 시 복구가 어렵기 때문에 실행하기 전에 현재 작업 중인 폴더를 백업해두는 것이 좋습니다.

cd ..
cp -r 작업폴더 작업폴더-backup
cd 작업폴더

이후 다음 git filter-repo 명령어를 실행해줍니다.

git filter-repo --force --commit-callback '
commit.encoding = b"utf-8"
'

해당 명령어에 대해 간략하게 설명하면 다음과 같습니다.

• --force: 히스토리 변경에 대해 강제로 실행할 수 있도록 허용.

• --commit-callback: 각 커밋을 순회하면서 원하는 처리를 할 수 있도록 하는 콜백 함수 정의.

• 'commit.encoding = b"utf-8"': 각 커밋의 인코딩 정보를 UTF-8로 명시적으로 설정하여, 기존에 깨진 문자 인코딩 문제를 해결.

명령어 실행 후, git log --oneline을 통해 확인해보면 다음과 같이 커밋의 해쉬값이 변경됩니다.

git cat-file -p <commit-hash>를 통해 커밋의 내부 정보를 살펴보면 다음과 같이 인코딩 설정이 utf-8로 변환되어 적용됩니다.

이후 git push origin main --force을 통해 원격 저장소에 push하면, GitHub 페이지에서 해당 리포지토리를 확인해보면 다음과 같이 정상적으로 표시되는 것을 확인할 수 있습니다.