Git 문서를 개선하기 위해 진행한 작업—Git의 핵심 개념을 설명하는 ‘데이터 모델’ 문서 추가와 `git push`/`git pull` 등 주요 매뉴얼 페이지의 서문 및 용어 설명을 업데이트한 과정, 그리고 기여 워크플로에 대한 메모.
2026년 1월 8일
안녕하세요! 지난 가을, 저는 Git 문서를 다듬는 데 시간을 좀 쓰기로 했습니다. 오픈 소스 문서를 손보고 싶다는 생각은 오래전부터 해 왔어요. 보통은 어떤 것의 문서가 더 나아질 수 있다고 느끼면, 블로그 글이나 진(zine) 같은 걸로 제가 따로 써서 설명하곤 했거든요. 그런데 이번에는 이렇게 생각해 봤습니다. 공식 문서 자체를 조금 개선할 수는 없을까?
그래서 Marie와 저는 Git 문서에 몇 가지 변경을 만들었습니다!
문서를 작업하다 보니, Git 문서는 “object(오브젝트)”, “reference(레퍼런스)”, “index(인덱스)” 같은 용어를 아주 자주 쓰는데도, 그 용어들이 무슨 뜻인지 또는 “commit(커밋)”, “branch(브랜치)” 같은 다른 핵심 개념과 어떻게 연결되는지에 대해 만족스러운 설명이 없다는 걸 알게 됐습니다. 그래서 새로운 “데이터 모델” 문서를 작성했습니다!
일단은 여기에서 데이터 모델 문서를 읽을 수 있어요. 언젠가(다음 릴리스 이후쯤?) Git 웹사이트에도 올라갈 거라고 생각합니다.
저는 이게 정말 기대돼요. Git이 커밋과 브랜치 데이터를 어떻게 조직하는지 이해하는 건, 수년 동안 Git이 어떻게 동작하는지 논리적으로 생각하는 데 엄청 도움이 되었거든요. 그리고 정확한 데이터 모델을 짧게(1600단어!) 정리한 버전이 존재하는 건 중요하다고 생각합니다.
그 “정확함”이라는 부분이 생각보다 쉽지 않았습니다. Git 데이터 모델의 기본은 알고 있다고 생각했는데, 리뷰 과정에서 새로운 디테일을 몇 가지 배우면서 수정도 꽤 많이 해야 했어요(예를 들어 머지 충돌이 스테이징 영역에 어떻게 저장되는지 같은 것들요).
git push, git pull 등 업데이트또 Git의 핵심 man page 몇 개의 도입부(introduction)를 업데이트하는 작업도 했습니다. 그런데 금방 깨달았어요. “그냥 내 판단으로 더 낫게 고쳐보자”는 접근은 통하지 않겠더라고요. 왜 유지보수자들이 제 버전이 더 낫다고 믿어야 할까요?
오픈 소스 문서 변경을 논의할 때 자주 보는 문제가 하나 있어요. 소프트웨어를 잘 아는 사용자 두 명이 “이 설명이 명확한가?”를 두고 논쟁하는 거죠(“X로 설명하는 게 좋을 것 같아!” “아니야, Y가 더 낫지!”).
저는 이게 별로 생산적이지 않다고 생각합니다(어떤 소프트웨어의 전문가 사용자들은, 그 설명이 비전문가에게도 명확할지 판단을 잘 못하는 경우가 악명 높게 많거든요). 그래서 man page의 문제를 좀 더 근거 기반으로 찾아낼 방법이 필요했습니다.
Mastodon에서 테스트 리더를 모집해서, 현재 버전의 문서를 읽고 무엇이 혼란스러운지, 어떤 질문이 생기는지 알려달라고 했습니다. 약 80명의 테스트 리더가 코멘트를 남겨주었고, 정말 많이 배웠어요!
사람들이 엄청나게 좋은 피드백을 많이 남겨줬습니다. 예를 들면:
테스트 리더 대부분이 최소 5~10년 동안 Git을 써 온 사람들이었는데, 이게 꽤 잘 맞았던 것 같습니다. 정기적으로 Git을 5년 이상 사용해 온 사람들이 어떤 문장이나 용어를 도저히 이해할 수 없다고 말한다면, 문서를 더 명확하게 바꾸어야 한다고 주장하기가 훨씬 쉬워지니까요.
이런 “소프트웨어 사용자들에게 기존 문서에 코멘트를 달게 하고, 그들이 발견한 문제를 고치는” 패턴이 아주 잘 동작했다고 생각하고, 앞으로 다시 시도해 볼 수 있을 것 같아 기대됩니다.
저희는 결국 다음 4개의 man page를 업데이트했습니다:
git push와 git pull 변경이 저에게는 가장 흥미로웠어요. 그 페이지들의 도입부를 업데이트하는 것 외에도, 결국 다음도 작성하게 됐습니다:
이 변경들을 만들면서 오픈 소스 문서를 유지보수하는 일이 얼마나 큰 작업인지 실감하게 됐습니다. “명확하면서도 사실인” 글을 쓰는 건 쉽지 않아요. 때로는 타협이 필요하기도 했는데, 예를 들어 “push.default 설정 값에 따라, 현재 브랜치에 upstream을 설정하지 않았으면 git push가 실패할 수도 있습니다.”라는 문장은 약간 모호하긴 합니다. 하지만 여기서 ‘따라’(depending)가 정확히 무엇을 뜻하는지의 세부사항은 정말 복잡해서, 그걸 풀어내는 것만으로도 큰 프로젝트가 될 정도거든요.
Git의 개발 프로세스를 이해하는 데는 시간이 좀 걸렸습니다. 여기서 그걸 설명하려고 하진 않을게요(그것만으로도 또 다른 글이 될 수 있으니까요!). 다만 몇 가지 짧은 메모를 남기면:
또 lore.kernel.org의 메일링 리스트 아카이브는 탐색하기가 어렵다고 느꼈기 때문에, 긴 메일링 리스트 스레드를 더 쉽게 읽으려고 저만의 git 리스트 뷰어를 급히 만들어 쓰기도 했습니다.
많은 분들이 기여 과정에서 길을 찾고 변경 사항을 리뷰하는 데 도움을 주셨습니다. Emily Shaffer, Johannes Schindelin(GitGitGadget의 저자), Patrick Steinhardt, Ben Knoble, Junio Hamano, 그리고 더 많은 분들께 감사드립니다.
(지금 Mastodon 코멘트를 실험 중인데, 여기서 코멘트를 볼 수 있어요.)
이 블로그의 주간 요약을 받고 싶나요?구독하기
아카이브© Julia Evans. 이 글이 마음에 들었다면, Ulia Ea를 좋아할 수도 있고, 좀 더 진지하게는 제가 사랑하는 블로그 목록이나 제가 읽은 책 목록도 좋아할지 모릅니다.
또한 제가 가장 좋아하는 프로그래밍 커뮤니티인 Recurse Center도 마음에 들 수 있어요(관련 글들)