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

Section ID: P2-14.2 Version: v2026.07.20

P2-14.1에서는 Git을 변경 이력 관리 도구로 봤습니다. 이제 문서 프로젝트의 작성 흐름에 맞춰 브랜치(branch), 커밋(commit), 배포 문서의 재현성을 연결합니다.

이 절은 Git을 깊게 배우기 위한 절이 아닙니다. 학습 문서가 커질 때 왜 작성 브랜치와 배포 브랜치를 나누고, 왜 커밋 단위를 조심해야 하는지 이해하는 것이 목표입니다. 지금 이 흐름을 잡아 두어야 Part 3 이후 모델 비교와 실험 기록이 늘어나도 작성 중인 판단과 배포해도 되는 설명을 섞지 않게 됩니다.

여기서는 브랜치(branch), 배포(deployment), 작업 흐름(workflow), 정적 배포(static deployment), 문서 재현성(document reproducibility)의 기본 구분을 설명합니다. Git과 커밋 단위 자체의 대표 설명은 P2-14.1과 개념사전에 두고, 여기서는 그 기록을 어떤 작업선과 공개 기준으로 나눌지 설명합니다.

이 절은 작업 흐름 분리와 배포 기준에 초점을 둡니다. 앞 절이 변경을 어떻게 기록할 것인가를 다뤘다면, 여기서는 그 기록을 어떤 작업선으로 나누고 언제 공개 기준으로 넘길 것인가로 질문이 바뀝니다. 따라서 브랜치는 개발자용 추가 기능이 아니라, 바로 앞 장들에서 만든 원고·코드·이미지 해석을 작성 중 판단과 배포 가능한 설명으로 분리해 남기는 운영 기준입니다.

핵심 기준: 브랜치(branch), 커밋(commit), 문서 재현성¶

• 브랜치를 “작업 흐름을 분리하는 이름 붙은 이력”으로 설명할 수 있습니다.
• 문서 프로젝트에서 작성 브랜치와 배포 브랜치의 역할 차이를 설명할 수 있습니다.
• 커밋 단위를 문서 재현성 관점에서 나눌 수 있습니다.
• 배포 전 확인해야 할 파일 관계를 설명할 수 있습니다.
• GitHub Pages 같은 정적 배포 흐름에서 배포 브랜치 반영이 갖는 의미를 설명할 수 있습니다.

먼저 붙잡을 기준¶

이 절에서 가장 먼저 붙잡아야 할 기준은 작성 중 판단과 배포 가능한 설명을 분리해 남기는 일입니다.

즉 Git은 단순 저장이 아니라, 어떤 판단을 언제 어떤 공개 기준으로 남길 것인가를 정하는 운영 도구로 읽어야 합니다.

세 가지 기준¶

이 절 다음 흐름도 단순합니다.

• 바로 뒤 Chapter 15에서는 문서 프로젝트 자동화와 배포 흐름을 더 실제 운영 장면으로 연결합니다.
• Part 3 이후 실험 기록과 비교표가 늘어나면, 여기서 잡은 브랜치·커밋·재현성 기준이 그대로 다시 필요해집니다.

브랜치는 작업 흐름을 분리한다¶

Git 공식 책은 브랜치를 커밋을 가리키는 가벼운 포인터로 설명합니다. 이 내부 표현을 모두 외우기보다, 브랜치를 같은 프로젝트 안에서 작업 흐름을 분리해 진행하기 위한 이름 붙은 이력으로 이해하는 편이 중요합니다.

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

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

브랜치는 단순히 개발자 편의를 위한 기능이 아니라, 독자에게 공개되는 문서의 안정성을 지키는 장치입니다.

문서 프로젝트에서는 작성 브랜치와 배포 브랜치를 나눌 수 있다¶

문서 프로젝트에서는 작성 중인 브랜치와 배포 기준 브랜치를 나누어 운영할 수 있습니다. 브랜치 이름은 팀마다 다르지만, 예를 들어 작성 브랜치와 배포 브랜치처럼 역할을 분리해 둘 수 있습니다.

flowchart TD
  A["작성 브랜치<br/>일반 작성과 편집"]
  B["검토<br/>빌드와 점검"]
  C["배포 브랜치<br/>공개 기준 원본"]
  D["정적 사이트 배포<br/>독자에게 보이는 책"]

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

작성 브랜치는 일반 작성과 편집을 위한 브랜치의 한 예시입니다. 원고를 추가하고, 예제 코드를 만들고, 차트를 수정하고, 조사 메모를 정리하는 작업은 이런 작성 브랜치에서 진행한다고 이해하면 됩니다.

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

이 구분이 있어야 Part 3에서 baseline을 바꿔 보거나 전처리를 다시 시도하고, 평가표 설명을 다듬는 중간 판단이 곧바로 공개 기준처럼 굳어지지 않습니다. 즉, 작성 중 비교와 배포해도 되는 설명을 분리하는 것이 브랜치 운영의 핵심입니다.

커밋은 배포 가능한 설명 단위가 되어야 한다¶

