How Git Works by 줄리아 에반스

안녕하세요, 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 🎲

" 안녕하세요!

《How Git Works》의 한국어 번역본이 출간되어 정말 기쁩니다. 저는 한국어를 읽을 수는 없지만, 번역본의 디자인과 완성도를 보며 정말 아름답게 만들어졌다고 느꼈습니다.

이 작은 진(Zine)이 여러분이 Git을 더 자신 있게 이해하고 사용할 수 있도록 도움이 되기를 바랍니다.

즐겁게 읽어주세요! "

— Julia Evans

안녕하세요. BFS(Byte Freaks Studio)입니다. 🎲
Julia의 인사말을 읽고 나니 한 가지 궁금증이 생길지도 모르겠습니다.

Julia는 왜 이 진(Zine)을 만들게 되었을까요?

Git은 전 세계 수많은 개발자가 매일 사용하는 도구이지만, 동시에 가장 많은 사람들이 어려움을 느끼는 도구이기도 합니다. Julia 역시 그 지점에 주목했고, 그 고민이 결국 《How Git Works》라는 작품으로 이어졌습니다.

아래 글은 Julia가 《How Git Works》 출간 당시 직접 작성한 블로그 포스트입니다. 이 진(Zine)이 어떤 문제의식에서 시작되었고, 무엇을 전달하고 싶었는지 더 깊이 이해할 수 있는 글이라 생각해 한국어로 함께 소개합니다.

즐겁게 읽어주세요. 🎲

안녕하세요!

몇 달 동안 이 블로그에서 Git 이야기만 계속했던 것 같은데요. 드디어 Git 진(Zine)이 완성되었습니다! 지난 금요일에 출간되었어요.

이 진(Zine)은 누구를 위한 책인가요?

이 진은 Git을 몇 년째 사용하고 있지만 여전히 Git이 두려운 사람들을 위해 썼습니다. 저는 늘 같은 생각을 합니다. 매일 업무에서 사용하는 도구를 두려워해야 한다는 건 정말 별로예요! 저는 사람들이 Git을 자신 있게 사용할 수 있었으면 좋겠습니다.

이 진의 목표는 다음과 같습니다.

• 처음에는 무섭게 느껴질 수 있는 Git의 개념들(예를 들어 "detached HEAD 상태")이 실제로는 무슨 일이 일어나고 있는지만 이해하면 꽤 단순하다는 것을 설명하기

• Git에서 특히 조심해야 할 부분들을 알려주기. 예를 들어 stash는 작업 내용을 잃어버리기 가장 쉬운 기능 중 하나이고, 한번 문제가 생기면 복구도 굉장히 성가롭습니다. 그래서 저는 stash를 많이 사용하지 않는 편입니다.

• 커밋(commit), 브랜치(branch), 머지(merge) 같은 Git의 핵심 개념에 대해 널리 퍼져 있는 오해를 바로잡기

도대체 Git은 뭐가 그렇게 헷갈리는 걸까요?

이 진을 쓰는 일은 생각보다 정말 어려웠습니다. 글을 쓰기 시작했을 때 저는 이미 10년 동안 꽤 자신 있게 Git을 사용하고 있었거든요. 그래서 Git 때문에 고생하던 시절이 어땠는지 거의 기억나지 않았습니다.

하지만 Marie와 Mastodon에서 Git에 대해 이야기를 나눠준 많은 분들의 도움 덕분에, 결국 저는 Git에 직관적이지 않거나, 오해를 부르거나, 혹은 그냥 단순히 헷갈리는 부분이 정말 많다는 사실을 다시 보게 되었습니다.

예를 들면 이런 것들입니다.

• 헷갈리는 용어들 ("fast-forward", "reference", "remote-tracking branch" 같은 표현들)

• 오해를 부르는 메시지들 (예를 들어 Your branch is up to date with 'origin/main'이라는 메시지가 반드시 원격 저장소의 main 브랜치와 실제로 동기화되어 있다는 뜻은 아닙니다)

• 충분한 정보를 주지 않는 출력 결과들 (예를 들어 저는 지금도 머지 충돌을 보고 있을 때 어떤 코드가 어느 브랜치에서 왔는지 한 번에 파악하지 못하는 경우가 있습니다)

• 브랜치가 서로 갈라진(diverged) 상황에 대한 부족한 안내 (예를 들어 git pull을 실행했는데 로컬 브랜치와 원격 브랜치가 갈라져 있는 경우, Git은 이 상황을 어떻게 처리해야 하는지 그다지 친절하게 설명해 주지 않습니다)

• 일관성 없는 동작들 (예를 들어 reflog는 거의 항상 기록만 추가되는 방식으로 동작하지만, stash만은 예외입니다. git stash drop을 실행하면 기존 항목이 실제로 삭제됩니다)

