sem Git 시맨틱 diff 사용 방법: 함수 단위 변경만 먼저 보기

git diff로 코드를 리뷰할 때, lines 142-160 changed 같은 줄 번호 중심의 변경 사항은 맥락을 잡기 어렵습니다. 특히 함수 이름을 바꾸거나 파일 위치를 옮기면 수백 줄이 삭제되고 추가된 것으로 보여, 무엇이 바뀌었는지 파악하느라 시간을 허비합니다.

sem은 파일의 줄(line) 대신 함수, 클래스, 메서드 같은 의미론적(semantic) 코드 엔티티를 기준으로 변경을 추적하는 Git 위(top of git)의 CLI 도구입니다.

tree-sitter를 사용해 28개 언어의 코드를 구문 분석하고 엔티티 단위로 해싱합니다. 그래서 파일 안에서 함수 위치가 바뀌거나 이름이 변경되더라도, 기존 git diff의 무의미한 줄 단위 추가/삭제 대신 "함수 A의 내부 로직 일부 수정됨"으로 맥락을 유지한 채 보여줍니다.

Git push 전 실수를 줄이는 쪽은 no-mistakes로 git push 할 때 실수 방지하기 글과 같이 보면 됩니다. 여기서는 push 차단보다 리뷰 전에 변경 내용을 읽는 방식에 초점을 둡니다.

적용 대상

• 함수 이동이나 리팩터링이 잦아 기존 git diff 리뷰에 피로감을 느끼는 환경.
• 코드 구조 기반의 의존성 분석(Impact analysis)이 필요한 경우.
• CLI 환경에서 작업하거나, LLM 기반 에이전트(MCP 지원)에 시맨틱 컨텍스트를 제공하려는 경우.
• 단순 설정 파일이나 마크다운 위주의 저장소라면 체감 효과가 크지 않습니다.

사전 준비 사항

• Linux, macOS, 또는 Windows 환경.
• 기존에 사용 중인 Git 저장소(별도의 초기 설정 없이 바로 동작).

1. 설치 방법

macOS나 Linux 환경에서는 설치 스크립트를 실행합니다.

curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh

Homebrew나 npm(node)을 이용한 설치도 가능합니다.

brew install sem-cli

# 또는 npm 설치
npm install -g @ataraxy-labs/sem

Windows PowerShell을 사용하는 경우 아래 명령을 실행합니다.

winget install AtaraxyLabs.sem

명령어 충돌 주의: GNU Parallel이 설치된 시스템의 경우 /usr/bin/sem 명령과 이름이 겹칩니다. 이런 경우 npm 래퍼(npx sem)를 사용하거나 shell profile에 alias를 지정해 경로를 우선 적용해야 합니다.

2. 시맨틱 diff 확인하기

기존 git diff를 실행하던 Git 저장소 디렉터리에서 바로 사용할 수 있습니다.

# 워킹 디렉터리의 시맨틱 변경점 확인
sem diff

# Staged 영역만 확인
sem diff --staged

결과는 줄 번호 변경이 아닌 Function authenticateUser was modified 형태로 출력됩니다. -v 플래그를 추가하시면 엔티티 내의 구체적인 변경 단어까지 인라인 강조 표시로 볼 수 있습니다.

sem diff -v

3. 의존성 및 변경 영향 분석 (Impact)

특정 함수(예: authenticateUser)를 수정했을 때, 해당 변경이 영향을 주는 다른 함수와 테스트를 파악할 수 있습니다.

# 전체 영향(Impact) 분석
sem impact authenticateUser

# 영향을 받는 테스트만 추출
sem impact authenticateUser --tests

이 기능은 수정 전에 안전성을 판단하는 지표가 됩니다. 코드베이스 전반의 연쇄적인 문제를 미리 확인하시면 됩니다.

4. 히스토리 추적 (Blame 및 Log)

기존 git blame은 파일 단위로 라인별 작성자를 보여주지만, sem blame과 sem log는 특정 엔티티의 이력을 추적합니다.

# 특정 파일 내 엔티티별 최근 수정자 확인
sem blame src/auth.ts

# 특정 함수의 변경 내역(히스토리) 추적
sem log authenticateUser -v

직접 돌려보지는 않았습니다. 공식 문서와 저장소의 실행 예제 구조를 기준으로 정리했습니다. 특히 sem log를 엔티티명 없이 실행하면 저장소 내에서 가장 자주 변경되는 핫스팟 함수나 같이 변경되는 경우가 많은 페어(co-change pairs)를 찾아주어, 아키텍처 개선 포인트를 파악하는 데 유용하다고 공식 문서에 명시되어 있습니다.

확인

설치가 완료되었는지 확인하려면 터미널에서 버전을 출력해 봅니다.

sem --version

버전 정보가 출력되면 정상적으로 설치된 것이며, 이제 Git 저장소에서 sem diff 명령으로 의미론적 변경 사항을 추적하시면 됩니다.