How Git Works by 줄리아 에반스

Git, 매일 쓰는데 아직도 무서운 적 있죠? git push가 거절당했을 때, 동료가 "리베이스해서 올려줘요"라고 했을 때, detached HEAD state 메시지가 떴을 때. 머릿속이 하얘져서 일단 폴더 통째로 지우고 새로 clone 받아본 적, 한 번쯤은 있을 거예요. 이 강의는 그런 분들을 위한 강의예요. 전 세계 개발자들이 사랑한 Julia Evans의 〈How Git Works〉, 드디어 한국어판으로 만나보세요. 명령어를 외우는 강의가 아니에요. Git이 안에서 어떻게 동작하는지를 천천히 들여다보는 강의예요. .git 폴더 안에 뭐가 들어있는지, 브랜치는 사실 어떻게 저장되는 건지, "미아가 된" 커밋은 어디로 가서 어떻게 되찾을 수 있는지, "up to date with origin/main"이 사실은 무슨 뜻인지. 총 27페이지, 6개 챕터로 구성되어 있어요. ★ 커밋(commits) ★ 브랜치(branch) ★ .git 폴더 구경하기 ★ 머지(merge) ★ 원격 저장소(remote) ★ 대재앙에서 살아남기 내부 모델 한 번만 제대로 잡고 나면, 그 다음부터는 Git이 던지는 어떤 메시지든 스스로 해석할 수 있게 돼요. 명령어를 외우는 게 아니라, "왜 이렇게 동작하는지"를 이해하면서 쓰게 되거든요. Julia가 진(zine) 첫 페이지에서 한 약속, 그대로 옮겨드릴게요 "내부 원리만 제대로 파악하면, 어떤 Git 난장판에서도 스스로 빠져나올 수 있습니다."

(5.0) 수강평 1개

수강생 53명

난이도 초급

수강기한 무제한

Byte Freaks Studio

깃

깃헙

깃허브

깃린이

깃허브커밋

깃

깃헙

깃허브

깃린이

깃허브커밋

새소식 목록

관리 작성

Byte Freaks Studio

･

수정됨

Git의 데이터 모델 (그리고 몇 가지 문서 업데이트)

안녕하세요, BFS(Byte Freaks Studio)입니다. 🎲

오늘은 줄리아 에반스가 지난 1월 자신의 블로그에 남긴 글 하나를 소개해드리려고 합니다. 바로, Git 공식 문서(documentation)를 직접 고친 이야기입니다.

Git을 쓰다 보면 한 번쯤은 object, reference, index 같은 용어 앞에서 멈칫한 적 있으실 거예요. 줄리아도 같은 지점에서 멈췄고, 결국 동료 Marie와 함께 Git의 공식 매뉴얼 페이지(man page) 몇 개를 직접 손보러 나섰습니다.

80명의 테스트 독자에게 "어디가 헷갈리는지" 피드백을 받아가며 git add, git checkout, git push, git pull 페이지를 다듬은 과정, 그리고 그 와중에 알게 된 오픈소스 문서화 작업의 의외의 어려움까지, Git 사용자라면 흥미롭게 읽으실 만한 내용입니다.

번역본은 아래에 이어집니다. 원문이 궁금하신 분들은 여기서 직접 확인하실 수 있어요.

즐겁게 읽어주세요. 🎲

Git의 데이터 모델 (그리고 몇 가지 문서 업데이트)

안녕하세요!

지난 가을, 저는 Git 문서를 개선하는 작업에 시간을 써보기로 했습니다. 보통 저는 문서가 아쉽다고 느끼게 되면 블로그 글이나 진(zine)을 따로 쓰는 방식으로 해결해 왔습니다. 그런데 이번에는 이런 생각이 들었습니다.

"공식 문서 자체를 조금 더 좋게 만들 수는 없을까?"

그래서 동료 Marie와 함께 Git 문서에 몇 가지 개선 작업을 진행했습니다.

Git을 위한 데이터 모델

Git 문서를 살펴보다 보니 Git은 object, reference, index 같은 용어를 매우 자주 사용하고 있었습니다. 하지만 이런 용어가 정확히 무엇을 의미하는지, 그리고 commit이나 branch 같은 핵심 개념과 어떤 관계를 가지는지 설명하는 자료가 부족하다는 점을 발견했습니다.