사람들이 Git을 얼마나 혼란스럽게 느끼는지에 대한 이야기를 들으면 들을수록, Git은 단순히 사용해 보기만 해서는 그 내부 논리를 이해하기 쉽지 않은 도구라는 사실이 점점 더 분명해졌습니다.

Git의 이상한 점들도 결국 익숙해집니다

지금까지의 내용을 읽다 보면 Git이 정말 형편없는 도구처럼 들릴 수도 있겠습니다. "도대체 누가 이런 걸 쓰는 거지?" 싶을 정도로요.

그런데 제 경험은 조금 다릅니다. Git이 내뱉는 이상한 에러 메시지들이 실제로 무엇을 의미하는지 이해하고 나니, 대부분의 상황은 꽤 일상적인 일이 되었습니다.

예를 들어 다음과 같은 에러를 만났다고 해봅시다.

failed to push some refs to 'github.com/wizard-zines-site'

그러면 저는 "아, 마지막으로 git pull을 한 뒤에 누군가 main 브랜치에 변경 사항을 올렸나 보네"라고 생각합니다. 그리고 git pull --rebase를 실행해 변경 사항을 가져온 뒤 다시 하던 일을 계속합니다. 보통 10초 정도면 끝나는 일입니다.

또는 다음과 같은 경고를 볼 수도 있습니다.

You are in 'detached HEAD' state

그럴 때는 단순히 코드를 계속 작성하기 전에 git checkout mybranch를 실행하면 됩니다. 큰 문제는 아닙니다.

저에게도, 그리고 Git에 대해 이야기를 나누는 많은 사람들에게도, Git 특유의 이상한 표현들은 너무 익숙해진 나머지 왜 누군가가 그것을 어렵게 느끼는지조차 잊어버릴 정도가 되곤 합니다.

Git 내부 구조는 얼마나 깊게 다뤄야 할까?

이 진(Zine)을 쓰면서 가장 많이 고민했던 것 중 하나는 .git 디렉터리 내부를 어디까지 설명해야 하느냐였습니다.

결국 우리는 Git 내부 구조를 다루는 페이지(".git 폴더 구경하기")를 포함하기로 했지만, 전체적으로는 Git을 사용할 때 실제로 보게 되는 동작과 Git이 가끔 예상 밖의 행동을 하는 이유에 더 집중하기로 했습니다.

그 이유는 두 가지입니다.

하나는 이미 Git 내부 구조를 설명하는 훌륭한 자료들이 많이 존재하기 때문입니다.

그리고 또 하나는, 그런 자료를 읽었다고 하더라도 그것이 Git 사용자 인터페이스에서 실제로 보이는 현상과 어떻게 연결되는지 이해하는 것은 생각보다 쉽지 않다고 느꼈기 때문입니다.

예를 들어 Git의 원격 저장소(remote)에 관한 설명은 쉽게 찾을 수 있습니다. 어떤 문서에서는 다음과 같이 설명합니다.

Remote-tracking branches [...] remind you where the branches in your remote repositories were the last time you connected to them.

하지만 이 설명을 읽었다고 해서 git status에 표시되는 다음 메시지가

Your branch is up to date with 'origin/main'

반드시 원격 저장소의 main 브랜치와 완전히 동기화되어 있다는 뜻이 아니라는 사실까지 자연스럽게 이해할 수 있는 것은 아닙니다.

그래서 이 진에서는 Git의 내부 구조를 먼저 설명하기보다, 여러분이 Git을 사용하면서 실제로 마주치는 동작들에 초점을 맞추고, 그런 동작들이 Git 내부에서는 어떤 원리로 이루어지는지를 함께 설명하려고 했습니다.

사실 저는 Git을 정말 좋아합니다

이 글에서는 Git에 대해 꽤 비판적인 이야기를 많이 했습니다. 하지만 저는 제가 좋아하는 기술에 대해서만 진(Zine)을 씁니다. Git도 예외는 아닙니다.

제가 Git을 좋아하는 이유는 여러 가지가 있습니다.

• 빠릅니다!

• 하위 호환성이 뛰어납니다. 10년 전에 배운 Git 지식이 지금도 거의 그대로 유효합니다.

• 무료로 사용할 수 있는 훌륭한 Git 호스팅 서비스가 정말 많습니다. (GitHub! GitLab! 그리고 그 밖에도 아주 많이요!) 덕분에 제 코드를 쉽게 백업할 수 있습니다.

• 단순한 워크플로는 정말 단순합니다. 혼자 프로젝트를 진행할 때는 git commit -am 'whatever'와 git push만 반복해도 대부분 아주 잘 동작합니다.

• Git 내부 파일 대부분은 꽤 단순한 텍스트 파일입니다. (또는 텍스트 형태로 볼 수 있는 버전이 있습니다.) 그래서 필요하다면 내부에서 무슨 일이 일어나고 있는지 언제든 이해할 수 있을 것 같은 느낌을 줍니다.

