Repomix의 옵션은 매우 다양하지만, 목적에 따라 분류하면 체계가 보입니다. 이 편은 매번 공식 문서를 뒤적이지 않고도 빠르게 원하는 설정을 적용할 수 있도록 정리한 CLI 옵션 참고서입니다.

가장 먼저 이해해야 할 것은 개별 옵션이 아니라, 여러 설정이 충돌할 때 적용되는 우선순위입니다.

옵션 우선순위: 무엇이 먼저 적용되는가

같은 항목에 대해 명령줄 옵션과 설정 파일에 각각 다른 값이 적혀 있다면, 명령줄 옵션이 최우선입니다.

우선순위: 명령줄 옵션 $\rightarrow$ 로컬 설정 파일 $\rightarrow$ 전역 설정 파일

따라서 팀 전체가 공유해야 할 기본값은 설정 파일에 정의하고, 특정 실행에서만 잠깐 바꿀 옵션은 명령줄 플래그로 제어하는 방식이 가장 효율적입니다.

참고로, 출력 파일 경로(-o)에 "-"를 지정하면 파일을 생성하지 않고 표준 출력(stdout)으로 내용을 내보냅니다. 이는 --stdout 플래그와 동일한 동작입니다.

입출력 방향 제어

옵션	동작 설명
-o, --output <file>	결과물을 저장할 파일 경로. (기본값: repomix-output.xml)
--stdout	파일 생성 없이 표준 출력으로 바로 내보냅니다.
--stdin	표준 입력(stdin)으로부터 파일 경로 목록을 한 줄씩 받습니다.
--copy	생성된 결과물을 시스템 클립보드에 즉시 복사합니다.
--verbose	처리 과정, 토큰 수, 적용된 설정 등 상세 로그를 출력합니다.
--quiet	오류 메시지를 제외한 모든 콘솔 출력을 억제합니다. (자동화 스크립트용)
--top-files-len <number>	파일 요약 블록에 표시할 최대 파일 수. (기본값: 5)
-v, --version	설치된 Repomix의 버전 정보를 확인합니다.

특히 --stdin 옵션은 find, git ls-files, rg 같은 강력한 셸 도구와 조합할 때 진가를 발휘합니다.

# src 폴더 내의 모든 .ts 파일만 골라 묶기
find src -name "*.ts" -type f | repomix --stdin

# Git이 추적 중인 .ts 파일만 묶기
git ls-files "*.ts" | repomix --stdin

# ripgrep으로 특정 키워드가 포함된 파일만 골라 묶기
rg -l "TODO|FIXME" --type ts | repomix --stdin

# fzf로 대화형으로 파일을 선택해 묶기
fzf -m | repomix --stdin

주의: --stdin으로 파일을 지정하더라도, Repomix의 무시 규칙은 여전히 작동합니다. 지정된 파일이 .gitignore나 기본 무시 패턴에 걸린다면 결과물에서 제외됩니다.

출력 모양과 구성 제어

옵션	동작 설명
--style <style>	출력 포맷 선택: xml(기본), markdown, json, plain
--output-file-path-style <style>	경로 표기 방식: target-relative(기본), cwd-relative
--parsable-style	특수문자를 이스케이프 처리하여 포맷 파손 방지 (토큰 사용량 증가)
--compress	Tree-sitter 기반으로 클래스, 함수 등 주요 구조만 남기고 압축
--output-show-line-numbers	각 줄에 줄 번호를 표시 (AI가 정확한 위치를 지칭하게 할 때 유용)
--no-file-summary	파일 요약 블록 제외
--no-directory-structure	디렉터리 트리 블록 제외
--no-files	파일 본문은 제외하고 메타데이터와 구조만 생성
--remove-comments	코드 내 주석 제거
--remove-empty-lines	불필요한 빈 줄 제거
--truncate-base64	긴 base64 문자열을 잘라 토큰 절약
--header-text <text>	출력 파일 최상단에 사용자 지정 문구 삽입
--instruction-file-path <path>	AI에게 줄 지침이 담긴 파일 경로 지정
--split-output <size>	출력 파일을 지정한 크기(1mb, 20mb 등)로 분할 생성
--include-empty-directories	빈 폴더도 구조 트리에 표시
--include-full-directory-structure	--include로 범위를 좁혀도 트리 구조는 전체를 표시

꿀팁: --split-output은 대형 저장소를 다룰 때 필수적입니다. Google AI Studio 같은 서비스의 파일 업로드 제한(예: 1MB)을 넘을 경우, 파일을 나누어 업로드해야 합니다. 이때 Repomix는 최상위 디렉터리 단위로 분할하여, 하나의 폴더가 두 파일에 걸쳐 찢어지지 않도록 세심하게 처리합니다.

파일 선택 및 필터링

