Admin 패널에 Git 브랜치 뷰어를 만든 이유

GitHub만으로는 부족했습니다

개인 블로그를 모노레포로 운영하면서 브랜치가 꽤 많이 쌓였습니다. 기능별로 브랜치를 따서 작업하고, 머지하고, 또 새 브랜치를 만들고. 그런데 문제는 머지 후 삭제하지 않은 브랜치가 로컬과 원격 모두에 방치되고 있다는 것이었습니다.

GitHub에 들어가면 원격 브랜치 목록은 볼 수 있습니다. 하지만 GitHub이 보여주는 건 push된 상태뿐입니다. 로컬에만 있는 브랜치, 지금 체크아웃된 브랜치, 그리고 git worktree로 병렬 작업 중인 디렉토리 정보는 GitHub에서 확인할 방법이 없습니다.

터미널에서 git branch -a를 치면 되긴 합니다. 하지만 Admin 패널에서 글을 쓰다가 "지금 어떤 브랜치에서 작업 중이지?"를 확인하려고 매번 터미널로 전환하는 건 번거로운 일이었습니다.

만들게 된 구체적인 이유

계기는 두 가지였습니다.

첫째, 방치된 브랜치 정리가 필요했습니다. feat/hybrid-search, feat/tiptap-editor 같은 브랜치들이 이미 main에 머지된 뒤에도 원격에 그대로 남아 있었습니다. 로컬에도 마찬가지였습니다. 어떤 브랜치가 아직 살아있는 작업이고 어떤 브랜치가 정리 대상인지, 마지막 커밋 날짜를 보면 바로 판단할 수 있을 것이라 생각했습니다.

둘째, worktree를 활용한 병렬 작업 현황 파악이었습니다. git worktree를 사용하면 하나의 레포에서 여러 브랜치를 동시에 체크아웃할 수 있습니다. 다만 "지금 어떤 worktree에서 어떤 브랜치가 작업 중인지"를 한눈에 보려면 git worktree list를 쳐야 하는데, 이것도 웹에서 바로 확인할 수 있으면 편하겠다는 생각이 들었습니다.

GitHub과의 차이점

정리하면 이런 차이가 있습니다.

항목	GitHub	Admin Git Info
push 안 한 로컬 브랜치	볼 수 없음	표시됨
현재 체크아웃된 브랜치	알 수 없음	current 표시
git worktree 목록	개념 자체가 없음	경로/브랜치 표시
로컬 커밋 상태	push 후에만 반영	즉시 반영
마지막 커밋 날짜	브랜치 페이지에서 확인	한 화면에 모두 표시

핵심은 GitHub이 "원격 저장소의 상태"를 보여주는 반면, 이 페이지는 "개발 머신의 실시간 상태"를 보여준다는 점입니다.

웹브라우저에서 git 정보를 조회하는 원리

브라우저에서는 직접 파일 시스템에 접근하거나 git 명령을 실행할 수 없습니다. 보안상 당연한 제약입니다. 그래서 백엔드 서버가 중간 다리 역할을 합니다.

브라우저 (React)
    ↓ HTTP GET /admin/git/info
NestJS 백엔드
    ↓ child_process.execFile('git', [...])
로컬 git CLI 실행
    ↓ stdout 파싱
JSON 응답으로 반환
    ↓
브라우저에서 테이블 렌더링

Node.js의 child_process.execFile을 사용하면 서버에서 시스템 명령어를 실행할 수 있습니다. exec 대신 execFile을 쓴 이유는 shell injection 방지 때문입니다. exec는 셸을 통해 명령을 실행하므로 인자에 ; rm -rf / 같은 것이 들어갈 수 있지만, execFile은 인자를 배열로 전달하기 때문에 이런 위험이 없습니다.

로컬 브랜치 조회

git의 --format 옵션을 활용하면 원하는 정보만 깔끔하게 추출할 수 있습니다.

git branch --format='%(HEAD)\x1f%(refname:short)\x1f%(objectname:short)\x1f%(subject)\x1f%(creatordate:relative)'

각 필드의 의미는 이렇습니다.

