Logo
Bason

macOS Git Worktree 원클릭 전환: fzf·VS Code Task 자동화 완전 가이드

macOS Git Worktree 원클릭 전환: fzf·VS Code Task 자동화 완전 가이드

이성훈
이성훈June 9, 2026 · 19 views

macOS 동적 워크트리 원클릭 전환 세팅 완전 가이드

Git Worktree + fzf + VS Code Task로 브랜치 전환을 1초 만에 끝내는 법

들어가며: 브랜치 전환, 아직도 손으로 하고 계신가요?

멀티 브랜치 환경에서 작업하다 보면 워크트리를 바꿀 때마다 터미널을 열고, 경로를 입력하고, 포트 충돌을 수동으로 해결하는 반복 작업이 쌓입니다. 하루에도 수십 번 반복되는 이 과정은 집중력을 끊고 개발 흐름을 망가뜨리는 대표적인 페인포인트입니다. 이 글에서는 macOS 환경에서 Git Worktree 전환을 단 한 번의 키 입력으로 끝내는 자동화 세팅을 단계별로 소개합니다.

1단계: fzf 설치 — 처음 한 번만 하면 끝

가장 먼저 fzf(fuzzy finder) 를 설치합니다. fzf는 터미널에서 동적으로 변하는 목록을 실시간으로 불러와 인터랙티브 선택 팝업으로 보여주는 탐색 유틸리티입니다. Homebrew가 설치되어 있다면 아래 명령어 한 줄로 끝납니다.

brew install fzf

설치는 최초 1회만 필요합니다. 이후 모든 워크트리 선택 팝업은 이 fzf가 담당합니다.

2단계: VS Code Task 설정 — tasks.json 구성

프로젝트 루트 폴더에 .vscode 디렉터리를 생성하고, 그 안에 tasks.json 파일을 만든 뒤 아래 코드를 붙여넣습니다. 이 파일 하나가 워크트리 자동 전환의 핵심입니다.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "🚀 워크트리 선택 및 실행",
      "type": "shell",
      "command": "SELECTED_WT=$(git worktree list | awk '{print $1}' | fzf) && [ -n \"$SELECTED_WT\" ] && echo \"🔥 기존 3000번 포트 청소 중...\" && npx kill-port 3000 && cd \"$SELECTED_WT\" && pnpm dev:web",
      "problemMatcher": [],
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "shared"
      }
    }
  ]
}

파일을 저장하면 VS Code가 해당 Task를 즉시 인식합니다. 별도의 플러그인이나 추가 설정은 필요하지 않습니다.

자동화 내부 동작 원리: 4단계 프로세스

Task가 실행되는 순간 백그라운드에서 다음 4단계가 순차적으로 처리됩니다.

  1. git worktree list — 현재 존재하는 모든 워크트리 경로를 실시간으로 동적 조회합니다. 새로 생성되거나 삭제된 워크트리도 즉시 반영됩니다.
  2. fzf — 조회된 목록을 VS Code 인터페이스 안에서 선택 가능한 팝업창으로 렌더링합니다.
  3. npx kill-port 3000 — 새 개발 서버가 시작되기 전, 기존 워크트리가 점유 중인 3000번 포트 프로세스를 선제적으로 강제 종료해 포트 충돌을 원천 차단합니다.
  4. cd ... && pnpm dev:web — 포트가 정리되면 선택한 워크트리 디렉터리로 자동 이동 후 웹 개발 서버를 즉시 구동합니다.

이 4단계가 사용자의 선택 직후 1초 내로 완료됩니다.

3단계: 실무에서 실행하는 두 가지 방법

방법 A. VS Code 명령 팔레트 이용

  1. Cmd + Shift + P 를 눌러 명령 팔레트를 엽니다.
  2. Tasks: Run Task (한국어 설정 시: 작업: 작업 실행)를 입력 후 엔터.
  3. 🚀 워크트리 선택 및 실행 항목을 선택하고 원하는 브랜치를 고르면 완료입니다.

방법 B. 전용 단축키 매핑 (강력 추천)

명령 팔레트를 여는 과정조차 줄이고 싶다면 단축키를 직접 지정하는 것이 가장 효율적입니다.

  1. Cmd + Shift + P → Preferences: Open Keyboard Shortcuts (JSON) 실행.
  2. 열린 JSON 파일의 대괄호 [ ] 안에 아래 코드를 추가하고 저장합니다.
{
  "key": "cmd+alt+w",
  "command": "workbench.action.tasks.runTask",
  "args": "🚀 워크트리 선택 및 실행"
}

설정 완료 후 Cmd + Option + W 한 번이면, 기존 서버 종료부터 새 워크트리 서버 기동까지 마우스 조작 없이 단 1초 만에 처리됩니다.

결론: 반복 작업을 자동화해 개발 흐름을 지키세요

이번 세팅의 핵심을 정리하면 다음과 같습니다.

  • fzf 설치 — 동적 워크트리 목록을 팝업으로 표시하는 인터랙티브 탐색 도구
  • tasks.json 구성 — 포트 정리 → 워크트리 이동 → 서버 기동을 하나의 명령으로 연결
  • 단축키 매핑 — Cmd + Option + W 한 번으로 전체 프로세스 즉시 실행

브랜치 전환마다 소모되던 컨텍스트 스위칭 비용을 없애고, macOS 순정 성능으로 쾌적한 개발 환경을 유지하세요. 지금 바로 세팅하면 오늘 업무부터 체감 효율이 달라집니다.

지금 tasks.json 파일을 만들고, 첫 원클릭 전환을 경험해 보세요.

메타설명: macOS에서 Git Worktree를 fzf와 VS Code Task로 연결해 브랜치 전환을 단축키 한 번에 끝내는 자동화 세팅 방법을 단계별로 안내합니다.

Contact support