그래서 우리는 새로운 "데이터 모델(Data Model)" 문서를 작성했습니다.

지금은 여기에서 읽을 수 있으며, 다음 릴리스 이후에는 Git 공식 웹사이트에도 포함될 것으로 예상합니다.

BFS NOTE: 현재는 Git 공식 웹사이트에 반영되어 있습니다.

제가 이 작업에 특히 만족하는 이유는 Git이 커밋과 브랜치 데이터를 어떻게 구성하는지 이해하는 것이 오랫동안 Git을 이해하는 데 큰 도움이 되었기 때문입니다. 그래서 Git의 데이터 모델을 짧지만(약 1,600단어) 정확하게 설명하는 문서가 꼭 필요하다고 생각했습니다.

다만 정확하다는 것이 생각보다 쉽지 않았습니다. 기본적인 구조는 이미 알고 있었지만 리뷰 과정에서 새로운 세부 사항들을 많이 배우게 되었고, 그에 따라 여러 부분을 수정해야 했습니다. 예를 들어 머지 충돌(merge conflict)이 스테이징 영역에 어떻게 저장되는지에 대한 설명도 수정되었습니다.

git push, git pull 등을 포함한 문서 개선

또한 Git의 주요 매뉴얼 페이지(man page) 몇 개의 도입부도 개선하는 작업을 진행했습니다.

처음에는 단순히 "내가 더 낫다고 생각하는 방향으로 고쳐보자"라고 생각했지만, 곧 문제가 있다는 걸 깨달았습니다.

"내 설명이 더 좋다고 말한들, Git 메인테이너들이 그걸 믿어줄 이유가 있을까?"

오픈소스 문서 작업을 하다 보면 이런 상황을 자주 봅니다.

"이렇게 설명하는 게 더 명확하지 않을까?"
"아니, 저렇게 설명하는 게 더 좋은데?"

하지만 소프트웨어 전문가들끼리 "어떤 설명이 더 이해하기 쉬운가"를 논쟁하는 건 그다지 생산적이지 않다고 생각했습니다. 특정 도구를 오래 사용한 사람들은 초보자가 무엇을 어려워하는지 판단하기 어려운 경우가 많기 때문입니다.

그래서 우리는 조금 더 근거에 기반한 방법을 찾고 싶었습니다.

테스트 독자를 통해 문제 찾기

Mastodon에서 자원자를 모집해 기존 문서를 읽어보고 무엇이 헷갈리는지, 어떤 질문이 생기는지 알려달라고 요청했습니다.

약 80명의 테스트 독자가 의견을 남겨주었고, 그 과정에서 정말 많은 것을 배웠습니다.

사람들이 남겨준 피드백은 매우 다양했습니다.

이해하기 어려운 용어
- pathspec이 뭔가요?
- reference는 무슨 뜻인가요?
- upstream이라는 용어는 Git에서 특별한 의미가 있나요?
특정 문장이 이해하기 어렵다는 의견
추가되면 좋겠다는 내용 제안
- "저는 항상 이런 작업을 하는데 여기에 포함되면 좋겠어요."
문서 간 불일치 지적
- 한쪽에서는 X가 기본값인 것처럼 보이는데 다른 곳에서는 Y가 기본값처럼 보입니다.

흥미로웠던 점은 테스트 독자 대부분이 Git을 최소 5~10년 이상 사용한 사람들이었다는 것입니다.

이것이 오히려 좋았습니다. Git을 오랫동안 사용해 온 사람들조차 어떤 문장이나 용어를 이해하기 어렵다고 느낀다면, 문서를 더 명확하게 고쳐야 한다는 강력한 근거가 되기 때문입니다.

이런 방식, 즉

"실제 사용자가 기존 문서를 읽고 문제점을 지적하면 그 문제를 수정한다"

라는 접근법이 매우 효과적이었다고 느꼈고, 앞으로도 다른 프로젝트에서 다시 시도해 보려고 합니다.

어떤 매뉴얼 페이지를 수정했나?

우리는 다음 네 개의 매뉴얼 페이지를 수정했습니다.

git add (before, after)
git checkout (before, after)
git push (before, after)
git pull (before, after)