문서 프로젝트에서 좋은 커밋은 “파일이 바뀌었다”보다 “하나의 설명 단위가 완성되었다”에 가깝습니다.

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

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

문서 재현성은 코드 재현성보다 넓다¶

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

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

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

따라서 문서 재현성은 원고만의 문제가 아닙니다. 원고, 코드, 이미지, 조사 메모, 배포 설정이 함께 맞아야 합니다. 이 기준은 Part 3의 실험 재현성과도 바로 닿습니다. baseline을 바꾸고, 특징을 바꾸고, 평가 지표를 다시 읽을 때도 어느 시점의 코드와 설명을 비교하는가가 분명해야 하기 때문입니다.

배포 전에는 연결 관계를 확인한다¶

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

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

이 확인을 더 짧게 체크리스트로 다시 쓰면:

배포 브랜치 반영은 별도 판단이 필요하다¶

문서 프로젝트에서는 일반 작성 중인 변경을 곧바로 배포 브랜치에 반영하지 않는 편이 안전합니다. 배포 브랜치 반영은 공개 문서를 갱신하는 일로 이어질 수 있기 때문입니다.

따라서 이번 변경을 공개 문서 기준으로 반영한다는 판단이 분명할 때만 배포 브랜치 반영을 진행하는 운영 기준을 둘 수 있습니다.

반대로 작성 중인 원고 수정이나 실험 중간 정리는 기본적으로 작성 브랜치에서 진행하는 편이 안전합니다.

사례 및 예시¶

사례 1. 아직 점검 중인 원고가 배포 페이지에 올라가면 생기는 문제¶

작성자가 작성 브랜치에서 새 챕터를 정리하면서 본문, 이미지, 사이트 목차 설정을 함께 수정하고 있다고 해 보겠습니다. 아직 빌드도 다 확인하지 않았고, 내부 링크가 맞는지도 점검 중입니다.

이 상태에서 바로 배포 브랜치에 반영되면 공개 배포 페이지에는 중간 상태가 그대로 노출될 수 있습니다. 목차에는 보이지만 본문 링크가 깨질 수도 있고, 이미지 파일은 교체됐지만 설명 문단은 아직 이전 버전일 수도 있습니다. 작성 중이던 초안이 그대로 공개 문서가 되는 셈입니다.

그래서 작성 브랜치와 배포 브랜치를 나누는 일은 단순한 습관이 아니라 공개 안정성을 지키는 장치입니다. 작성 브랜치에서는 원고와 실험을 진행하고, 배포 브랜치로 옮기기 전에는 빌드, 링크, 이미지, 목차, 출처 연결을 한 번 더 확인해야 합니다.

이 사례는 문서 재현성이 왜 커밋 단위와 브랜치 운영 모두에 걸쳐 있는지를 보여 줍니다. 배포되는 책은 원고만 맞으면 되는 것이 아니라, 그 원고를 둘러싼 코드, 자산, 설정이 함께 맞아야 다시 같은 결과를 보여 줄 수 있습니다.

이 절은 Git 명령을 더 많이 외우는 절이 아니라, 앞 절들에서 만든 계산과 해석을 어떤 기준으로 남길지 정하는 절입니다.

짧은 복귀 표¶

체크리스트¶

• 브랜치는 작업 흐름을 분리하는 이름 붙은 이력이라고 설명할 수 있는가?
• 작성 브랜치와 배포 브랜치의 역할 차이를 설명할 수 있는가?
• 커밋은 파일 묶음이 아니라 의미 있는 변경 묶음이어야 한다는 점을 설명할 수 있는가?
• 한 커밋에 들어갈 파일을 변경 목적 기준으로 고를 수 있는가?
• 문서 재현성은 원고만의 문제가 아니라 코드, 이미지, 조사 메모, 배포 목차가 함께 맞아야 생긴다는 점을 설명할 수 있는가?
• 배포 브랜치 반영이 공개 배포로 이어질 수 있으므로 별도 판단이 필요하다는 점을 말할 수 있는가?
• 작성 중인 변경과 배포 가능한 변경을 분리해 관리해야 할 때 브랜치와 커밋 단위 관점을 먼저 떠올릴 수 있는가?
• 배포 전 사이트 목차 설정, 이미지, 조사 메모, 빌드를 함께 확인해야 하는 이유를 설명할 수 있는가?

출처와 참고 자료¶

• Scott Chacon and Ben Straub, Pro Git 2nd Edition: Branches in a Nutshell, Git documentation, 확인 날짜: 2026-07-20. https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell 브랜치를 커밋을 가리키는 가벼운 이동 포인터로 설명하는 기준입니다.
• Git project, git-branch Documentation, 확인 날짜: 2026-07-20. https://git-scm.com/docs/git-branch git branch가 브랜치를 나열·생성·삭제하는 명령이라는 설명의 직접 참고 자료입니다.
• GitHub Docs, What is GitHub Pages?, 확인 날짜: 2026-07-20. https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages GitHub Pages가 저장소의 HTML, CSS, JavaScript를 빌드 과정과 함께 정적 사이트로 게시할 수 있다는 설명을 확인했습니다.