디렉토리 트리 구조와 함께 프로젝트 파일들을 하나의 텍스트 파일로 결합하여 코딩 프로젝트를 위한 LLM 컨텍스트를 제공하는 CLI 도구입니다.

코딩 프로젝트를 이어가거나 디버깅하기 위해 대규모 언어 모델 (LLMs)을 사용할 때, 적절한 컨텍스트 (context)를 제공하는 것이 핵심입니다. gptree는 다음과 같은 기능을 통해 이 과정을 단순화합니다:

• 프로젝트의 명확한 디렉토리 트리 구조 (directory tree structure) 생성
• **관련 파일의 내용 (contents of relevant files)**을 하나의 출력 텍스트 파일로 결합
• 포함될 파일을 미세 조정할 수 있도록 대화형 파일 선택 (select files interactively) 기능 제공
• 최대의 유연성을 위해 간단한 파일 유형 필터링 (simple file type filtering) 및 고급 글로브 패턴 (advanced glob patterns) 지원

생성된 파일은 LLM 프롬프트에 쉽게 복사하여 붙여넣을 수 있으며, 모델이 사용자를 효과적으로 도울 수 있도록 필요한 컨텍스트를 제공합니다.

• 🗂 트리 구조 (Tree Structure): 프로젝트의 시각적인 디렉토리 트리를 포함합니다.
• ✅ 스마트 파일 선택 (Smart File Selection): .gitignore 및 .git, __pycache__, .vscode와 같은 일반적인 디렉토리를 사용하여 무시된 파일을 자동으로 제외합니다.
• 📁 간단한 파일 유형 (Simple File Types): 빠른 설정을 위해 파일 확장자(예: .py, .js)로 쉽게 필터링할 수 있습니다.
• 🎯 고급 패턴 (Advanced Patterns): 복잡한 필터링을 위한 선택적 글로브 패턴(glob patterns)을 지원합니다 (예: src/**/*.py, !**/tests/**).
• 🎛 대화형 모드 (Interactive Mode): 화살표 키를 사용하여 파일을 대화형으로 선택하거나 선택 해제할 수 있으며, ESC를 눌러 즉시 종료할 수 있습니다.
• 🌍 글로벌 설정 지원 (Global Config Support): ~/.gptreerc 파일에서 기본 설정을 정의할 수 있습니다.
• 🔧 디렉토리별 설정 (Directory-Specific Config): .gptree_config 파일을 통해 각 프로젝트별로 동작을 맞춤 설정할 수 있습니다.
• 🎛 CLI 오버라이드 (CLI Overrides): 최대의 제어력을 위해 CLI에서 직접 설정을 미세 조정할 수 있습니다.
• 📜 안전 모드 (Safe Mode): 파일 수와 총 크기를 제한하여 너무 큰 파일이 결합되는 것을 방지합니다.
• 📋 클립보드 지원 (Clipboard Support): 원하는 경우 출력을 클립보드에 자동으로 복사합니다.
• 🛠 사용자 정의 구성 관리 (Custom Configuration Management): 프로젝트별로 자동 감지되거나 전역적으로 적용되는 구성을 정의합니다.

아름답고 효율적인 그래픽 인터페이스와 함께 gptree를 경험해 보세요!

가볍고 빠름 (Lightweight & Fast): 최적의 성능을 위해 Rust로 구축되었습니다.
크로스 플랫폼 (Cross-Platform): macOS, Windows, Linux에서 사용할 수 있습니다.
자세히 알아보기 및 다운로드: gptree.dev를 방문하세요.
오픈 소스 (Open Source): GitHub에서 코드를 확인하세요.

pipx install gptree-cli

brew tap travisvn/tap
brew install gptree

Homebrew는 pip3를 사용하여 gptree 설치를 시도하며,
그렇지 않을 경우 바이너리 (binary) 설치로 전환합니다.

또는 pip를 통해 gptree (gptree-cli)를 직접 설치할 수 있습니다:

pip install gptree-cli

참고

Python (pipx 또는 pip)으로 직접 설치할 때 성능이 더 좋습니다.
바이너리 설치는 시작하는 데 1~2초 정도 더 걸릴 수 있습니다 (큰 문제는 아니지만 참고하시기 바랍니다).

프로젝트 디렉토리에서 gptree를 실행하세요:

gptree

또는 어디에서나 실행하고 프로젝트에 대한 상대 경로를 정의할 수 있습니다.

--exclude-file-types와 결합하여 사용 |
| --output-file | 출력 파일의 이름을 지정 |
| --output-file-locally | 출력 파일을 현재 작업 디렉토리에 저장 |
| --no-config , -nc | 설정 파일의 생성 또는 사용을 비활성화 |
| --ignore-gitignore | .gitignore 패턴을 무시 |
| --disable-safe-mode , -dsm | 파일 개수 또는 크기에 대한 세이프 모드 (Safe Mode) 체크를 비활성화 |
| --line-numbers , -n | 출력물에 줄 번호를 추가 |
| --previous , -p | 이전에 저장된 파일 선택 사항을 사용 |
| --save , -s | 선택된 파일을 설정에 저장 |
| --show-ignored-in-tree | 디렉토리 트리에서 무시된 모든 파일을 표시 |
| --show-default-ignored-in-tree | .gitignore를 준수하면서도 트리 내에 기본적으로 무시되는 파일들을 표시 |
| --version | GPTree의 현재 버전을 표시 |
| path | (선택 사항) 프로젝트의 루트 디렉토리. 기본값은 . |

Python 및 JavaScript 파일만 포함하기:

gptree --include-file-types .py,.js

로그 및 임시 파일 제외하기:

gptree --exclude-file-types .log,.tmp,.cache

특정 유형은 포함하고 다른 유형은 제외하기:

gptree --include-file-types .py,.js,.ts --exclude-file-types .test.py,.spec.js

src 디렉토리의 Python 파일은 포함하되 테스트 파일은 제외하기:

gptree --include-patterns "src/**/*.py" --exclude-patterns "**/test_*.py"

웹 프로젝트를 위한 복잡한 필터링:

gptree --include-patterns "src/**/*.{js,ts,jsx,tsx},styles/**/*.{css,scss}" --exclude-patterns "**/tests/**,**/*.test.*,**/*.spec.*"

특정 디렉토리에 있는 파일을 제외한 모든 파일 포함하기:

gptree --exclude-patterns "node_modules/**,venv/**,.git/**"

파일 유형을 기본 필터로 사용하면서 추가적인 패턴 제외 적용하기:

gptree --include-file-types .py,.js --exclude-patterns "**/tests/**,**/node_modules/**"

참고: 포함(includes)을 위해 파일 유형과 패턴이 모두 지정된 경우, 패턴이 우선순위를 갖습니다. 제외(excludes)의 경우, 파일 유형과 패턴이 모두 결합되어 적용됩니다.

사전 필터링된 파일들을 사용한 대화형 파일 선택:

gptree --interactive --include-file-types .py,.js

현재 선택 사항을 설정(config)에 저장:

gptree --interactive --save

이전에 저장된 파일 선택 사항을 재사용하고 클립보드에 복사:

gptree --previous --copy

GPTree는 다양한 사용자의 요구를 충족하기 위해 파일 필터링에 두 가지 접근 방식을 제공합니다:

사용 사례: 확장자(extension)를 통해 빠르고 쉽게 파일을 포함하거나 제외하고 싶을 때.

# 빠르고 간편하게 - Python 및 JavaScript 파일 포함
gptree --include-file-types .py,.js
# 일반적인 불필요한 파일 제외
...

설정(Config) 예시:

includeFileTypes: .py,.js,.ts
excludeFileTypes: .log,.tmp

사용 사례: 디렉토리 구조에 대한 정밀한 제어와 복잡한 필터링이 필요할 때.

# 고급 기능 - 특정 디렉토리 패턴 포함
gptree --include-patterns "src/**/*.py,tests/**/*.py" --exclude-patterns "**/conftest.py"

설정(Config) 예시:

includePatterns: src/**/*.py,**/*.js
excludePatterns: **/tests/**,**/*.log

두 가지 방식을 결합할 수도 있습니다! 파일 유형(file types)은 기본 필터를 제공하며, 패턴(patterns)은 고급 규칙을 추가합니다:

# 파일 유형을 기본으로 사용하고, 패턴으로 고급 제외 규칙 적용
gptree --include-file-types .py,.js --exclude-patterns "**/node_modules/**,**/tests/**"

프로젝트마다 반복적인 설정을 피하려면 ~/.gptreerc에 전역 기본값(global defaults)을 정의하세요. 예시:

# ~/.gptreerc
version: 3
useGitIgnore: true
...

이 파일은 존재하지 않을 경우 기본 설정으로 자동 생성됩니다.

프로젝트 루트에 .gptree_config 파일을 추가하여 특정 프로젝트에 대한 설정을 사용자 정의할 수 있습니다. 예시:

# .gptree_config
version: 3
useGitIgnore: false
...

설정은 다음 순서(높은 우선순위부터 낮은 순서)로 적용됩니다:

CLI Arguments (CLI 인자): 항상 다른 설정을 덮어씁니다.
Directory Config (디렉토리 설정): .gptree_config에 정의된 프로젝트별 설정.
Global Config (글로벌 설정): ~/.gptreerc에 정의된 사용자 지정 기본값.
Programmed Defaults (프로그램 기본값): 다른 설정이 제공되지 않을 때 사용되는 내장 기본값.

Include Logic (포함 로직): includePatterns가 지정되어 있고 비어 있지 않은 경우, 이는 includeFileTypes를 덮어씁니다. 그렇지 않으면 includeFileTypes는 내부적으로 패턴으로 변환됩니다.

Exclude Logic (제외 로직): excludeFileTypes와 excludePatterns가 모두 결합되어, 둘 중 하나라도 일치하는 파일은 제외됩니다.

Migration (마이그레이션): 기존 설정은 자동으로 보존되며, 파일 유형(file types)에서 패턴(patterns)으로의 강제 변환은 발생하지 않습니다.

너무 큰 파일이 결합되는 것을 방지하기 위해, Safe Mode (안전 모드)는 다음을 제한합니다:

• 전체 파일 수 (기본값: 30개)
• 결합된 파일 크기 (기본값: 약 25k 토큰, 약 100,000 바이트)

--disable-safe-mode를 사용하여 Safe Mode를 비활성화할 수 있습니다.

대화형 모드(interactive mode)에서는 다음 컨트롤을 사용합니다:

기여를 환영합니다! 개선 사항이 있다면 저장소를 포크(fork)하고 풀 리퀘스트(pull request)를 생성해 주세요.

이 프로젝트는 GNU General Public License v3.0 (GPL-3.0) 라이선스 하에 배포됩니다.