본문으로 건너뛰기
오픈소스 전체 목록

fzf

파일 · 명령 기록 · 목록을 입력하며 바로 고르는 범용 명령줄 퍼지 파인더. Bash · Zsh · Fish · Vim 연동. MIT

원본:junegunn/fzf

요약

파일 · 명령 기록 · 목록을 입력하며 바로 고르는 범용 명령줄 퍼지 파인더. Bash · Zsh · Fish · Vim 연동. MIT

설명

fzf - 명령줄 퍼지 파인더

빌드 상태 버전 라이선스 기여자 후원자 별


fzf 굴시 튜어리얼 아닌 사랑을 보여 주세요 -- 티셔츠, 머그컵, 스티커를 이제 만날 수 있습니다!

fzf 굴즈

commitgoods.com의 공식 굴즈


fzf는 범용 명령줄 퍼지 파인더이자 대화형 터미널 도구 모음입니다.

파일을 고르든, 명령 기록을 훑든, 데이터를 미리 보든, 퍼지 매칭으로 복잡한 데이터 집합을 탐색하든, 사용자 정의 메뉴와 워크플로를 만들든, fzf는 쉘 스크립트를 풍부한 터미널 애플리케이션으로 바꾸는 빌딩 블록을 제공합니다.

fzf 미리보기

주요 특징

  • 이식성 // 단일 실행 파일로 배포되어 설치가 쉽습니다
  • 빠름 // 수백만 개 항목을 밀리초 단위로 처리하도록 최적화되어 있습니다
  • 프로그래밍 가능 // 이벤트 기반 구조로 사용자 정의 터미널 인터페이스와 워크플로를 만들 수 있습니다
  • 배터리 포함 // Bash, Zsh, Fish, Nushell, Vim, Neovim 연동이 들어 있습니다

차례

  • 설치
    • Homebrew 쓰기
    • Mise 쓰기
    • Linux 패키지
    • Windows 패키지
    • git 쓰기
    • 바이너리 릴리스
    • 쉘 연동 설정
    • Vim/Neovim 플러그인
  • fzf 업그레이드
  • fzf 빌드
  • 사용법
    • 파인더 쓰기
    • 표시 모드
      • --height 모드
      • --popup 모드
    • 검색 문법
    • 환경 변수
    • 모양 꾸미기
    • 옵션
    • 데모
  • 예시
  • 명령줄 키 바인딩
  • 퍼지 자동 완성
    • 파일과 디렉터리
    • 프로세스 ID
    • 호스트 이름
    • 환경 변수 / 별칭
    • bash와 zsh의 퍼지 자동 완성 꾸미기
    • 사용자 정의 퍼지 자동 완성
    • fish용 퍼지 자동 완성
    • Nushell용 퍼지 자동 완성
  • Vim 플러그인
  • 고급 주제
    • 입력 종류에 맞게 꾸미기
    • 성능
    • 외부 프로그램 실행
    • 다른 프로세스로 바꾸기
    • 후보 목록 다시 불러오기
    • 미리보기 창
    • 이미지 미리보기
  • 팁
    • .gitignore 따르기
    • Fish 쉘
    • fzf 테마 놀이터
  • 관련 프로젝트
  • 라이선스
  • 굴즈
  • 후원자

설치

Homebrew 쓰기

Homebrew(macOS 또는 Linux)로 fzf를 설치할 수 있습니다.

brew install fzf

💡 중요 쉘 연동(키 바인딩과 퍼지 자동 완성)을 설정하려면 아래 쉘 연동 설정 안내를 보세요.

fzf는 MacPorts로도 쓸 수 있습니다: sudo port install fzf

Mise 쓰기

mise로 fzf를 설치할 수 있습니다.

mise use -g fzf@latest

Linux 패키지

패키지 관리자Linux 배포판명령
APKAlpine Linuxsudo apk add fzf
APTDebian 9+/Ubuntu 19.10+sudo apt install fzf
Condaconda install -c conda-forge fzf
DNFFedorasudo dnf install fzf
NixNixOS 등nix-env -iA nixpkgs.fzf
PacmanArch Linuxsudo pacman -S fzf
pkgFreeBSDpkg install fzf
pkginNetBSDpkgin install fzf
pkg_addOpenBSDpkg_add fzf
PortageGentooemerge --ask app-shells/fzf
Spackspack install fzf
XBPSVoid Linuxsudo xbps-install -S fzf
ZypperopenSUSEsudo zypper install fzf

💡 중요 쉘 연동(키 바인딩과 퍼지 자동 완성)을 설정하려면 아래 쉘 연동 설정 안내를 보세요.

패키지 현황

Windows 패키지

Windows에서는 Chocolatey, Scoop, Winget, MSYS2로 fzf를 쓸 수 있습니다.

패키지 관리자명령
Chocolateychoco install fzf
Scoopscoop install fzf
Wingetwinget install fzf
MSYS2 (pacman)pacman -S $MINGW_PACKAGE_PREFIX-fzf

git 쓰기

대신 이 저장소를 아무 디렉터리에 "git clone"하고 install 스크립트를 실행할 수도 있습니다.

git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

설치 스크립트는 쉘 설정 파일에 줄을 더해 $PATH를 바꾸고 쉘 연동을 설정합니다.

바이너리 릴리스

릴리스 페이지에서 공식 fzf 바이너리를 내려받을 수 있습니다.

쉘 연동 설정

쓰는 쉘의 설정 파일에 다음 줄을 추가하세요.

  • bash
    # Set up fzf key bindings and fuzzy completion
    eval "$(fzf --bash)"
  • zsh
    # Set up fzf key bindings and fuzzy completion
    source <(fzf --zsh)
  • fish
    # Set up fzf key bindings
    fzf --fish | source
    
  • Nushell -- Nushell은 source로 파이프하는 것을 지원하지 않아서, 설치 스크립트가 자동 로드 디렉터리에 파일을 만듭니다. 설치 스크립트를 쓰지 않았다면 직접 설정할 수 있습니다.
    # Generate the integration script
    mkdir ($nu.default-config-dir | path join "autoload")
    fzf --nushell | save -f ($nu.default-config-dir | path join "autoload" "_fzf_integration.nu")
    

💡 참고 --bash, --zsh, --fish, --nushell 옵션은 최근 버전의 fzf에서만 쓸 수 있습니다. 오래된 버전이거나 더 세밀하게 제어하고 싶다면 /shell 디렉터리의 스크립트 파일을 하나씩 source 할 수 있습니다. 파일 위치는 쓰는 패키지 관리자에 따라 다를 수 있으니 패키지 문서를 참고하세요. (예: apt show fzf)

💡 팁 스크립트를 source 할 때 해당 *_COMMAND 변수를 빈 문자열로 두면 CTRL-T, CTRL-R, ALT-C 바인딩을 끌 수 있습니다. 예를 들어 CTRL-R과 ALT-C를 끄려면:

  • bash: FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= eval "$(fzf --bash)"
  • zsh: FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= source <(fzf --zsh)
  • fish: fzf --fish | FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= source
  • nushell: env.nu에 추가: $env.FZF_CTRL_R_COMMAND = ""; $env.FZF_ALT_C_COMMAND = ""

스크립트를 source 한 뒤에 변수를 정해도 효과가 없습니다.

Vim/Neovim 플러그인

vim-plug를 쓴다면 Vim 설정 파일에 다음을 추가하세요.

Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
  • junegunn/fzf는 기본 라이브러리 함수를 제공합니다
    • fzf#install()은 최신 바이너리를 쓰도록 보장합니다
  • junegunn/fzf.vim은 다양한 유용한 명령을 제공하는 별도 프로젝트입니다

Vim 연동에 대해 더 알아보려면 README-VIM.md를 보세요.

💡 팁 Neovim을 쓰고 Lua 기반 플러그인을 선호한다면 fzf-lua를 확인해 보세요.

fzf 업그레이드

fzf는 활발히 개발되고 있어서 가끔 업그레이드하고 싶을 수 있습니다. 쓴 설치 방법에 따라 아래 안내를 따르세요.

  • git: cd ~/.fzf && git pull && ./install
  • brew: brew update; brew upgrade fzf
  • macports: sudo port upgrade fzf
  • chocolatey: choco upgrade fzf
  • vim-plug: :PlugUpdate fzf

fzf 빌드

BUILD.md를 보세요.

사용법

fzf는 대화형 파인더를 실행하고, STDIN에서 목록을 읽어, 선택한 항목을 STDOUT에 씁니다.

find * -type f | fzf > selected

STDIN 파이프가 없으면 fzf는 현재 디렉터리 아래의 파일 시스템을 훑어 파일 목록을 가져옵니다.

vim $(fzf)

💡 참고 기본 동작은 바꿀 수 있습니다.

  • $FZF_DEFAULT_COMMAND를 원하는 목록을 만드는 명령으로 정하거나
  • $FZF_DEFAULT_OPTS에 --walker, --walker-root, --walker-skip 옵션을 설정합니다

💡 경고 더 든든한 방법은 xargs를 쓰는 것이지만, 이해하기 쉽도록 위의 방식으로 보여 드렸습니다.

fzf --print0 | xargs -0 -o vim

💡 팁 fzf는 자신을 다른 프로세스로 바꿀 수도 있습니다.

fzf --bind 'enter:become(vim {})'

자세한 내용은 아래 「다른 프로세스로 바꾸기」를 보세요.

파인더 쓰기

  • CTRL-K / CTRL-J(또는 CTRL-P / CTRL-N)로 커서를 위아래로 움직입니다
  • Enter 키로 항목을 고르고, CTRL-C / CTRL-G / ESC로 나갑니다
  • 다중 선택 모드(-m)에서는 TAB과 Shift-TAB으로 여러 항목을 표시합니다
  • Emacs 스타일 키 바인딩
  • 마우스: 스크롤, 클릭, 더블 클릭. 다중 선택 모드에서는 Shift-클릭과 Shift-스크롤

표시 모드

fzf는 기본으로 전체 화면 모드로 실행되지만 다른 표시 모드도 있습니다.

--height 모드

--height HEIGHT[%]를 쓰면 fzf는 커서 아래에서 주어진 높이로 시작합니다.

fzf --height 40%

reverse 레이아웃과 --border가 이 옵션과 잘 어울립니다.

fzf --height 40% --layout reverse --border

높이 앞에 ~를 붙이면 최대 높이를 정하는 것입니다.