이 진(Zine)이 여러분도 Git을 좋아하게 되는 데 조금이나마 도움이 되었으면 좋겠습니다.

이 진(Zine)을 만드는 데 도움을 준 사람들

저는 이 진(Zine)들을 혼자 만들지 않습니다!

저는 8개월 동안 매일 아침 Marie Claire LeBlanc Flanagan과 함께 Git을 더 명확하게 설명하는 방법을 고민하며 작업했습니다. 표지는 Vladimir Kašiković가 작업했고, Gersande La Flèche가 교정을 맡았습니다. 《Building Git》의 저자인 James Coglan은 기술 검토를 해주었고, 운영 매니저인 Lee는 텍스트 전사 작업뿐 아니라 셀 수 없이 많은 일들을 도와주었습니다. 제 파트너 Kamal은 언제나 그렇듯 초고를 읽고 어색한 부분을 알려주었고, Marco Rogers와도 Git에 대해 정말 많은 좋은 대화를 나눴습니다.

마지막으로 베타 리더 여러분께도 감사의 말씀을 전하고 싶습니다. 이번에는 무려 66명의 베타 리더가 참여했는데, 이는 지금까지 가장 많은 인원이었습니다! 그들은 무엇이 헷갈렸는지, 무엇을 새롭게 배웠는지, 그리고 제 농담 중 어떤 것이 재미있었는지에 대해 수백 개의 의견을 남겨주었습니다.

제가 명확하게 설명했다고 생각했던 페이지가 사실은 굉장히 혼란스럽다는 이야기를 듣는 일은 언제나 쉽지 않습니다. 하지만 그런 문제들을 최종 출간 전에 발견하고 수정할 수 있었기에, 이 진은 훨씬 더 좋은 결과물이 될 수 있었습니다.

감사합니다

언제나 그렇듯, 그동안 제 진(Zine)을 구매해 주셨던 모든 분들께 진심으로 감사드립니다. 여러분의 꾸준한 응원 덕분에 여기까지 올 수 있었습니다.

그리고 출간 후 단 3일 만에 이 진을 구매해 주신 1,000명이 넘는 분들께도 감사드립니다!!!

덕분에 이 진은 Wizard Zines 역사상 하루 동안 가장 많이 판매된 진이라는 기록을 세웠습니다. 정말 놀랍고, 큰 감동을 받았습니다.

BFS(Byte Freaks Studio)

Julia의 글 잘 읽으셨나요?

이 글에서 가장 인상 깊었던 점은, Julia가 Git의 불편함을 단순히 비판하는 데서 멈추지 않았다는 점이었습니다. Git은 어렵습니다. 때로는 이상하고, 어떤 메시지는 이해하기 어렵고, 어떤 동작은 직관적이지 않습니다. 하지만 Julia는 "Git은 왜 이럴까?"라는 질문을 던졌습니다. 그리고 Git을 이해하기 어려운 이유를 차근차근 분석하고 설명하려고 했습니다.

또 한 가지 인상 깊었던 점은 Git 학습 자료에 대한 시각이었습니다.

이미 시중에는 Git의 내부 구조를 설명하는 훌륭한 자료들이 많이 존재합니다. 하지만 그런 자료를 읽고 나서도 막상 터미널에서 Git을 사용하다 보면 "그래서 지금 Git이 왜 이런 행동을 하는 거지?"라는 질문이 남는 경우가 많습니다.

Git의 내부 원리와 실제 사용자가 마주하는 사용자 인터페이스 사이에는 생각보다 큰 간격이 존재합니다. 아마 많은 분들이 비슷한 경험을 해보셨을 것입니다. Git 관련 두꺼운 책을 일부 읽고 나면 이해한 것 같은데, 정작 실제 작업 중 에러 메시지를 만나면 다시 당황하게 되는 경험 말입니다.

저희는 Julia가 바로 그 간격을 정확하게 짚어냈다는 점을 높게 평가했습니다. 무엇보다 이 문장이 특히 공감되었습니다.

You are in 'detached HEAD' state

개발자라면 한 번쯤은 이 메시지를 보고 멈칫해 본 적이 있을 것입니다.

"이게 무슨 뜻이지?" "지금 뭘 해야 하지?" "잘못 건드리면 뭔가 망가지는 거 아닐까?"

저 역시 여러분과 비슷한 고민을 해왔습니다. 그래서 이 책은 Git의 모든 것을 설명하려는 책이라기보다, Git이 왜 그런 행동을 하는지 이해하도록 돕는 책에 가깝다고 느꼈습니다.

그리고 그 이해가 쌓일수록 Git은 조금 덜 낯설고, 조금 덜 두려운 도구가 됩니다. 여러분도 《How Git Works》를 통해 Git을 조금 더 이해하고, Git을 조금 덜 두려워하게 되기를 바랍니다.

— BFS 🎲