안녕하세요! 지난 가을, 저는 시간을 내어 Git 문서 작업을 하기로 했습니다. 오픈소스 문서 작업을 해보고 싶다는 생각을 오랫동안 해왔습니다. 보통은 어떤 문서가 개선될 수 있겠다고 생각하면 블로그 글이나 진(zine) 같은 걸 따로 쓰곤 했습니다. 하지만 이번에는 이렇게 생각해 봤습니다. 직접 공식 문서를 조금 개선해 보면 어떨까?

그래서 Marie와 저는 Git 문서에 몇 가지 변경을 했습니다!

Git의 데이터 모델

문서 작업을 한동안 하다 보니, Git 문서 전반에서 “object”, “reference”, “index” 같은 용어가 자주 쓰이는데도 그 용어들이 정확히 무엇을 의미하는지, 그리고 “commit”이나 “branch” 같은 다른 핵심 개념과 어떻게 연결되는지에 대한 제대로 된 설명이 없다는 걸 알게 됐습니다. 그래서 저희는 새로운 “데이터 모델” 문서를 썼습니다!

지금은 여기에서 데이터 모델을 읽을 수 있습니다. 아마 언젠가(다음 릴리스 이후쯤?) Git 웹사이트에도 올라올 거라고 생각합니다.

이 작업이 특히 기대되는 이유는, Git이 커밋과 브랜치 데이터를 어떻게 구성하는지 이해하는 것이 그동안 Git의 동작을 이해하는 데 정말 큰 도움이 되었기 때문입니다. 그리고 정확하면서도 짧은(1600단어!) 데이터 모델 문서가 있다는 건 중요하다고 생각합니다.

그런데 “정확한” 문서를 만드는 일은 생각보다 쉽지 않았습니다. Git 데이터 모델이 어떻게 동작하는지 기본은 알고 있었지만, 리뷰 과정에서 새로운 세부 내용을 알게 되면서 꽤 많은 부분을 수정해야 했습니다(예를 들어 병합 충돌이 스테이징 영역에 어떻게 저장되는지 같은 부분입니다).

git push, git pull 등의 업데이트

저는 Git의 핵심 man 페이지 중 일부의 도입부를 업데이트하는 작업도 했습니다. 곧 깨달았죠. “그냥 내 판단대로 개선해 보자”는 방식으로는 안 된다는 걸요. 왜 메인테이너들이 제 버전이 더 낫다고 믿어줘야 할까요?

오픈소스 문서 변경을 논의할 때 이런 문제를 정말 자주 봤습니다. 소프트웨어에 능숙한 두 사용자가 설명이 명확한지 아닌지를 두고 논쟁하는 거죠(“X 방식으로 설명하면 좋을 것 같아요! 음, Y 방식이 더 낫지 않을까요?”).

저는 이런 방식이 그다지 생산적이지 않다고 생각합니다(소프트웨어의 숙련 사용자들은 어떤 설명이 비전문가에게 명확할지를 판단하는 데 악명 높을 정도로 서툴거든요). 그래서 man 페이지의 문제점을 조금 더 근거 있게 파악할 방법을 찾아야 했습니다.

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

저는 Mastodon에서 테스트 독자를 모집해 현재 버전의 문서를 읽고 헷갈리는 점이나 궁금한 점을 알려달라고 부탁했습니다. 약 80명의 테스트 독자가 댓글을 남겨줬고, 정말 많은 것을 배울 수 있었습니다!

사람들은 정말 훌륭한 피드백을 엄청나게 많이 남겨줬습니다. 예를 들면 다음과 같습니다.

• 이해하지 못한 용어(pathspec이 뭔가요? “reference”는 무슨 뜻인가요? “upstream”은 Git에서 특정한 의미가 있나요?)
• 헷갈리는 특정 문장
• 추가하면 좋겠다는 제안(“저는 X를 항상 하는데, 여기 포함되면 좋을 것 같아요”)
• 불일치(“여기서는 X가 기본값이라고 하는데, 다른 곳에서는 Y가 기본값이라고 하네요”)

