코드를 읽기 전에 먼저 치는 Git 명령어들 — 낯선 코드베이스를 빠르게 파악하는 법

새 프로젝트에 투입됐을 때, 코드부터 열지 마세요

새로운 팀에 합류하거나 오픈소스 프로젝트에 기여하려고 할 때, 가장 먼저 하는 일이 뭔가요? 대부분 README를 읽거나 src/ 폴더를 열어보죠. 그런데 그 전에 Git 명령어 몇 개만 먼저 쳐보면, 이 프로젝트의 "성격"을 훨씬 빠르게 파악할 수 있어요.

개발자 Adam Piechowski가 공유한 이 접근법이 꽤 실용적인데요, 코드를 한 줄도 읽기 전에 Git 히스토리만으로 프로젝트의 구조, 활발한 영역, 핵심 기여자를 파악하는 방법이에요. 단순한 팁 모음이 아니라, 낯선 코드베이스를 체계적으로 이해하는 하나의 워크플로우라고 보면 돼요.

핵심 명령어들, 하나씩 뜯어볼게요

1. git log --oneline --graph --all

가장 먼저 치는 명령어예요. 이게 뭐냐면, 프로젝트의 전체 커밋 히스토리를 한눈에 보여주는 거예요. --graph 옵션을 붙이면 브랜치가 어떻게 갈라지고 합쳐졌는지 시각적으로 보이거든요. 마치 지하철 노선도를 보는 것처럼요.

이걸 보면 프로젝트가 어떤 브랜치 전략을 쓰는지 바로 알 수 있어요. main 하나로만 가는 프로젝트인지, feature 브랜치를 열심히 따는 프로젝트인지, release 브랜치를 따로 관리하는지. 이게 팀의 개발 문화를 보여주는 첫 번째 단서예요.

2. git shortlog -sn

이건 누가 얼마나 커밋했는지를 순서대로 보여줘요. 프로젝트의 핵심 기여자가 누구인지 바로 파악이 되죠. 특히 오픈소스 프로젝트에서 이걸 먼저 보면, 나중에 코드 리뷰를 요청하거나 질문할 사람을 금방 찾을 수 있어요. 사내 프로젝트에서도 마찬가지인데, 어떤 모듈에 대해 가장 잘 아는 사람이 누군지 커밋 수가 알려주거든요.

3. git log --diff-filter=A --summary

이건 파일이 처음 추가된 시점을 추적하는 명령어예요. --diff-filter=A에서 A가 "Added"를 의미해요. 프로젝트가 시간순으로 어떻게 구조가 잡혀갔는지 볼 수 있어서, 아키텍처의 진화 과정을 역추적할 수 있어요.

4. git log -- [특정 파일 경로]

특정 파일이나 디렉토리의 변경 이력만 따로 볼 수 있어요. 예를 들어 git log -- src/auth/ 이렇게 치면 인증 관련 코드가 언제, 왜 바뀌었는지 커밋 메시지를 통해 알 수 있죠. 코드의 "왜"를 이해하는 데 커밋 메시지만큼 좋은 자료가 없어요.

5. git log --since="2 weeks ago" --oneline

최근 활동을 보는 명령어예요. 프로젝트가 활발한지, 어떤 영역에서 작업이 집중되고 있는지 알 수 있어요. 만약 최근 2주간 커밋이 없다면, 프로젝트가 안정기에 있거나 혹은 유지보수가 안 되고 있다는 신호일 수도 있고요.

왜 코드보다 히스토리를 먼저 봐야 할까

코드는 "현재 상태"만 보여줘요. 하지만 Git 히스토리는 "맥락"을 보여줘요. 왜 이 구조가 됐는지, 최근에 어떤 부분이 자주 바뀌는지, 누가 이 코드를 가장 잘 아는지. 이런 맥락 없이 코드만 읽으면, 겉모습만 보고 판단하는 셈이에요.

특히 자주 변경되는 파일을 찾는 게 중요한데요, git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -20 이런 식으로 가장 많이 수정된 파일 Top 20을 뽑아볼 수 있어요. 자주 바뀌는 파일은 보통 버그가 많거나 비즈니스 로직의 핵심이거나 둘 중 하나거든요. 어느 쪽이든 가장 먼저 이해해야 할 파일이에요.

비슷한 도구들도 있어요

Git 명령어를 직접 치는 게 불편하다면, GUI 도구를 활용할 수도 있어요. GitLens(VS Code 확장), GitHub의 Insights 탭, git-quick-stats 같은 도구들이 비슷한 정보를 시각적으로 보여주죠. 하지만 CLI 명령어를 알고 있으면 어떤 환경에서든 바로 쓸 수 있다는 장점이 있어요. SSH로 서버에 접속해서 코드를 봐야 할 때, GUI가 없잖아요.

최근에는 AI 기반 코드 분석 도구들 — Sourcegraph, CodeScene 같은 — 도 커밋 히스토리 분석을 자동화해주고 있어요. CodeScene은 특히 "핫스팟 분석"이라는 걸 해주는데, 자주 변경되면서 복잡도가 높은 파일을 자동으로 찾아줘요. 하지만 이런 도구들을 쓰더라도 기본적인 Git 명령어를 이해하고 있어야 결과를 제대로 해석할 수 있어요.

한국 개발자에게 주는 시사점

이 워크플로우는 당장 내일부터 쓸 수 있어요. 특히 이런 상황에서 유용해요.

첫째, 새 회사나 팀에 온보딩할 때. 한국 IT 업계는 이직이 활발한 편이잖아요. 새 프로젝트에 투입될 때마다 이 명령어들을 루틴으로 돌려보면, 문서화가 부족한 프로젝트에서도 맥락을 빠르게 잡을 수 있어요.

둘째, 레거시 코드를 인수인계 받을 때. 전임자가 퇴사하고 문서도 없는 상황, 한국 개발자라면 한 번쯤 겪어봤을 거예요. Git 히스토리가 유일한 문서인 경우가 많거든요.

셋째, 코드 리뷰할 때. PR을 리뷰하기 전에 해당 파일의 히스토리를 먼저 보면, 이 변경이 기존 맥락에 맞는지 더 잘 판단할 수 있어요.

한 가지 더 팁을 드리면, 이 명령어들을 shell alias로 등록해두면 편해요. .zshrc나 .bashrc에 alias gstat='git shortlog -sn' 이런 식으로 넣어두면, 프로젝트를 클론하자마자 습관처럼 쓸 수 있거든요.

마무리

코드를 잘 읽는 개발자는 코드부터 열지 않아요. Git 히스토리라는 "지도"를 먼저 펼쳐보고, 어디를 봐야 할지 감을 잡은 다음에 코드를 읽어요.

여러분은 새 프로젝트에 합류하면 가장 먼저 뭘 하시나요? 나만의 온보딩 루틴이 있다면 공유해주세요!