특히 git push와 git pull 작업이 가장 흥미로웠습니다.

도입부를 개선하는 것 외에도 다음 내용을 새롭게 작성했습니다.

upstream branch가 무엇인지 설명하는 섹션(
이전에는 사실상 제대로 설명되어 있지 않았습니다.)
push refspec에 대한 설명 정리

이 작업을 하면서 오픈소스 문서를 유지보수하는 일이 얼마나 어려운지 새삼 깨달았습니다.

"문장은 명확해야 할 뿐만 아니라 동시에 사실과도 일치해야 합니다."

때로는 절충도 필요했습니다. 예를 들어 다음 문장을 보겠습니다.

git push may fail if you haven't set an upstream for the current branch, depending on what push.default is set to.
("현재 브랜치의 upstream이 설정되지 않았다면, push.default 설정에 따라 git push가 실패할 수 있다.")

이 설명은 다소 모호합니다. 하지만 "설정에 따라"가 정확히 무엇을 의미하는지 완전히 설명하려면 훨씬 복잡한 내용을 다뤄야 하며, 그것만으로도 하나의 큰 프로젝트가 될 정도였습니다.

Git에 기여하는 과정에 대해

Git의 개발 프로세스를 이해하는 데도 꽤 시간이 걸렸습니다.

여기서 전부 설명할 생각은 없습니다. 그것만으로도 별도의 글 한 편이 될 수 있으니까요.

대신 몇 가지 짧은 메모를 남기겠습니다.

Git에는 Discord 서버가 있으며, 처음 기여하는 사람들을 위한 "my first contribution" 채널이 있습니다.
- 시작하는 데 필요한 도움을 받을 수 있었고, 모두 매우 친절했습니다.
저는 모든 기여를 GitGitGadget을 통해 진행했습니다.
- GitHub Pull Request라는 익숙한 워크플로를 사용할 수 있었고,
- GitGitGadget이 이를 Git 개발자들이 사용하는 이메일 패치 형식으로 변환해 주었습니다.
- 덕분에 이메일 패치를 보내는 방법을 새로 배울 필요가 없었습니다.
리뷰에 답변할 때는 평소 사용하는 이메일 클라이언트(Fastmail 웹 인터페이스)를 사용했습니다.
- 메일링 리스트 관례에 맞춰 텍스트를 80자 단위로 줄바꿈했습니다.

또한 lore.kernel.org의 메일링 리스트 아카이브는 탐색하기가 다소 불편했습니다. 그래서 긴 토론 스레드를 읽기 쉽도록 개인적으로 간단한 Git 메일링 리스트 뷰어를 만들어 사용했습니다.

기여 과정과 리뷰 과정에서는 많은 분들의 도움을 받았습니다. Emily Shaffer, Johannes Schindelin(GitGitGadget의 작성자), Patrick Steinhardt, Ben Knoble, Junio Hamano를 비롯한 여러 분들께 감사드립니다.

BFS

이 글에서 가장 눈에 띄었던 부분은, 줄리아가 "내가 더 잘 설명할 수 있다"는 확신만으로 문서를 고치지 않았다는 점이었습니다. 대신 실제 사용자들의 반응을 먼저 모았고, 그 데이터를 근거로 수정 방향을 정했습니다. 전문가 두 명이 "이 표현이 더 명확하다"며 논쟁하는 것보다, 실제로 헷갈려하는 사람들의 목소리를 듣는 쪽이 훨씬 신뢰할 수 있다는 거죠.

Git을 매일 쓰면서도 어딘가 석연치 않았던 표현들이 있었다면, 이 글이 그 답을 조금은 보여줄지도 모르겠습니다.

앞으로는 줄리아가 그동안 자신의 블로그에 남겨온 Git 관련 글들을 하나씩 골라 번역해서 소개해보려고 합니다. 어떤 글은 우리가 Git을 쓰며 흔히 겪는 사소한 불편함을, 또 어떤 글은 익숙하다고 생각했던 개념에 대한 오해를 다시 짚어보는 내용이에요.

《How Git Works》와 함께 보면 이해가 한층 더 깊어질 만한 글들이라, 천천히 하나씩 풀어드릴 예정이니 기대해주세요. 🎲

- BFS 🎲