옵션	동작 설명
--include <patterns>	포함할 파일 패턴. 쉼표로 구분하여 지정 (예: "src/**/*.js,*.md")
-i, --ignore <patterns>	추가로 제외할 패턴 지정 (예: "*.test.js,docs/**")
--no-gitignore	.gitignore 규칙을 무시하고 모든 파일을 대상으로 함
--no-dot-ignore	.ignore 규칙을 무시함
--no-default-patterns	Repomix 내장 기본 무시 패턴(node_modules 등)을 적용하지 않음

🚨 결정적 오해 방지: --include는 "강제 포함"이 아닙니다. 많은 사용자가 --include를 쓰면 무시 규칙을 무시하고 무조건 포함된다고 생각하지만, 사실은 "후보군을 좁히는 필터"일 뿐입니다. 필터링 된 후에도 무시 규칙(ignore)은 여전히 적용됩니다.

만약 node_modules 안의 특정 파일을 꼭 넣어야 한다면, --include와 함께 --no-default-patterns나 --no-gitignore 옵션을 사용하여 무시 규칙 자체를 꺼야 합니다. (다만, 의존성 파일을 무분별하게 포함하면 토큰 낭비가 심하므로 주의하세요.)

Git 컨텍스트 활용

옵션	동작 설명
--include-diffs	현재 작업 트리와 스테이징 영역의 변경 사항(diff)을 추가
--include-logs	커밋 날짜, 메시지, 변경 파일 목록을 추가
--include-logs-count <count>	포함할 최근 커밋 수 (기본값: 50)
--no-git-sort-by-changes	변경 빈도 기반의 파일 정렬 기능을 끔

버그 수정이나 코드 리뷰 요청 시 --include-diffs를 사용해 보세요. "어떤 코드가 바뀌었는지"와 "전체 구조"가 한 파일에 담기므로, AI가 변경의 의도와 영향 범위를 훨씬 정확하게 분석할 수 있습니다.

토큰 관리 및 최적화

옵션	동작 설명
--token-count-tree [threshold]	디렉터리별 토큰 사용량을 트리 형태로 표시. 선택 값 이상만 표시
--token-count-encoding <encoding>	토큰 계산 인코더 설정. (o200k_base $\rightarrow$ GPT-4o / cl100k_base $\rightarrow$ GPT-4)
--token-budget <number>	출력물이 설정한 토큰 수를 초과하면 에러 코드로 실패 알림 (CI용 안전장치)

--token-budget은 자동화 파이프라인(CI/CD)에서 매우 유용합니다. 특정 모델의 컨텍스트 창을 초과하여 결과가 잘리는 사고를 방지하고, 자동으로 빌드를 실패시켜 운영자가 인지하게 만들 수 있습니다.

기타 특수 옵션

상세 내용은 각 전용 가이드에서 다루며, 여기서는 조합 제한 사항만 정리합니다.

그룹	주요 옵션	관련 가이드
원격 저장소	--remote, --remote-branch, --remote-trust-config	원격 저장소 편
설정 관리	-c, --config, --init, --global	설정 파일 편
보안 검사	--no-security-check	보안 편
MCP 서버	--mcp, --sandbox	MCP 서버 편
에이전트 스킬	--skill-generate, --skill-output, --force	에이전트 연동 편
워치 모드	-w, --watch	워치 모드 편

보안 경고: --remote-trust-config는 원격 저장소의 설정 파일을 신뢰하여 실행하겠다는 뜻입니다. 설정 파일은 실행 가능한 코드를 포함할 수 있으므로, 신뢰할 수 없는 저장소를 대상으로 할 때는 절대 사용하지 마세요.

실무 활용 조합 예제

자주 쓰이는 옵션 조합을 상황별로 정리했습니다.

# 1. 가장 기본: 현재 폴더를 빠르게 묶기
repomix

# 2. 파일명과 포맷을 지정해 마크다운으로 저장
repomix -o my-output.md --style markdown

# 3. 표준 출력으로 내보내어 AI CLI 도구로 바로 전달
repomix --stdout | llm "이 코드의 구조를 분석하고 리팩터링 포인트를 알려줘."

# 4. 대형 저장소: 압축하고 20MB 단위로 분할 저장
repomix --compress --split-output 20mb

# 5. 특정 영역만 정밀하게 묶기 (src 폴더 내의 ts와 md 파일만)
repomix --include "src/**/*.ts,*.md" --ignore "*.test.js,docs/**"

# 6. 원격 저장소의 특정 브랜치 묶기
repomix --remote https://github.com/user/repo/tree/main

# 7. 현재 수정 중인 내용(diff)과 최근 로그를 포함해 분석 요청
repomix --include-diffs --include-logs --include-logs-count 20

# 8. 토큰 사용량 확인 후 범위 좁히기
repomix --token-count-tree 1000

옵션을 일일이 입력하는 것이 번거롭다면, 이제 설정 파일을 만들 때입니다. 다음 편에서는 repomix.config.* 파일을 통해 팀 표준 설정을 구축하는 방법을 알아보겠습니다.