vibe
쉽고 빠른 Git Worktree 관리용 CLI 도구입니다.
日本語 | 简体中文
문서화 (Documentation)
📚 전체 문서는 vibe.kexi.dev에서 확인할 수 있습니다.
사용법 (Usage)
| 명령어 | 설명 |
|---|
vibe start <branch> [options] | 새 또는 기존 브랜치로 worktree를 생성합니다 (멱등성). |
| ... | |
예시 (Examples)
vibe start feat/new-feature
...
대화형 프롬프트 (Interactive Prompts)
vibe start는 다음 상황들을 처리합니다:
- 브랜치가 이미 다른 worktree에서 사용 중일 때: 기존 worktree로 이동할지 여부를 확인합니다.
- 동일한 worktree가 이미 존재할 때: 자동으로 이를 재사용합니다 (멱등성).
- 다른 브랜치를 가진 디렉토리가 존재할 때: 다음 옵션 중에서 선택할 수 있습니다.
- 덮어쓰기 (Overwrite): 삭제 후 재생성
- 재사용 (Reuse): 기존 디렉토리 사용
- 취소 (Cancel)
$ vibe start feat/new-feature
Branch 'feat/new-feature'는 worktree '/path/to/repo-feat-new-feature'에서 이미 사용 중입니다.
...
기본 브랜치 옵션 (Base Branch Option)
--base 옵션은 새 브랜치의 시작 지점을 지정합니다:
- 새 브랜치: 지정된 base(브랜치, 태그 또는 커밋)로부터 브랜치를 생성합니다.
- 기존 브랜치:
--base 옵션은 경고와 함께 무시됩니다.
- 유효하지 않은 base: 지정된 ref가 존재하지 않으면 오류와 함께 종료됩니다.
기본적으로, --base는 upstream 추적(upstream tracking)을 설정하지 않습니다. 명시적으로 upstream을 설정하려면 --track을 사용하십시오:
vibe start feat/new-feature --base origin/develop
...
정리 동작 (Cleanup Behavior)
vibe clean은 worktree 디렉토리를 동기적으로 삭제하는 대신, 해당 worktree 디렉토리를 이동시키는 빠른 제거 전략을 사용합니다.
- macOS: 항목은 Finder를 통해 시스템 휴지통으로 이동합니다 (필요시 복구 가능).
- Linux: 항목은 XDG 휴지통으로 이동합니다 (파일 관리자에서 복구 가능).
- Windows: 항목은 휴지통(Recycle Bin)으로 이동합니다 (필요시 복구 가능).
이 접근 방식 덕분에 vibe clean은 작업 트리 크기에 관계없이 즉시 완료될 수 있습니다.
전역 옵션 (Global Options)
| 옵션 | 설명 |
|---|
-h, --help | 도움말 메시지를 표시합니다. |
| ... | |
명령어 옵션 (Command Options)
시작 옵션 (Start Options)
| 옵션 | 설명 |
|---|
--base <ref> | 새 브랜치의 기본 브랜치/커밋입니다. |
| ... | |
정리 옵션 (Clean Options)
| 옵션 | 설명 |
|---|
-f, --force | 확인 프롬프트를 건너뜁니다. |
| ... | |
업그레이드 옵션 (Upgrade Options)
| 옵션 | 설명 |
|---|
--check | 업그레이드 지침을 표시하지 않고 업데이트를 확인합니다. |
설치 (Installation)
Homebrew (macOS)
brew install kexi/tap/vibe
npm (Node.js 18 이상)
npm install -g @kexi/vibe
...
참고: 이 npm 패키지는 플랫폼별 네이티브 vibe 바이너리를 실행하는 얇은 런처입니다 (플랫폼별 optionalDependency, 예: @kexi/vibe-darwin-arm64로 자동 설치됨). macOS(APFS) 및 Linux(Btrfs/XFS)에서 최적화된 Copy-on-Write 파일 클로닝 기능이 해당 바이너리에 직접 내장되어 있습니다.
Bun (1.2.0 이상)
bun add -g @kexi/vibe
...
참고: Bun은 Node.js와 동일한 npm 패키지를 사용합니다. 즉, 플랫폼별 네이티브 vibe 바이너리를 실행합니다.
mise
.mise.toml에 추가합니다:`
[plugins]
vibe = "https://github.com/kexi/mise-vibe"
...
실행:
mise hooks를 사용한 셸 설정
mise activate를 사용하는 경우, 수동 셸 설정을 건너뛰려면 [hooks]에 다음 내용을 추가하세요:
[hooks]
enter = 'eval "$(vibe shell-setup)"'
Nix
nix run github:kexi/vibe -- start feat/my-feature
...
참고: Nix 패키지는 SHA-256 해시로 검증된 GitHub Releases의 사전 빌드 바이너리를 설치합니다.
Linux
참고: WSL2 사용자는 배포판에 따라 아래 리눅스 설치 방법을 사용할 수 있습니다.
Ubuntu/Debian (.deb 패키지)
curl -LO https://github.com/kexi/vibe/releases/latest/download/vibe_amd64.deb
sudo apt install ./vibe_amd64.deb
...
기타 Linux 배포판
curl -L https://github.com/kexi/vibe/releases/latest/download/vibe-linux-x64 -o vibe
chmod +x vibe
...
Windows
Windows (x64)를 지원합니다. npm을 통해 설치할 수 있으며, @kexi/vibe 런처가 사용자의 플랫폼에 맞는 @kexi/vibe-win32-x64 바이너리 패키지를 가져옵니다:
npm install -g @kexi/vibe
[!NOTE]
Copy-on-Write 클로닝은 Windows에서 사용할 수 없으므로, vibe는 worktree를 생성할 때 표준 파일 복사 방식으로 대체됩니다. 그 외 모든 기능은 Linux 및 macOS와 동일하게 작동합니다. 또한 위 리눅스 지침을 사용하여 WSL2에서도 vibe를 실행할 수 있습니다 (Btrfs 볼륨에서의 Copy-on-Write에 유용함). 또는 Rust 툴체인을 사용하여 소스에서 빌드할 수도 있습니다 (참고 수동 빌드).
수동 빌드
cargo build --manifest-path rust/Cargo.toml -p vibe --release
설정 (Setup)
다음 내용을 셸 구성 파일에 추가하세요:
<details>
<summary>Zsh (.zshrc)</summary>
vibe() { eval "$(command vibe "$@")" }
</details>
<details>
<summary>Bash (.bashrc)</summary>
vibe() { eval "$(command vibe $@)"; }
<details>
<summary>Fish (~/.config/fish/config.fish)</summary>
function vibe
eval (command vibe $argv)
end
</details>
<details>
<summary>Nushell (~/.config/nushell/config.nu)</summary>
def --env --wrapped vibe [...args] {
let out = (^vibe --eval-dialect nu ...$args)
for line in ($out | lines) {
...
vibe 2.2.0 이상 버전과 nushell 0.83 이상 버전이 필요합니다. 이전에 붙여넣었던 모든 오래된 nu -c 스니펫은 교체해야 합니다. 해당 스니펫들은 디렉토리를 실제로 변경하지 않았으며 플래그를 포함하는 어떤 명령어도 거부했습니다. --wrapped(플래그가 ...args에 도달하도록 함)와 for(nushell은 each 클로저 내부에서 이루어진 환경 변화를 폐기함) 둘 다 유지해야 합니다.
</details>
<details>
<summary>PowerShell ($PROFILE)</summary>
function vibe { $out = & vibe.exe --eval-dialect powershell @args; if ($out) { Invoke-Expression ($out -join "`n") } }
vibe 2.2.0 이상 버전이 필요합니다. 이전에 붙여넣었던 모든 오래된 Invoke-Expression (& vibe.exe $args) 스니펫은 교체해야 합니다. 해당 스니펫들은 단일 따옴표를 포함하는 경로를 잘못 처리했으며, vibe가 출력을 생성하지 않을 때 오류를 발생시켰습니다.
</details>
설정 (Configuration)
.vibe.toml
.vibe.toml 파일을 리포지토리 루트에 배치하면 vibe start 시 작업이 자동으로 실행됩니다. 이 파일은 일반적으로 git에 커밋되어 팀원들과 공유됩니다.
[copy]
files = ["*.env"]
...
최초 사용 시에는 vibe trust를 사용하여 신뢰 등록이 필요합니다.
복사 설정의 Glob 패턴 (Glob Patterns in Copy Configuration)
files 배열은 유연한 파일 선택을 위해 glob 패턴을 지원합니다:
[copy]
files = [
"*.env",
...
지원되는 패턴:
* - /를 제외한 모든 문자와 일치합니다.** - /를 포함하여 모든 문자와 일치합니다 (재귀적).? - 단일 문자 하나와 일치합니다.[abc] - 대괄호 안의 모든 문자와 일치합니다.
참고:
- 일치하는 파일을 복사할 때 디렉토리 구조가 유지됩니다.
- 재귀 패턴(
**/*)은 대규모 저장소에서 느릴 수 있습니다.
- 가능하다면 특정 패턴을 사용하세요 (예:
**/*.json 대신 config/**/*.json).
- 패턴 확장은 모든 명령어마다 발생하는 것이 아니라 워크트리 생성 시 한 번만 발생합니다.
디렉토리 복사 설정 (Directory Copy Configuration)
The dirs 배열은 전체 디렉토리를 재귀적으로 복사합니다:
[copy]
dirs = [
"node_modules",
...
참고 사항 (Notes):
- 디렉토리는 완전히 복사됩니다 (증분 동기화가 아님).
- Glob 패턴은 파일 패턴과 동일하게 작동합니다.
node_modules와 같은 대규모 디렉토리는 복사에 시간이 걸릴 수 있습니다.
Vibe는 시스템에 따라 최적의 복사 전략을 자동으로 선택합니다:
| 전략 | 사용 시점 | 플랫폼 |
|---|
| Clone (CoW) | APFS의 네이티브 clonefile() 사용 | macOS |
| ... | | |
| 작동 방식: | | |
- 파일 복사: 최고의 단일 파일 성능을 위해 항상 네이티브
copyFile()을 사용합니다.
- 디렉토리 복사: 자동으로 가장 빠른 사용 가능한 방법을 사용합니다:
- APFS를 사용하는 macOS: 즉각적인 CoW 클로닝을 위해 네이티브
clonefile() 시스템 호출(바이너리에 내장)을 사용합니다. 사용 불가능할 경우 cp -cR로 폴백됩니다.
- Btrfs/XFS를 사용하는 Linux: CoW 클로닝을 위해
cp --reflink=auto를 사용합니다.
- CoW가 사용 불가능한 경우 rsync 또는 표준 복사로 폴백됩니다.
장점:
- Copy-on-Write는 메타데이터만 복사하기 때문에 매우 빠릅니다.
- 설정이 필요하지 않습니다 - 최적의 전략이 자동 감지됩니다.
- 자동 폴백 기능은 항상 복사가 작동하도록 보장합니다.
복사 전략 및 구현에 대한 자세한 정보는 Copy Strategies를 참조하세요.
워크트리 경로 설정 (Worktree Path Configuration)
외부 스크립트를 사용하여 워크트리 디렉토리 경로를 사용자 정의할 수 있습니다:
[worktree]
path_script = "~/.config/vibe/worktree-path.sh"
스크립트는 이러한 환경 변수를 받으며 절대 경로를 출력해야 합니다:
| Variable | Description | Example |
|---|
VIBE_REPO_NAME | Repository name | my-project |
| ... | | |
| 예시 스크립트: | | |
#!/bin/bash
echo "${HOME}/worktrees/${VIBE_REPO_NAME}-${VIBE_SANITIZED_BRANCH}"
에디터 지원 (JSON Schema)
Vibe는 자동 완성과 유효성 검사를 위해 settings.json에 대한 JSON Schema를 제공합니다. $schema 속성은 vibe가 설정 파일을 저장할 때 자동으로 추가됩니다. 대부분의 최신 에디터(VS Code, IntelliJ 등)는 자동으로 자동 완성을 제공합니다.
수동 VS Code 설정을 하려면 settings.json 문서를 참조하세요.
보안: 해시 검증 (Hash Verification)
Vibe는 SHA-256 해시를 사용하여 .vibe.toml 및 .vibe.local.toml 파일의 무결성을 자동으로 검증합니다. 이를 통해 설정 파일에 대한 무단 수정이 방지됩니다.
작동 방식
vibe trust를 실행하면 Vibe는 설정 파일의 SHA-256 해시를 계산하고 저장합니다.vibe start를 실행하면 Vibe는 해시를 확인하여 파일이 수정되지 않았는지 검증합니다.- 해시가 일치하지 않으면, Vibe는 오류와 함께 종료되며
vibe trust를 다시 실행하도록 요청합니다.
해시 검사 건너뛰기 (개발용)
설정 파일(~/.config/vibe/settings.json)에서 해시 검증을 비활성화할 수 있습니다:
전역 설정:
{
"version": 3,
"skipHashCheck": true,
...
파일별 설정:
{
"version": 3,
"permissions": {
...
참고: 버전 3은 리포지토리 기반의 신뢰 식별자를 사용합니다. 설정은 첫 로드 시 v2에서 v3로 자동 마이그레이션됩니다. 신뢰는 동일한 리포지토리의 모든 워크트리에서 공유됩니다.
브랜치 전환 (Branch switching)
Vibe는 파일당 여러 개의 해시(최대 100개)를 저장하므로, 파일을 다시 신뢰할 필요 없이 브랜치 간 전환이 가능합니다 (단, 각 브랜치의 버전을 최소 한 번 신뢰했을 경우).
보안 고려 사항
트러스트 메커니즘은 사용자가 해당 파일을 신뢰한 이후로 설정 파일이 수정되지 않았는지 확인하는 역할을 합니다. 하지만, 다음 사항에 유의하십시오: