P2-14.2 브랜치(branch), 커밋(commit), 문서 재현성¶

Section ID: P2-14.2 Version: v2026.09.15

브랜치와 커밋¶

Git 공식 책은 브랜치를 커밋을 가리키는 가벼운 포인터로 설명합니다. 같은 커밋에서 출발한 두 브랜치도 서로 다른 커밋을 쌓으며 별개의 이력으로 이어질 수 있습니다.

문서 프로젝트에서는 다음 상황에서 브랜치가 필요합니다.

• 작성 중인 원고와 배포 중인 원고를 구분해야 한다.
• 실험적인 목차 변경을 배포본에 바로 반영하지 않아야 한다.
• 이미지, 코드, 문서 구조가 함께 바뀌는 동안 중간 상태가 공개되지 않아야 한다.
• 배포 실패가 생겼을 때 어느 변경이 원인인지 추적해야 한다.

브랜치 이름만으로 공개 여부가 정해지는 것은 아닙니다. 어떤 브랜치의 변경을 사이트에 반영할지는 배포 설정으로 결정합니다.

브랜치는 커밋을 가리킨다¶

main과 dev가 모두 커밋 A를 가리키는 상태에서 dev에 새 커밋 B를 만들었다고 합시다. dev는 B로 이동하지만 main은 A에 남습니다. 두 브랜치가 전체 프로젝트를 서로 별개의 폴더로 복사한 것은 아닙니다. A까지의 이력을 공유하면서 가리키는 커밋이 달라진 것입니다.

flowchart TD
  A["커밋 A"] --> B["커밋 B"]
  M["main"] -.-> A
  D["dev"] -.-> B
  H["HEAD"] -.-> D

실선은 A 다음에 B가 만들어진 순서이며, 점선은 브랜치와 HEAD가 무엇을 가리키는지 나타냅니다. A와 B는 설명용 이름이며 실제 Git 명령에서 쓰는 해시가 아닙니다.

현재 브랜치와 커밋 연결은 다음 명령으로 확인합니다.

1
2

git branch --show-current
git log --oneline --graph --decorate --all -5

첫 명령은 현재 브랜치 이름을, 둘째 명령은 최근 커밋 다섯 개의 연결과 브랜치 이름을 보여 줍니다. --all은 여러 참조에서 도달 가능한 이력을 함께 조회하며 원격 서버의 최신 상태를 다운로드하는 옵션은 아닙니다.

앞 절의 git-record-practice 연습 저장소에서 세 커밋을 모두 만든 뒤, 별도 작업 브랜치를 만들 수 있습니다.

1
2
3
4

git status --short
git switch -c revise-chart
git branch --show-current
git switch practice

작업 트리가 깨끗한 상태에서 실행하면 현재 커밋에서 revise-chart를 만들고 전환했다가 practice로 돌아옵니다. 아직 새 커밋이 없으므로 두 브랜치는 같은 커밋을 가리킵니다. git branch revise-chart는 생성만 하고 전환하지 않는다는 차이가 있습니다.

브랜치를 바꾸면 Git은 그 브랜치의 파일 상태에 맞춰 작업 트리와 스테이징 영역을 갱신합니다. 커밋하지 않은 수정은 조건에 따라 새 브랜치로 따라갈 수 있고, 전환 때문에 수정 내용이 덮어써질 때는 Git이 전환을 거부합니다. 따라서 브랜치 전환을 “수정 내용을 자동으로 다른 상자에 보관하는 일”로 이해하면 안 됩니다.

작성 브랜치와 배포 브랜치¶

이 책은 dev를 작성·편집 브랜치, main을 배포 기준 브랜치로 사용합니다. 이는 이 저장소의 운영 규칙이며 Git이 정한 이름별 기능은 아닙니다. 다른 프로젝트에서는 하나의 브랜치나 다른 이름으로 운영할 수도 있습니다.

flowchart TD
  A["dev에서 작성·커밋"]
  B["원고·코드·그림 검토"]
  C["검토한 변경을 main에 반영"]
  D["origin/main으로 push"]
  E["배포 작업 성공·페이지 확인"]

  A --> B --> C --> D --> E

작성 브랜치에는 원고·예제 코드·차트의 수정 이력을 남깁니다. 배포 기준 브랜치는 공개할 상태를 가리키도록 운영할 수 있습니다.

배포 브랜치는 공개 기준을 반영하는 브랜치의 한 예시입니다. 정적 사이트 배포에서는 이 브랜치에 반영되는 일이 곧 배포 실행으로 이어질 수 있습니다. 따라서 배포 브랜치로 옮기는 작업은 단순 저장이 아니라 공개 문서를 갱신하는 행위로 볼 수 있습니다.

커밋·푸시·배포의 차이¶

원격 저장소는 다른 위치에 있는 Git 저장소입니다. origin은 원격 주소에 붙이는 관례적인 별칭이며 GitHub라는 서비스 이름 자체를 뜻하지 않습니다.

원격 주소가 등록되어 있고 쓰기 권한이 있는 경우, 다음 명령은 로컬 dev를 origin의 dev로 올리는 예입니다. 위 연습 저장소에는 원격을 등록하지 않았으므로 이 명령을 그대로 실행할 조건이 갖춰져 있지 않습니다.

1

git push origin dev

원격에 로컬이 포함하지 않은 커밋이 있으면 일반적인 push가 거절될 수 있습니다. 그때는 원격 이력을 확인하고 변경을 통합한 뒤 다시 올립니다. 로컬 main으로 전환하는 것만으로 dev의 변경이 합쳐지지는 않습니다. 두 이력의 변경을 결합하는 작업이 병합(merge)이며, 같은 부분을 다르게 고쳤다면 사람이 충돌을 해결해야 할 수 있습니다.

관련 파일을 같은 변경으로 묶기¶

커밋은 작성 중인 상태도 기록할 수 있습니다. 공개할 커밋을 고를 때는 원고와 연결된 자산이 함께 맞는지 확인해야 합니다.

예를 들어 P2-13.3을 작성한다면 다음 파일들이 함께 바뀔 수 있습니다.

이 파일들이 서로 연결되어 있다면 한 커밋에 묶는 것이 자연스럽습니다. 반대로 같은 시점에 CSS 레이아웃도 고쳤다면, 그것은 별도 커밋으로 나누는 편이 이력을 읽기 쉽습니다.

문서 재현성¶

소프트웨어에서 재현성(reproducibility)은 같은 코드와 환경에서 같은 결과를 다시 얻는 능력으로 자주 설명됩니다. 이 책에서는 문서 재현성을 조금 더 넓게 봅니다.

문서 재현성은 다음 질문에 답할 수 있어야 합니다.

• 이 설명은 어떤 근거를 바탕으로 작성되었는가?
• 본문에 들어간 차트는 어떤 코드로 만들었는가?
• 예제 코드는 어떤 패키지 버전을 전제로 하는가?
• 배포 목차에는 어떤 시점에 들어갔는가?
• 나중에 오류를 발견하면 어느 커밋에서 생겼고 어떤 수정 커밋으로 바로잡았는가?

따라서 문서 재현성은 원고만의 문제가 아닙니다. 원고, 코드, 이미지, 조사 메모, 배포 설정이 함께 맞아야 합니다. 같은 커밋의 원고와 생성 코드를 사용하고 필요한 데이터·패키지 버전·설정을 맞추면 이전 문서 결과를 다시 만드는 데 필요한 조건을 추적할 수 있습니다.

커밋은 기록한 파일을 고정하지만 가상환경, 설치된 글꼴, 외부 데이터 파일을 자동으로 보관하지 않습니다. 예를 들어 같은 그래프 코드라도 Matplotlib나 글꼴 버전이 다르면 글자 폭과 이미지 배치가 달라질 수 있습니다. 난수가 있으면 시드도 기록하되, 시드 하나가 모든 환경에서 동일한 파일을 보장하지는 않습니다.

P2-13.3의 생성 스크립트는 본문 자산을 덮어쓰지 않고 별도 폴더에 그래프를 만들 수 있습니다. 저장소 루트에서 Matplotlib·NumPy와 기본 글꼴 Noto Sans CJK JP가 설치된 Python 환경을 사용합니다. 다른 글꼴을 --font-family로 선택하면 외형이 달라질 수 있습니다.

그래프 생성 코드

1

python docs/assets/part-02/chapter-13/p2_13_3_compare_and_save.py --language all --output-dir .tmp/p2-14-reproduce

세 언어로 된 SVG 여섯 개가 만들어집니다. 그중 subplot-loss-accuracy-ko.svg를 본문 그림과 비교할 때는 파일이 존재한다는 사실뿐 아니라 마지막 정확도, 축 범위, 범례도 확인합니다. 같은 환경에서는 파일 해시까지 비교할 수 있지만, 해시가 다르면 먼저 수치가 달라졌는지 서식만 달라졌는지 구분합니다.

공개할 파일의 연결 확인¶

배포 전에 최소한 다음 연결을 확인합니다.

이 확인을 하지 않으면 배포 브랜치 반영 뒤 공개 페이지에서 링크가 깨지거나, 이미지가 누락되거나, 설명과 예제가 서로 달라질 수 있습니다.

사례 1. 원고는 0.86인데 그림은 0.88이라면¶

공개된 문서에는 마지막 정확도가 0.88인 그림이 들어 있습니다. 작성 브랜치에서 마지막 정확도를 0.86으로 바꾸고 원고도 마지막 세 반복에서 정확도 0.86 유지로 고쳤다고 합시다. 생성 코드를 바꾸었어도 이미지를 다시 만들지 않았다면 본문과 그림은 서로 다른 결과를 설명합니다.

작성 브랜치의 중간 커밋은 수정 과정을 남기는 데 유용합니다. 공개 전에는 생성 코드를 실행해 이미지를 갱신하고, 본문이 그 파일을 가리키는지 확인합니다. 사이트 빌드가 성공하더라도 숫자의 불일치까지 자동으로 검증되는 것은 아닙니다.

배포가 특정 브랜치의 push에 연결되어 있다면 점검한 상태를 그 브랜치에 반영하고 원격에 올릴 때 배포 작업이 시작됩니다. 로컬 커밋만으로 공개 사이트가 바뀌는 것은 아닙니다. 배포 작업이 성공했는지와 실제 페이지에 어떤 결과가 보이는지도 확인해야 공개 상태를 판단할 수 있습니다.

수정 파일을 직접 고르기¶

원고와 생성 코드에서 마지막 정확도를 0.86으로 바꿨고, 아직 그림을 재생성하지 않았으며, 별도로 CSS 색상도 바꿨다고 합시다. “정확도 설명 수정” 커밋에 어떤 파일을 넣을지 고릅니다.

1. 현재 그림을 그대로 넣으면 설명과 맞는지 판단합니다.
2. 그림을 재생성한 뒤 원고·코드·해당 그림을 같은 변경으로 선택합니다.
3. CSS 변경이 정확도 설명과 독립적인지 판단합니다.

이 경우에는 그림을 갱신해야 하고, 독립적인 CSS 변경은 별도 커밋으로 남깁니다. 그 커밋을 dev에 push했더라도 배포가 main에만 연결되어 있다면 공개 사이트는 아직 이전 상태입니다.

체크리스트¶

• 브랜치는 작업 흐름을 분리하는 이름 붙은 이력이라고 설명할 수 있는가?
• 작성 브랜치와 배포 브랜치의 역할 차이를 설명할 수 있는가?
• 커밋은 파일 묶음이 아니라 의미 있는 변경 묶음이어야 한다는 점을 설명할 수 있는가?
• 한 커밋에 들어갈 파일을 변경 목적 기준으로 고를 수 있는가?
• 문서 재현성은 원고만의 문제가 아니라 코드, 이미지, 조사 메모, 배포 목차가 함께 맞아야 생긴다는 점을 설명할 수 있는가?
• 배포 브랜치 반영이 공개 배포로 이어질 수 있으므로 별도 판단이 필요하다는 점을 말할 수 있는가?
• 작성 중 커밋과 공개할 커밋의 점검 범위가 다른 이유를 설명할 수 있는가?
• 새 브랜치를 만든 직후 두 브랜치가 같은 커밋을 가리킬 수 있는 이유를 설명할 수 있는가?
• 커밋·푸시·배포를 구분하고 브랜치 전환과 병합의 차이를 말할 수 있는가?
• 코드의 커밋만으로 설치 환경과 그림 재현이 보장되지 않는 이유를 설명할 수 있는가?
• 배포 전 사이트 목차 설정, 이미지, 조사 메모, 빌드를 함께 확인해야 하는 이유를 설명할 수 있는가?

출처와 참고 자료¶

• Pro Git, Branches in a Nutshell 확인 날짜: 2026-09-15. 브랜치·커밋·HEAD 참조 관계.
• Git project, git-branch 확인 날짜: 2026-09-15. 브랜치 생성과 조회.
• Git project, git-switch 확인 날짜: 2026-09-15. 브랜치 전환과 미커밋 변경 보호.
• Git project, git-log 확인 날짜: 2026-09-15. 그래프·브랜치 이름·여러 참조의 이력 조회.
• Git project, git-push 확인 날짜: 2026-09-15. 원격 참조 갱신과 push 거절 조건.
• Git project, git-merge 확인 날짜: 2026-09-15. 이력 통합과 충돌.
• GitHub Docs, Configuring a publishing source for your GitHub Pages site 확인 날짜: 2026-09-15. 브랜치 또는 Actions 기반 배포 설정.