# Will take as few lines as possible to display the list
seq 3 | fzf --height ~100%
seq 3000 | fzf --height ~100%

높이 값은 음수일 수도 있습니다.

# Screen height - 3
fzf --height -3

--popup 모드

--popup 옵션을 쓰면 fzf는 팝업 창에서 시작합니다(tmux 3.3+ 또는 Zellij 0.44+ 필요).

# --popup [center|top|bottom|left|right][,SIZE[%]][,SIZE[%][,border-native]]

fzf --popup center         # Center, 50% width and height
fzf --popup 80%            # Center, 80% width and height
fzf --popup 100%,50%       # Center, 100% width and 50% height
fzf --popup left,40%       # Left, 40% width
fzf --popup left,40%,90%   # Left, 40% width, 90% height
fzf --popup top,40%        # Top, 40% height
fzf --popup bottom,80%,40% # Bottom, 80% width, 40% height

tmux나 Zellij에 있지 않으면 --popup은 조용히 무시됩니다.

💡 참고 팝업을 지원하지 않는 오래된 tmux를 쓰거나 일반 tmux 패인에서 fzf를 열고 싶다면 fzf-tmux 스크립트를 확인해 보세요.

💡 팁 이 옵션들을 $FZF_DEFAULT_OPTS에 넣어 두면 기본으로 적용됩니다. 예를 들어,

# Open in a popup if on tmux or Zellij, otherwise use --height mode
export FZF_DEFAULT_OPTS='--height 40% --popup bottom,40% --layout reverse --border top'

검색 문법

달리 지정하지 않으면 fzf는 "확장 검색 모드"로 시작하며, 공백으로 구분한 여러 검색어를 입력할 수 있습니다. 예: ^music .mp3$ sbtrkt !fire

토큰매칭 종류설명
sbtrkt퍼지 매칭sbtrkt와 맞는 항목
'wild정확 매칭(따옴표)wild를 포함하는 항목
'wild'정확 경계 매칭(양쪽 따옴표)단어 경계에서 wild를 포함하는 항목
^music접두사 정확 매칭music으로 시작하는 항목
.mp3$접미사 정확 매칭.mp3로 끝나는 항목
!fire부정 정확 매칭fire를 포함하지 않는 항목
!^music부정 접두사 정확 매칭music으로 시작하지 않는 항목
!.mp3$부정 접미사 정확 매칭.mp3로 끝나지 않는 항목

퍼지 매칭을 선호하지 않거나 모든 단어에 따옴표를 붙이고 싶지 않다면 -e 또는 --exact 옵션으로 fzf를 시작하세요. --exact가 설정되면 ' 접두사가 검색어의 따옴표를 "푸는" 역할을 합니다.

막대 문자 하나로 이루어진 검색어는 OR 연산자로 동작합니다. 예를 들어 다음은 core로 시작하고 go, rb, py 중 하나로 끝나는 항목과 맞습니다.

^core go$ | rb$ | py$

환경 변수

  • FZF_DEFAULT_COMMAND
    • 입력이 tty일 때 쓸 기본 명령
    • 예: export FZF_DEFAULT_COMMAND='fd --type f'
  • FZF_DEFAULT_OPTS
    • 기본 옵션
    • 예: export FZF_DEFAULT_OPTS="--layout=reverse --inline-info"
  • FZF_DEFAULT_OPTS_FILE
    • 기본 옵션을 파일로 관리하고 싶다면 이 변수를 그 파일 위치로 정합니다
    • 예: export FZF_DEFAULT_OPTS_FILE=~/.fzfrc

