문서 작업 가이드
텍스트 개정본을 비교하고 Unified Diff 검증하기
정확한 텍스트 비교 기준선을 만들고 CRLF·가장자리 공백 잡음을 분리한 뒤 변경 hunk와 unified patch를 적용 전에 검증합니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
텍스트·코드·Unified Patch Diff 비교기에서 “Patch 준비 전 설정 변경 검토” 픽스처를 임의로 고치거나 단순화하지 않고 실행했습니다. “정확한 줄 비교 기준선 생성”에서 “줄바꿈과 가장자리 공백 잡음 진단”로 이어지는 결과를 대조했습니다. 비성공 경로 검토에는 “화면의 치환을 한 번만 셈”, “모든 들여쓰기를 미관 차이로 취급” 조건을 사용했습니다.
비교 결과는 추가 패치 행 3개, 삭제 행 2개, 짝지은 변경 2개와 hunk 1개를 보고했고, 포트·로그 수준·/ready 경로 변경이 내보낸 패치에 드러났습니다.
문제 상황
비교 화면이 깔끔해도 잘못된 차이를 숨길 수 있습니다. CRLF와 LF 차이가 검토 화면을 가득 채우고, trim이 의미 있는 들여쓰기를 감추며, 마지막 줄바꿈 누락이 검사를 깨뜨릴 수 있습니다. 위치끼리만 비교하면 삽입 하나가 수백 개의 치환처럼 보입니다. Unified diff에는 또 다른 위험이 있습니다. 문맥과 파일 header가 대상과 맞아야 하고, 무시 옵션으로 만든 patch는 원본의 모든 바이트 차이를 나타내지 않습니다. 따라서 정확한 기준선을 보존하고, 필터 보기는 진단으로 한정하며, patch의 추가·삭제와 화면용 치환 짝을 구분하고, 내보낸 결과를 대상 파일의 복사본에서 증명해야 합니다.
이럴 때 사용하세요
- 전체 저장소 클라이언트 밖에서 코드나 설정 개정본을 검토해야 할 때
- 환경 파일 두 개가 다르게 보이며 CRLF 또는 줄 가장자리 공백이 원인일 수 있을 때
- 기밀 내용을 비교 서버에 보내지 않고 문서의 정확한 삽입·삭제를 확인할 때
- 생성 결과나 snapshot이 바뀌어 생성 단계를 감사해야 할 때
- Unified diff를 다른 사람에게 전달하거나 저장소 적용 전에 확인할 때
단계
- 1단계
두 원본을 동결하고 성격 분류
손대지 않은 복사본을 보관하고 어느 쪽이 원본이고 수정본인지 표시합니다. 붙여넣기 전에 문자 인코딩을 확인하고 비밀정보나 개인정보 포함 여부를 파악하며 비교에 필요하지 않은 데이터만 제거합니다. 아직 어느 쪽도 포맷하지 마세요.
- 2단계
정확한 줄 비교 기준선 생성
왼쪽에 원본, 오른쪽에 수정본을 넣습니다. 줄 모드와 문맥 3줄을 선택하고 두 동등성 필터를 모두 끈 채 실행합니다. 원시 추가 줄, 원시 삭제 줄, hunk 수, 마지막 줄바꿈 표식을 기록합니다.
- 3단계
각 변경 블록의 이유 확인
개별 행보다 hunk 범위를 먼저 읽습니다. 모든 추가와 삭제가 의도한 것인지 확인하세요. 짝지은 치환 행은 인접한 patch 줄을 화면용으로 정렬한 것이므로 둘이 의미상 관련 있다고 가정하지 말고 실제 텍스트를 비교합니다.
- 4단계
줄바꿈과 가장자리 공백 잡음 진단
정확한 기준선이 서식 차이로 가득하면 먼저 Line Ending Detector로 파일을 검사합니다. 그다음 'CRLF를 LF로 취급' 또는 '줄 가장자리 공백 무시'를 한 번에 하나씩 켜 다시 실행합니다. 내부 공백은 계속 유효하며 정확한 기준선을 진실의 원본으로 보존합니다.
- 5단계
작은 변경에만 문자 모드 사용
짧은 문장이나 식별자의 변경 구간만 문자 모드로 비교합니다. 강조 단위는 grapheme cluster가 아닌 Unicode 코드 포인트이므로 결합 문자, 국기, ZWJ 이모지가 여러 단위일 수 있습니다. patch 출력은 줄 모드로 돌아가서 만듭니다.
- 6단계
필터 없는 patch만 내보내기
두 필터를 끄고 다시 실행한 뒤 Unified patch에서 `--- before.txt`, `+++ after.txt` header, hunk 범위, 마지막 줄바꿈 누락 표식을 확인합니다. 기본 이름은 검토용이므로 통제된 patch 준비 단계에서만 검증된 저장소 상대 경로로 바꿉니다.
- 7단계
Dry run 후 복사본에 적용하고 재검사
올바른 경로 header를 준비한 뒤 `git apply --check` 같은 대상 도구의 검사 모드나 patch dry run을 사용합니다. 폐기 가능한 작업 복사본에 적용해 의도한 수정본과 비교하고, 포매터와 테스트를 별도로 실행하며 정확한 입력과 검토한 patch를 변경 기록에 보관합니다.
예시
Patch 준비 전 설정 변경 검토
입력
before.txt(마지막 줄바꿈 있음)
server:
port: 8080
log: info
routes:
- /health
after.txt(마지막 줄바꿈 있음)
server:
port: 8081
log: debug
routes:
- /health
- /ready
출력
정확한 줄 결과: 추가 patch 3줄, 삭제 patch 2줄, 화면용 치환 짝 2개, 변경 hunk 1개. port와 log 변경, /ready 추가 의도를 확인하고 필터를 끈 상태를 유지합니다. generic before.txt/after.txt header를 검사한 뒤 대상 경로 준비와 dry run을 별도로 수행합니다.흔한 실수
처음부터 무시 옵션을 켬
깔끔한 필터 결과만으로는 필터가 무엇을 지웠는지 알 수 없습니다. 정확한 기준선을 먼저 남기고 필터를 한 번에 하나씩 사용해 잡음을 분류하세요.
화면의 치환을 한 번만 셈
Unified diff에서 치환은 삭제 한 줄과 추가 한 줄입니다. 짝지은 행 개수는 읽기 보조이며 원시 patch 개수를 대체하지 않습니다.
모든 들여쓰기를 미관 차이로 취급
Python, YAML, Makefile 같은 형식에서는 앞 공백이 의미를 바꿉니다. 줄 가장자리 필터도 진단에만 사용하고 일괄 승인 근거로 쓰지 마세요.
Generic patch header를 그대로 적용
내보낸 검토 patch는 before.txt와 after.txt를 사용합니다. 저장소 적용에는 의도적으로 준비한 대상 경로와 검사 또는 dry run이 필요합니다.
Diff 완료를 동작 검증으로 간주
텍스트 변경이 정확해 보여도 동작은 틀릴 수 있습니다. 설정 파싱, 테스트, 생성 산출물 검증, 실행 동작 검토를 patch 뒤에 수행하세요.
자주 묻는 질문
첫 비교에서 필터를 꺼야 하는 이유는 무엇인가요?
모든 줄과 종결자 차이를 증거로 보존하기 때문입니다. 이후 필터 실행은 잡음을 설명할 수 있지만 의도적으로 무시한 차이를 복원하지 못합니다.
CRLF와 LF 차이를 커밋해야 하나요?
일반적으로 .gitattributes와 편집기 설정에 기록된 저장소 정책을 따릅니다. 먼저 원인을 진단하고 가능하면 줄바꿈 정규화를 별도 변경으로 수행해 로직 수정과 전체 줄바꿈 변경을 섞지 마세요.
줄 가장자리 공백 무시는 들여쓰기도 무시하나요?
그렇습니다. 동일성 판단에서 각 줄의 시작과 끝을 모두 trim합니다. 의미 있는 들여쓰기를 숨길 수 있으므로 진단용으로만 쓰고 승인 전 정확 비교로 돌아가세요.
치환 개수가 추가·삭제 개수와 다른 이유는 무엇인가요?
Patch에는 독립적인 삭제 줄과 추가 줄이 있습니다. 좌우 보기는 화면의 빈칸을 줄이려고 인접한 줄을 위치 기준으로 짝지을 뿐, patch에 별도 치환 연산을 추가하지 않습니다.
문자 모드로 이모지 텍스트를 안전하게 비교할 수 있나요?
Unicode 코드 포인트 차이는 정확히 찾지만 화면에서 하나인 이모지는 지역 표시자, modifier, variation selector, ZWJ 결합을 포함할 수 있습니다. 주변 grapheme과 렌더링 결과를 함께 검토하세요.
검토 증거로 무엇을 보관해야 하나요?
비밀정보를 불필요하게 저장하지 않으면서 정확한 원본 파일의 식별자나 hash, 선택 옵션, 원시 개수, 검토 hunk, 마지막 줄바꿈 상태, 필터 없는 patch, 경로 준비, dry-run 결과, 적용 후 테스트를 보관합니다.