• %(HEAD) — 현재 브랜치면 *, 아니면 공백
• %(refname:short) — 브랜치 이름 (예: main)
• %(objectname:short) — 마지막 커밋 해시 (예: 265a515)
• %(subject) — 커밋 메시지
• %(creatordate:relative) — 상대 시간 (예: 2 days ago)

구분자로 \x1f(Unit Separator)를 사용했습니다. 커밋 메시지에 |나 ,가 포함될 수 있기 때문에, ASCII 제어 문자를 구분자로 쓰면 파싱이 깨지지 않습니다.

원격 브랜치 조회

원격 브랜치도 동일한 방식입니다. -r 플래그만 추가하면 됩니다.

git branch -r --format='%(refname:short)\x1f%(objectname:short)\x1f%(subject)\x1f%(creatordate:relative)'

다만 이 정보는 마지막 git fetch 시점의 스냅샷이라는 점을 알아두어야 합니다. 원격 브랜치의 실제 최신 상태를 보려면 먼저 git fetch를 실행해야 합니다.

Worktree 목록 조회

git worktree list --porcelain

--porcelain 옵션을 붙이면 프로그램에서 처리하기 쉬운 고정된 텍스트 형식으로 출력됩니다. 각 worktree마다 경로, HEAD 커밋, 브랜치 정보가 한 블록으로 나옵니다.

서비스 초기화 시 레포 루트 탐지

한 가지 주의할 점이 있었습니다. NestJS가 실행되는 process.cwd()가 반드시 git 레포의 루트 디렉토리와 같지 않을 수 있습니다. 모노레포 구조상 백엔드 패키지 디렉토리에서 실행될 수도 있기 때문입니다.

그래서 서비스 초기화 시 git rev-parse --show-toplevel을 실행해서 실제 레포 루트 경로를 한 번 찾아두고, 이후 모든 git 명령에 이 경로를 cwd로 전달하는 방식을 사용했습니다.

async onModuleInit() {
  const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
    timeout: 5000,
  });
  this.repoRoot = stdout.trim();
}

프론트엔드 구현

프론트엔드는 기존 Admin 패널의 패턴을 그대로 따랐습니다. React Query의 useQuery 훅으로 데이터를 가져오고, 테이블 형태로 렌더링합니다. staleTime을 60초로 설정해서 불필요한 재요청을 줄였고, 수동 새로고침 버튼도 추가했습니다.

페이지는 세 섹션으로 나눠집니다.

• 로컬 브랜치 — 현재 브랜치는 초록색으로 하이라이트, 각 브랜치의 마지막 커밋 정보 표시
• 원격 브랜치 — 브랜치명과 마지막 커밋 해시, 메시지, 날짜 표시
• Worktrees — 각 worktree의 경로, 브랜치, HEAD 해시 표시

보안 고려사항

이 기능은 Admin 패널에서만 접근 가능합니다. NestJS의 JwtAuthGuard와 RolesGuard를 통해 admin 역할을 가진 사용자만 호출할 수 있도록 했습니다. 그리고 이 Admin 패널 자체가 로컬에서만 실행되는 도구이기 때문에, 외부에서 접근할 수 있는 경로는 없습니다.

execFile을 사용해서 shell injection을 방지한 것도 중요한 부분입니다. 읽기 전용 git 명령만 실행하고, 사용자 입력이 git 명령 인자에 포함될 여지가 없습니다.

돌이켜 생각해보면

사실 터미널에서 git branch -a 한 줄이면 되는 일이긴 합니다. 하지만 Admin 패널에서 글을 쓰다가 컨텍스트 전환 없이 바로 확인할 수 있다는 건, 생각보다 편한 경험이었습니다.

특히 원격 브랜치의 마지막 커밋 날짜를 한눈에 볼 수 있으니, "이 브랜치는 3개월 전이 마지막이네, 정리해야겠다"는 판단을 빠르게 내릴 수 있게 되었습니다. 작은 도구지만, 로컬 개발 환경의 상태를 시각적으로 파악할 수 있다는 점에서 나름 유의미한 작업이었다는 생각이 듭니다.