💡 경고 FZF_DEFAULT_COMMAND는 요구 사항이 약간 다르기 때문에 쉘 연동에서는 쓰이지 않습니다.

  • CTRL-T는 $FZF_CTRL_T_COMMAND를 실행해 파일과 디렉터리 목록을 가져옵니다
  • ALT-C는 $FZF_ALT_C_COMMAND를 실행해 디렉터리 목록을 가져옵니다
  • vim ~/**은 접두사(~/)를 첫 번째 인수로 하여 fzf_compgen_path()를 실행합니다
  • cd foo**는 접두사(foo)를 첫 번째 인수로 하여 fzf_compgen_dir()을 실행합니다

쓸 수 있는 옵션은 이 문서의 뒤에서 설명합니다.

모양 꾸미기

fzf의 사용자 인터페이스는 많은 설정 옵션으로 완전히 바꿀 수 있습니다. 빠르게 시작하려면 --style 옵션의 스타일 프리셋 default, full, minimal 중 하나로 시작하면 됩니다.

fzf --style full \
    --preview 'fzf-preview.sh {}' --bind 'focus:transform-header:file --brief {}'
프리셋스크린샷
defaultdefault 프리셋
fullfull 프리셋
minimalminimal 프리셋

다음은 full 프리셋을 바탕으로 한 예입니다.

full 프리셋에 테두리를 입힌 데모

git ls-files | fzf --style full \
    --border --padding 1,2 \
    --border-label ' Demo ' --input-label ' Input ' --header-label ' File Type ' \
    --preview 'fzf-preview.sh {}' \
    --bind 'result:transform-list-label:
        if [[ -z $FZF_QUERY ]]; then
          echo " $FZF_MATCH_COUNT items "
        else
          echo " $FZF_MATCH_COUNT matches for [$FZF_QUERY] "
        fi
        ' \
    --bind 'focus:transform-preview-label:[[ -n {} ]] && printf " Previewing [%s] " {}' \
    --bind 'focus:+transform-header:file --brief {} || echo "No file selected"' \
    --bind 'ctrl-r:change-list-label( Reloading the list )+reload(sleep 2; git ls-files)' \
    --color 'border:#aaaaaa,label:#cccccc' \
    --color 'preview-border:#9999cc,preview-label:#ccccff' \
    --color 'list-border:#669966,list-label:#99cc99' \
    --color 'input-border:#996666,input-label:#ffcccc' \
    --color 'header-border:#6699cc,header-label:#99ccff'

옵션

전체 옵션 목록은 man 페이지(fzf --man 또는 man fzf)를 보세요.

데모

영상으로 배우는 편이라면, @samoshkin이 만든 이 스크린캐스트로 fzf 기능을 살펴보세요.

fzf - 명령줄 퍼지 파인더

예시

명령줄 키 바인딩

쉘 연동을 설정하면 bash, zsh, fish, Nushell에서 다음 키 바인딩을 쓸 수 있습니다.

  • CTRL-T - 선택한 파일과 디렉터리를 명령줄에 붙여 넣습니다
    • 목록은 --walker file,dir,follow,hidden 옵션으로 만들어집니다
    • FZF_CTRL_T_COMMAND를 원하는 목록을 만드는 명령으로 정해 동작을 바꿀 수 있습니다
    • 또는 FZF_CTRL_T_OPTS에 --walker* 옵션을 정할 수 있습니다
    • FZF_CTRL_T_OPTS로 fzf에 추가 옵션을 넘깁니다
      # Preview file content using bat (https://github.com/sharkdp/bat)
      export FZF_CTRL_T_OPTS="
        --walker-skip .git,node_modules,target
        --preview 'bat -n --color=always {}'
        --bind 'ctrl-/:change-preview-window(down|hidden|)'"
    • 스크립트를 source 할 때 FZF_CTRL_T_COMMAND를 빈 문자열로 두면 끌 수 있습니다
  • CTRL-R - 선택한 명령을 기록에서 명령줄에 붙여 넣습니다.
    • TAB으로 여러 명령을 고릅니다.
    • 명령을 시간 순서로 보고 싶다면 CTRL-R을 다시 누르세요. 관련도 순 정렬을 뒤집습니다
    • ALT-R을 누르면 매칭의 주변 항목을 볼 수 있는 "raw" 모드를 켭니다. 이 모드에서는 CTRL-N과 CTRL-P로 매칭되는 항목끼리만 움직일 수 있습니다.
    • CTRL-/ 또는 ALT-/로 줄 바꿈을 켤니다
    • SHIFT-DELETE로 선택한 명령을 지웁니다(bash와 fish)
    • Fish 쉘에서만:
      • ALT-ENTER로 선택한 명령을 다시 서식해 삽입합니다
      • ALT-T로 명령 접두사(타임스탬프, 날짜/시간, 없음)를 순환합니다
    • FZF_CTRL_R_OPTS로 fzf에 추가 옵션을 넘깁니다
      # CTRL-Y to copy the command into clipboard using pbcopy
      export FZF_CTRL_R_OPTS="
        --bind 'ctrl-y:execute-silent(echo -n {2..} | pbcopy)+abort'
        --color header:italic
        --header 'Press CTRL-Y to copy command into clipboard'"
      # Fish shell: Set date/time as default prefix
      set -gx FZF_CTRL_R_OPTS "--with-nth 1,3.. --bind 'alt-t:change-with-nth(2..|3..|1,3..)'"
      
      # Or display no prefix by default
      set -gx FZF_CTRL_R_OPTS "--with-nth 3.. --bind 'alt-t:change-with-nth(2..|1,3..|3..)'"
      
    • 스크립트를 source 할 때 FZF_CTRL_R_COMMAND를 빈 문자열로 두면 끌 수 있습니다
    • 비어 있지 않은 FZF_CTRL_R_COMMAND로 직접 덮어쓰는 것은 아직 지원되지 않으며 경고를 냅니다
  • ALT-C - 선택한 디렉터리로 cd 합니다
    • 목록은 --walker dir,follow,hidden 옵션으로 만들어집니다
    • FZF_ALT_C_COMMAND를 정해 기본 명령을 덮어쓸 수 있습니다
    • 또는 FZF_ALT_C_OPTS에 --walker-* 옵션을 정할 수 있습니다
    • FZF_ALT_C_OPTS로 fzf에 추가 옵션을 넘깁니다
      # Print tree structure in the preview window
      export FZF_ALT_C_OPTS="
        --walker-skip .git,node_modules,target
        --preview 'tree -C {}'"
    • 스크립트를 source 할 때 FZF_ALT_C_COMMAND를 빈 문자열로 두면 끌 수 있습니다

이 바인딩의 표시 모드는 FZF_{CTRL_T,CTRL_R,ALT_C}_OPTS로 따로 설정하거나 FZF_DEFAULT_OPTS로 한 번에 설정할 수 있습니다. (예: FZF_CTRL_R_OPTS='--popup bottom,60% --height 60% --border top')

더 많은 팁은 위키 페이지에 있습니다.

퍼지 자동 완성

쉘 연동은 bash, zsh, fish, Nushell용 퍼지 자동 완성도 제공합니다.

파일과 디렉터리

커서 앞 단어가 트리거 시퀀스(기본값 **)로 끝나면 파일과 디렉터리에 대한 퍼지 자동 완성을 불러올 수 있습니다.

  • COMMAND [DIRECTORY/][FUZZY_PATTERN]**
# Files under the current directory
# - You can select multiple items with TAB key
vim **<TAB>

# Files under parent directory
vim ../**<TAB>

# Files under parent directory that match `fzf`
vim ../fzf**<TAB>

# Files under your home directory
vim ~/**<TAB>

# Directories under current directory (single-selection)
cd **<TAB>

# Directories under ~/github that match `fzf`
cd ~/github/fzf**<TAB>

프로세스 ID

kill 명령에는 PID용 퍼지 자동 완성이 제공됩니다.

# Can select multiple processes with <TAB> or <Shift-TAB> keys
kill -9 **<TAB>

호스트 이름

ssh 명령에는 호스트 이름용 퍼지 자동 완성이 제공됩니다. 이름은 /etc/hosts와 ~/.ssh/config에서 뽑습니다.

ssh **<TAB>

환경 변수 / 별칭

# bash and zsh
unset **<TAB>
export **<TAB>
unalias **<TAB>

# fish
set <SHIFT-TAB>

bash와 zsh의 퍼지 자동 완성 꾸미기

자동 완성에 쓸 fzf 옵션 꾸미기

# Use ~~ as the trigger sequence instead of the default **
export FZF_COMPLETION_TRIGGER='~~'

# Options to fzf command
export FZF_COMPLETION_OPTS='--border --info=inline'

# Options for path completion (e.g. vim **<TAB>)
export FZF_COMPLETION_PATH_OPTS='--walker file,dir,follow,hidden'

# Options for directory completion (e.g. cd **<TAB>)
export FZF_COMPLETION_DIR_OPTS='--walker dir,follow'

# Advanced customization of fzf options via _fzf_comprun function
# - The first argument to the function is the name of the command.
# - You should make sure to pass the rest of the arguments ($@) to fzf.
_fzf_comprun() {
  local command=$1
  shift

  case "$command" in
    cd)           fzf --preview 'tree -C {} | head -200'   "$@" ;;
    export|unset) fzf --preview "eval 'echo \$'{}"         "$@" ;;
    ssh)          fzf --preview 'dig {}'                   "$@" ;;
    *)            fzf --preview 'bat -n --color=always {}' "$@" ;;
  esac
}

경로와 디렉터리 자동 완성의 후보 원천 꾸미기

# Use fd (https://github.com/sharkdp/fd) for listing path candidates.
# - The first argument to the function ($1) is the base path to start traversal
# - See the source code (completion.{bash,zsh}) for the details.
_fzf_compgen_path() {
  fd --hidden --follow --exclude ".git" . "$1"
}

# Use fd to generate the list for directory completion
_fzf_compgen_dir() {
  fd --type d --hidden --follow --exclude ".git" . "$1"
}

지원하는 명령(bash)

bash에서는 미리 정해 둔 명령에만 퍼지 자동 완성이 켜집니다(complete | grep _fzf로 목록을 볼 수 있습니다). 하지만 _fzf_setup_completion 도우미 함수로 다른 명령에도 켜 수 있습니다.

# usage: _fzf_setup_completion path|dir|var|alias|host COMMANDS...
_fzf_setup_completion path ag git kubectl
_fzf_setup_completion dir tree

사용자 정의 퍼지 자동 완성

(사용자 정의 자동 완성 API는 실험적이며 바뀔 수 있습니다)

이름이 _"COMMAND"_인 명령에는 _fzf_complete 도우미로 _fzf_complete_COMMAND 함수를 정의합니다.

# Custom fuzzy completion for "doge" command
#   e.g. doge **<TAB>
_fzf_complete_doge() {
  _fzf_complete --multi --reverse --prompt="doge> " -- "$@" < <(
    echo very
    echo wow
    echo such
    echo doge
  )
}
  • -- 앞의 인수는 fzf에 넘길 옵션입니다.
  • -- 뒤에는 원래의 자동 완성 인수를 그대로("$@") 넘깁니다.
  • 그런 다음 자동 완성 후보를 만드는 명령을 쓰고, 그 출력을 프로세스 치환(< <(...))으로 함수에 넘깁니다.

zsh는 이름 규칙으로 함수를 자동으로 찾지만, bash에서는 complete 명령으로 함수를 명령에 직접 연결해야 합니다.

[ -n "$BASH" ] && complete -F _fzf_complete_doge -o default -o bashdefault doge

fzf의 출력을 후처리해야 한다면 다음처럼 _fzf_complete_COMMAND_post를 정의합니다.

_fzf_complete_foo() {
  _fzf_complete --multi --reverse --header-lines=3 -- "$@" < <(
    ls -al
  )
}

_fzf_complete_foo_post() {
  awk '{print $NF}'
}

[ -n "$BASH" ] && complete -F _fzf_complete_foo -o default -o bashdefault foo

fish용 퍼지 자동 완성

fish의 퍼지 자동 완성은 bash와 zsh와 다른 점이 있습니다.

  • ** 같은 트리거 시퀀스가 필요 없습니다. 대신 Shift-TAB에서 켜지며(fish의 기본 페이저 검색 모드를 대체), TAB은 fish의 기본 자동 완성 동작을 그대로 둡니다.
  • 재귀적인 파일 시스템 탐색이 아니라 fish의 기본 자동 완성 시스템으로 후보 목록을 채웁니다. 재귀 검색을 하려면 대신 CTRL-T 바인딩을 쓰세요.
  • 현재 명령줄 토큰이 와일드카드 패턴이면 와일드카드 확장 경로 목록에서 검색합니다(기본 동작인 모든 결과를 명령줄에 넣는 대신). 확장에 쉘을 쓰기 때문에 결과 수에 한계가 있습니다.
  • 지원하는 설정 변수는 FZF_COMPLETION_OPTS와 FZF_EXPANSION_OPS뿐입니다.
  • 사용자 정의 자동 완성 함수가 쓰는 함수의 이름은 fzf_complete이며, fzf 옵션만 인수로 받고, 리다이렉션된 입력 없이도 호출해 fish의 기본 자동 완성 결과를 보여 주면서 fzf 옵션만 바꿀 수도 있습니다. 다른 쉘과의 호환을 위해 fzf 옵션 뒤에 명령줄 인수로 -- $argv를 받을 수 있는 _fzf_complete 함수도 제공됩니다.

fish 자동 완성이 다루지 않는 명령은 (TAB과 Shift-TAB 모두에서 동작하는) 일반 fish 자동 완성 함수를 만드는 편이 낫고, 특정 명령에서 fzf 옵션을 바꿔야 하거나 Shift-TAB에서 다른 결과를 원할 때만 fzf 자동 완성 함수를 만드세요.

# Customize git completion
function _fzf_complete_git
  # Show header text with active branch for all git completions
  set -lx -- FZF_COMPLETION_OPTS --header="'"(git branch --show-current 2>/dev/null)"'"

  # No other changes when less than 3 arguments, or when completing options
  if not set -q argv[3]; or string match -q -- '-*' $argv[-1]
    fzf_complete
    return
  end

  # Check subcommand
  switch $argv[2]
    case checkout diff log show
      # Set preview and display all branches and commits for subcommands: checkout, diff, log, show
      begin
        git branch --all --format='%(refname:short)'
        git log --all --oneline --color=always
      end | fzf_complete --no-multi --ansi --accept-nth=1 --query=$argv[-1] --preview='git show --color=always {1}'

    case add rm mv
      # Only set preview for subcommands: add, rm, mv
      # Special characters in fish completion lists are escaped, so the r flag must be used.
      fzf_complete --preview="git diff --color=always {r1}"

    case '*'
      # No changes for other subcommands
      fzf_complete
  end
end

bash와 zsh처럼 fzf의 출력을 명령줄에 넣기 전에 후처리할 수 있습니다. _fzf_complete_COMMAND_post 또는 _fzf_post_complete_COMMAND라는 함수를 정의하면 됩니다.

function _fzf_complete_foo
  ls -sh --zero --color=always | fzf_complete --read0 --print0 --ansi --no-multi-line --header-lines=1
end

function _fzf_post_complete_foo
  while read -lz result
    string escape -n -- $result | string trim -l -c '\ ' | string split -m 1 -f 2 ' '
  end
end

Nushell용 퍼지 자동 완성

Nushell에서의 퍼지 자동 완성은 외부 완성기 메커니즘으로 동작합니다. bash와 zsh와는 몇 가지 차이가 있습니다.

  • Nushell 0.116.1 이상이 필요합니다. 자동 완성은 라인 에디터 스레드에서 실행되어 fzf가 터미널을 맡을 수 있습니다. 그래서 이전에 설정한 외부 완성기(예: Carapace)는 ** 트리거가 없을 때 그 자리에서 호출됩니다.
  • 스크립트는 로드될 때 설정된 외부 완성기를 감싼다는 점에 유의하세요. 다른 외부 완성기 설정 뒤에 로드해야 합니다. 위에서 설명한 자동 로드 설정은 config.nu 뒤에 실행되므로 이미 그렇게 됩니다.
  • Nushell 0.103.0 이상에서는 내장 명령(예: cd, ls)에 외부 완성기가 더 이상 호출되지 않습니다. **를 쓰는 퍼지 자동 완성은 외부 명령에서만 동작합니다.
  • config.nu의 $env.FZF_COMPLETERS 레코드로 사용자 정의 완성기를 정의할 수 있습니다. 항목마다 접두사와 명령 범위(span)를 받아 후보 문자열 목록이나, 사용자 정의 fzf 옵션을 담은 레코드 { candidates: [...], opts: [...] }를 돌려주는 클로저입니다.
    $env.FZF_COMPLETERS = {
        pacman: {|prefix, spans|
            let sub = $spans | skip 1 | first
            let candidates = (if ($sub =~ "-[SF]") { ^pacman -Slq | lines
            } else if ($sub =~ "-[QR]") { ^pacman -Qq | lines
            } else { [] })
            { candidates: $candidates, opts: ["--preview", "pacman -Si {}"] }
        }
    }
    
    더 많은 예시는 shell/completion-examples.nu를 보세요.
  • 다음 환경 변수를 지원합니다: FZF_COMPLETION_TRIGGER, FZF_COMPLETION_OPTS, FZF_COMPLETION_PATH_OPTS, FZF_COMPLETION_DIR_OPTS, FZF_COMPLETION_DIR_COMMANDS.

Vim 플러그인

README-VIM.md를 보세요.

고급 주제

입력 종류에 맞게 꾸미기

fzf는 범용 텍스트 필터이므로 알고리즘이 어떤 종류의 입력에도 "대체로" 잘 동작하도록 설계되었습니다. 그러나 모두에 맞는 단 하나의 해법은 없으므로 입력 종류에 따라 알고리즘과 일부 설정을 조정하고 싶을 수 있습니다. 이를 쉽게 하려고 fzf는 몇 가지 흔한 입력 유형을 위한 "스킴"을 제공합니다.

스킴설명
--scheme=default어떤 종류의 입력에도 잘 맞도록 설계한 범용 스킴
--scheme=path파일 경로에 알맞음
--scheme=history명령 기록이나 시간 순서가 중요한 입력에 알맞음

(자세한 내용은 fzf --man을 보세요)

성능

fzf는 빠릅니다. 대부분의 사용 사례에서 성능은 문제가 되지 않습니다. 다만 성능에 영향을 주는 옵션은 알아 두는 것이 좋습니다.

  • --ansi는 fzf가 입력의 ANSI 색 코드를 추출하고 해석하라고 시키며, 초기 스캔을 느리게 만듭니다. 그래서 $FZF_DEFAULT_OPTS에 넣는 것은 권하지 않습니다.
  • --nth는 fzf가 줄마다 토큰화해야 하므로 더 느려집니다.
  • 정규식 구분자보다 평범한 문자열 --delimiter를 선호해야 합니다.
  • --with-nth는 fzf가 줄마다 토큰화하고 다시 조립해야 하므로 더 느려집니다.

외부 프로그램 실행

fzf를 떠나지 않고도 외부 프로세스를 시작하는 키 바인딩(execute, execute-silent)을 만들 수 있습니다.

# Press F1 to open the file with less without leaving fzf
# Press CTRL-Y to copy the line to clipboard and aborts fzf (requires pbcopy)
fzf --bind 'f1:execute(less -f {}),ctrl-y:execute-silent(echo {} | pbcopy)+abort'

자세한 내용은 man 페이지의 KEY/EVENT BINDINGS 절을 보세요.

다른 프로세스로 바꾸기

become(...)는 위에서 설명한 execute(...)/execute-silent(...)와 비슷하지만, 명령을 실행하고 끝날 때 fzf로 돌아오는 대신 fzf를 그 명령의 새 프로세스로 바꿉니다.

fzf --bind 'enter:become(vim {})'

격으로는 동등해 보이는 명령 치환 vim "$(fzf)"와 비교하면 이 방식에는 여러 장점이 있습니다.

  • CTRL-C로 fzf를 종료해도 Vim이 빈 파일을 열지 않습니다
  • 빈 결과에서 ENTER를 눌러도 Vim이 빈 파일을 열지 않습니다
  • 공백이 들어 있는 여러 선택도 처리할 수 있습니다
    fzf --multi --bind 'enter:become(vim {+})'

공평하게 말하면 vim "$(fzf)" 대신 fzf --print0 | xargs -0 -o vim을 실행해도 위 문제는 모두 해결됩니다. 그래도 become(...)은 다른 상황에서 추가 장점이 있습니다.

  • 감싸는 스크립트 없이 여러 바인딩을 만들어 결과를 서로 다르게 처리할 수 있습니다
    fzf --bind 'enter:become(vim {}),ctrl-e:become(emacs {})'
    • 예전에는 --expect=ctrl-e를 쓰고 fzf 출력의 첫 줄을 검사해야 했습니다
  • fzf의 필드 인덱스 표현식으로 뒤이어 실행할 명령을 쉽게 만들 수 있습니다
    # Open the file in Vim and go to the line
    git grep --line-number . |
        fzf --delimiter : --nth 3.. --bind 'enter:become(vim {1} +{2})'

후보 목록 다시 불러오기

reload 동작을 키나 이벤트에 묶으면 fzf가 후보 목록을 동적으로 다시 불러오게 할 수 있습니다. 자세한 내용은 https://github.com/junegunn/fzf/issues/1750 을 보세요.

1. CTRL-R을 눌러 프로세스 목록 갱신하기

ps -ef |
  fzf --bind 'ctrl-r:reload(ps -ef)' \
      --header 'Press CTRL-R to reload' --header-lines=1 \
      --height=50% --layout=reverse

2. CTRL-D 또는 CTRL-F를 눌러 원천 바꾸기

FZF_DEFAULT_COMMAND='find . -type f' \
  fzf --bind 'ctrl-d:reload(find . -type d),ctrl-f:reload(eval "$FZF_DEFAULT_COMMAND")' \
      --height=50% --layout=reverse

3. 대화형 ripgrep 연동

다음 예는 fzf를 ripgrep의 선택 인터페이스로 씁니다. reload 동작을 change 이벤트에 묶었기 때문에, fzf에 입력할 때마다 자리 표시자 표현식 {q}로 나타낸 갱신된 검색어로 ripgrep 프로세스가 다시 시작됩니다. 또한 fzf가 2차 필터링을 하지 않도록 --disabled 옵션을 쎨다는 점에 유의하세요.

: | rg_prefix='rg --column --line-number --no-heading --color=always --smart-case' \
    fzf --bind 'start:reload:$rg_prefix ""' \
        --bind 'change:reload:$rg_prefix {q} || true' \
        --bind 'enter:become(vim {1} +{2})' \
        --ansi --disabled \
        --height=50% --layout=reverse

ripgrep이 매칭을 찾지 못하면 0이 아닌 종료 상태로 끝나고 fzf가 경고합니다. 그 경고 메시지를 없애려고 명령에 || true를 붙여 항상 0으로 끝나게 했습니다.

더 정교한 예는 "fzf를 대화형 Ripgrep 런처로 쓰기"를 보세요.

미리보기 창

--preview 옵션을 정하면 fzf는 현재 줄을 인수로 외부 프로세스를 자동으로 시작해 그 결과를 나뉜 창에 보여 줍니다. 명령은 $SHELL -c COMMAND로 $SHELL을 써서 실행합니다. 창은 마우스나 사용자 정의 키 바인딩으로 스크롤할 수 있습니다.

# {} is replaced with the single-quoted string of the focused line
fzf --preview 'cat {}'

미리보기 창은 ANSI 색을 지원하므로 Bat이나 Highlight처럼 파일 내용의 문법을 강조해 주는 어떤 프로그램이든 쓸 수 있습니다.

fzf --preview 'bat --color=always {}' --preview-window '~3'

--preview-window 옵션으로 미리보기 창의 크기, 위치, 테두리를, --color 옵션으로 글자색과 배경색을 바꿀 수 있습니다. 예를 들어,

fzf --height 40% --layout reverse --info inline --border \
    --preview 'file {}' --preview-window up,1,border-horizontal \
    --bind 'ctrl-/:change-preview-window(50%|hidden|)' \
    --color 'fg:#bbccdd,fg+:#ddeeff,bg:#334455,preview-bg:#223344,border:#778899'

전체 옵션 목록은 man 페이지(man fzf)를 보세요.

더 고급 예시는 여기에 있습니다.

💡 경고 fzf는 파일 찾기 도구가 아니라 범용 텍스트 필터이므로, $FZF_DEFAULT_OPTS에 --preview 옵션을 넣는 것은 좋은 생각이 아닙니다.

# *********************
# ** DO NOT DO THIS! **
# *********************
export FZF_DEFAULT_OPTS='--preview "bat --style=numbers --color=always --line-range :500 {}"'

# bat doesn't work with any input other than the list of files
ps -ef | fzf
seq 100 | fzf
history | fzf

이미지 미리보기

fzf는 다음 프로토콜 중 하나로 미리보기 창에 이미지를 보여 줄 수 있습니다.

자세한 내용은 bin/fzf-preview.sh 스크립트를 보세요.

fzf --preview 'fzf-preview.sh {}'

팁

.gitignore 따르기

fd, ripgrep, the silver searcher로 .gitignore를 따르면서 파일 시스템을 훑을 수 있습니다.

# Feed the output of fd into fzf
fd --type f --strip-cwd-prefix | fzf

# Setting fd as the default source for fzf
export FZF_DEFAULT_COMMAND='fd --type f --strip-cwd-prefix'

# Now fzf (w/o pipe) will use the fd command to generate the list
fzf

# To apply the command to CTRL-T as well
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"

심볼릭 링크를 따라가고 숨김 파일을 제외하지 않으려면 다음 명령을 쓰세요.

export FZF_DEFAULT_COMMAND='fd --type f --strip-cwd-prefix --hidden --follow --exclude .git'

Fish 쉘

fish의 CTRL-T 키 바인딩은 bash와 zsh와 달리 명령줄의 마지막 토큰을 재귀 검색의 루트 디렉터리로 씁니다. 예를 들어 다음 명령줄 끝에서 CTRL-T를 누르면

ls /var/

/var/ 아래의 모든 파일과 디렉터리를 나열합니다.

사용자 정의 FZF_CTRL_T_COMMAND를 쓸 때는 이 기능을 쓰도록 확장되지 않은 $dir 변수를 쓰세요. 마지막 토큰이 유효한 디렉터리가 아니면 $dir의 기본값은 .입니다. 예:

set -g FZF_CTRL_T_COMMAND "command find -L \$dir -type f 2> /dev/null | sed '1d; s#^\./##'"

fzf 테마 놀이터

Vitor Mello가 만든 fzf 테마 놀이터는 fzf 테마를 대화형으로 만들어 볼 수 있는 웹페이지입니다.

관련 프로젝트

https://github.com/junegunn/fzf/wiki/Related-projects

라이선스

MIT 라이선스 (MIT)

Copyright (c) 2013-2026 Junegunn Choi

굴즈

fzf 티셔츠, 머그컵, 스티커는 commitgoods.com/collections/fzf에서 만나보세요.

후원자 :heart:

fzf를 계속 개선할 수 있도록 해 주는 이 프로젝트의 모든 후원자분들께 감사드립니다.

이 프로젝트를 후원하고 싶다면 https://github.com/sponsors/junegunn 을 방문해 주세요.

저장소

junegunn/fzf

평점

–평가 0개 기준
5점
0
4점
0
3점
0
2점
0
1점
0