[Git] 엑셀(.xlsx) 파일 변경 사항(Diff) 확인하는 방법

게임 개발을 하다 보면 기획 데이터나 밸런스 테이블을 엑셀(xlsx)로 관리하는 경우가 많습니다. 하지만 엑셀은 바이너리 파일이라 Git에 올리면 기록이 제대로 남지 않습니다.

누가 어떤 데이터를 잘못 수정했는지 추적하기 어려워 간혹 잘못된 데이터가 빌드에 포함되는 휴먼 에러가 발생하기도 합니다. 이런 불편함을 해결하기 위해, Git에서 엑셀 파일의 diff를 명확하게 볼 수 있는 방법을 공유합니다.

 

Git에는 바이너리 파일을 비교하기 전, 임시로 텍스트 파일로 변환하여 대조해 주는 textconv 기능이 있습니다. 엑셀 파일을 백그라운드에서 임시로 CSV 텍스트로 변환해 주는 파이썬 스크립트를 연결하여, Git과 Fork 같은 GUI 앱이 그 텍스트를 대조해 변경 사항을 눈으로 보여주도록 만들 것입니다.

엑셀을 CSV로 변환하는 도구는 빠르고 대용량 처리에 좋은 xlsx2csv 라이브러리를 사용했습니다.

 

https://github.com/dilshod/xlsx2csv

GitHub - dilshod/xlsx2csv: Convert xslx to csv, it is fast, and works for huge xlsx files

 

 

Step 1. 파이썬 라이브러리 설치

엑셀 파일을 읽어서 텍스트로 변환하기 위해 Python 및 변환 라이브러리가 필요합니다. 터미널(또는 CMD)을 열고 아래 명령어로 라이브러리를 먼저 설치해 줍니다.

 

pip install xlsx2csv

 

 

Step 2. .gitattributes 설정

프로젝트 최상위 경로(Root)에 .gitattributes 파일을 만들고(이미 있다면 맨 아래에 추가) 아래 내용을 입력합니다. Git에게 확장자가 .xlsx와 .xls인 파일을 만났을 때 excel이라는 드라이버를 거쳐서 변환하라는 뜻입니다.

 

*.xlsx diff=excel
*.xls diff=excel

 

Step 3. 변환 전용 파이썬 스크립트 작성

윈도우 환경에서 한글 깨짐이나 특수 문자 때문에 발생하는 UnicodeEncodeError를 방지하고, 엑셀 내의 모든 시트를 긁어모아 변환해 주는 전용 스크립트입니다.

프로젝트 폴더 안에 Tools 폴더를 만들고, 그 아래에 excel_diff.py 라는 이름으로 저장합니다.

import sys
import os

# 윈도우 환경의 터미널 출력 인코딩을 UTF-8로 설정하여 한글/유니코드 인코딩 오류 방지
if hasattr(sys.stdout, 'reconfigure'):
    sys.stdout.reconfigure(encoding='utf-8')
elif hasattr(sys.stdout, 'buffer'):
    import io
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

try:
    from xlsx2csv import Xlsx2csv
except ImportError:
    print("Error: xlsx2csv library is not installed.", file=sys.stderr)
    sys.exit(1)

def main():
    if len(sys.argv) < 2:
        sys.exit(1)
        
    file_path = sys.argv[1]
    if not os.path.exists(file_path):
        sys.exit(0)
        
    try:
        # 모든 시트를 순회하며 텍스트 변환 후 출력
        xlsx = Xlsx2csv(file_path, outputencoding="utf-8")
        for sheet in xlsx.workbook.sheets:
            print(f"=== Sheet: {sheet['name']} ===")
            xlsx.convert(sys.stdout, sheet['index'])
            print("\n")
    except Exception as e:
        print(f"Error parsing excel file: {e}", file=sys.stderr)

if __name__ == '__main__':
    main()

 

 

Step 4. .git/config 파일에 드라이버 등록

프로젝트 폴더 내 숨김 폴더인 .git/config 파일(프로젝트 개별 설정 파일)을 메모장이나 코드 에디터로 엽니다. 파일 맨 아랫줄에 다음 설정을 추가해 줍니다. 3단계에서 작성한 파이썬 스크립트를 Git의 엑셀 diff 드라이버로 등록하는 설정입니다.

 

 

[diff "excel"]
	binary = true
	textconv = python Tools/excel_diff.py

 

 

이러면 셋팅이 끝납니다

 

 

적용 확인