테스트 독자 대부분은 Git을 최소 5~10년은 사용해 온 분들이었는데, 이게 정말 잘 맞아떨어졌다고 생각합니다. Git을 5년 이상 꾸준히 써온 독자 그룹조차 어떤 문장이나 용어를 도저히 이해할 수 없다고 한다면, 문서를 더 명확하게 업데이트해야 한다는 주장이 훨씬 쉬워지니까요.

“소프트웨어 사용자들이 기존 문서에 대해 의견을 남기게 한 뒤, 그들이 찾은 문제점을 고친다”는 이런 방식이 정말 잘 작동했다고 생각하고, 앞으로도 다시 시도해 보고 싶습니다.

man 페이지 변경 내용

결국 저희는 다음 4개의 man 페이지를 업데이트하게 됐습니다.

• git add (이전, 이후)
• git checkout (이전, 이후)
• git push (이전, 이후)
• git pull (이전, 이후)

git push와 git pull 변경이 저에게는 가장 흥미로웠습니다. 해당 페이지의 도입부를 업데이트하는 것 외에도, 저희는 결국 다음 내용도 작성하게 됐습니다.

• “upstream branch”라는 용어가 무엇을 의미하는지 설명하는 섹션 (이전에는 제대로 설명되지 않았던 부분입니다)
• “push refspec”이 무엇인지 정리한 설명

이런 변경 작업을 하면서 오픈소스 문서를 유지 관리하는 일이 얼마나 많은 노력을 필요로 하는지 절실히 느끼게 됐습니다. 명확하면서도 정확한 글을 쓰는 건 쉽지 않고, 때로는 타협을 해야 할 때도 있습니다. 예를 들어 “현재 브랜치에 upstream을 설정하지 않았다면 push.default 설정에 따라 git push가 실패할 수 있습니다.”라는 문장은 조금 모호하지만, “따라”가 정확히 무엇을 의미하는지에 대한 세부 내용은 정말 복잡해서 그걸 명확히 풀어내는 건 큰 작업이기 때문입니다.

Git에 기여하는 과정에 대해

Git의 개발 과정을 이해하는 데 시간이 좀 걸렸습니다. 여기서는 그 과정을 설명하려 하진 않겠습니다(그건 따로 글을 하나 써야 할 정도니까요!). 다만 몇 가지 간단히 짚고 넘어가자면:

• Git에는 기여를 시작하는 데 도움을 주는 “my first contribution” 채널이 있는 Discord 서버가 있습니다. Discord에서 사람들이 정말 친절하게 맞아주었습니다.
• 저는 모든 기여에 GitGitGadget을 사용했습니다. 덕분에 제가 익숙한 방식인 GitHub 풀 리퀘스트를 만들면 GitGitGadget이 이를 Git 개발자들이 사용하는 시스템(패치가 첨부된 이메일)으로 변환해 주었습니다. GitGitGadget은 정말 잘 동작했고, Git으로 이메일 패치를 보내는 방법을 따로 배우지 않아도 돼서 정말 다행이었습니다.
• 그 외에는 평소에 쓰는 이메일 클라이언트(Fastmail 웹 인터페이스)를 사용해 이메일에 답장했고, 메일링 리스트 관례에 따라 텍스트를 80자 단위로 줄바꿈했습니다.

또한 lore.kernel.org에 있는 메일링 리스트 아카이브는 탐색하기가 어렵게 느껴져서, 긴 메일링 리스트 스레드를 더 쉽게 읽을 수 있도록 제 나름의 git list viewer를 급하게 만들어 봤습니다.

많은 분들이 기여 과정을 헤쳐나가고 변경 내용을 리뷰하는 데 도움을 주셨습니다. Emily Shaffer, Johannes Schindelin(GitGitGadget의 저자), Patrick Steinhardt, Ben Knoble, Junio Hamano를 비롯한 모든 분께 감사드립니다.

(Mastodon 댓글 기능을 시험 중인데, 댓글은 여기에서 볼 수 있습니다)