fzf 사용법: 긴 파일 목록을 빠른 선택 도구로 바꾸기

fzf는 표준 입력으로 받은 후보 목록에서 원하는 항목을 대화형으로 고르는 범용 fuzzy finder입니다. 파일 내용을 검색하는 ripgrep이나 파일 목록을 만드는 fd와는 역할이 다릅니다. 기존 명령이 만든 목록에 선택 인터페이스를 붙이고 싶을 때 특히 유용합니다.

인기와 유지보수

공식 GitHub API를 2026년 10월 20일 조회한 결과 junegunn/fzf는 스타 83,687개, archived=false였습니다. 최근 push는 10월 17일이며 최신 릴리스는 10월 11일 공개된 v0.74.5입니다. 라이선스는 MIT입니다. 스타는 사용자의 관심 지표이지 보안 감사나 특정 작업의 성능을 보증하지 않습니다. 이번 글은 당일 인기·유지보수 확인에 근거한 소개이지 오늘 출시된 제품이라는 뜻이 아닙니다.

설치 전 준비

아래 명령은 공식 README를 기준으로 정리했으며 직접 설치·실행하지 않았습니다. macOS 또는 Linux의 Homebrew 환경을 중심으로 설명합니다. 이미 Homebrew가 설치되어 있고 패키지 설치가 허용된 계정이어야 합니다. Windows는 공식 README의 Winget·Scoop 등 별도 설치 경로와 셸 차이를 확인하세요. 배포판 패키지는 최신 릴리스보다 늦을 수 있으므로 설치 후 버전을 먼저 확인합니다.

brew install fzf
fzf --version
printf '%s\n' apple apricot banana | fzf --height 40% --reverse

마지막 명령에서 ap처럼 일부 글자를 입력하면 관련 후보가 좁혀집니다. Enter로 항목을 선택하면 선택 문자열이 표준 출력에 나오고 Esc로 취소할 수 있습니다. --height 40%는 화면 전체 대신 일부 높이를 쓰고 --reverse는 입력 위치와 목록 방향을 바꿉니다. 이 단계에서는 셸 시작 파일을 수정하지 않습니다.

Git 파일 선택 예제

다음은 이미 복제한 신뢰할 수 있는 Git 저장소에서 추적 중인 파일 경로를 골라 출력하는 예입니다. Git도 설치되어 있어야 합니다. 파일을 수정하거나 삭제하지 않으므로 선택 동작부터 익히기 좋습니다.

git ls-files | fzf --height 40% --reverse --query src

--query는 처음 검색창에 들어갈 문자열일 뿐 검색 범위를 파일 내용으로 바꾸지 않습니다. src가 들어간 경로를 선택해 출력 경로가 실제 저장소 파일과 일치하는지 확인하세요. 일반적인 줄 단위 예제이므로 개행 문자가 포함된 특수 파일명을 다루는 자동화에는 그대로 쓰지 않는 편이 좋습니다. 선택 결과를 곧바로 삭제 명령에 연결하지 않는 것이 안전합니다.

실무에서는 선택 결과를 검토한 뒤 편집기나 다른 명령에 전달할 수 있습니다. 공식 README에는 --print0와 xargs -0를 이용하는 예와 Enter를 외부 명령 실행에 연결하는 예가 있습니다. 플랫폼마다 xargs 옵션이 다르므로 이 글의 출력 전용 예제로 시작한 뒤 사용 운영체제의 문서를 확인해 확장하세요.

검색과 옵션 선택

기본 fuzzy 검색은 글자가 연속되지 않아도 후보를 좁힙니다. 공식 문서의 확장 검색에서는 ^로 시작 부분, $로 끝 부분을 제한하고 !로 특정 패턴을 제외할 수 있습니다. 따라서 단순한 파일 이름 탐색과 정확히 정해진 이름 확인을 구분해야 합니다. 선택된 후보가 의도한 대상인지 최종 출력에서 다시 확인하는 습관이 중요합니다.

여러 항목을 선택하려면 --multi를 사용할 수 있지만 이후 명령이 여러 줄을 어떻게 처리하는지 함께 설계해야 합니다. 공통 화면 옵션을 매번 입력하기 싫다면 FZF_DEFAULT_OPTS를 사용할 수 있습니다. 처음에는 현재 셸에만 설정하여 기존 환경과 충돌하지 않는지 확인하는 편이 좋습니다.

export FZF_DEFAULT_OPTS='--height 40% --reverse'
printf '%s\n' alpha beta gamma | fzf
unset FZF_DEFAULT_OPTS

셸 통합은 별도 선택

Bash·Zsh 등에서는 키 바인딩과 자동 완성을 활성화할 수 있습니다. 예를 들어 공식 Zsh 통합은 source <(fzf --zsh)입니다. 이를 영구 적용하려면 기존 .zshrc를 백업하고 해당 줄만 추가해야 합니다. 이 글의 최소 예에는 필요하지 않습니다. 여러 플러그인 관리자가 이미 fzf를 불러오는 환경에서는 중복 로딩을 피하세요.

명령 기록을 선택하는 기능은 로컬 셸 기록을 화면에 표시할 수 있습니다. 터미널 공유나 녹화 중에는 기록에 비밀이 없는지 먼저 확인하세요. 후보 문자열 자체는 데이터지만 --preview나 실행 바인딩에 지정한 프로그램은 실제로 동작합니다. 신뢰하지 않는 목록을 임의의 셸 명령에 연결하거나 관리자 권한으로 실행하지 마세요. 단순 목록 선택과 외부 프로그램 실행은 서로 다른 권한 경계입니다.

비용과 데이터 경계

fzf 자체는 로컬에서 동작하는 오픈소스 바이너리이며 기본 선택 기능에 유료 API 계정은 필요하지 않습니다. 다만 설치 시 패키지 다운로드가 발생하고, 사용자가 연결한 preview나 외부 명령은 네트워크·파일 접근을 할 수 있습니다. MIT 라이선스의 저작권·허가 고지 조건도 배포 시 확인해야 합니다. 원격 개발 환경에서는 목록과 터미널 화면이 어느 호스트에서 처리되는지도 구분하세요.

오류와 제거

command not found면 설치 성공 여부와 PATH, 현재 셸을 확인합니다. 키 바인딩만 동작하지 않으면 바이너리 재설치보다 통합 스크립트 로딩과 버전을 먼저 확인하세요. 후보가 비면 앞단의 git ls-files 또는 printf를 단독 실행해 입력이 실제로 나오는지 봅니다. 화면이 예상과 다르면 FZF_DEFAULT_OPTS와 플러그인이 넣은 옵션을 조사하고 새 셸에서 최소 예를 재현합니다.

도입을 취소할 때는 자신이 추가한 셸 통합 한 줄과 환경변수만 제거하고 새 셸을 엽니다. Homebrew로 설치했다면 brew uninstall fzf로 패키지를 제거할 수 있습니다. 다른 도구가 의존하는지 먼저 확인하고 셸 설정 파일 전체를 덮어쓰지 마세요. fzf는 원래 파일 목록 생성 명령을 대체하지 않으므로 기존 Git·find 기반 작업 흐름을 유지한 채 점진적으로 사용할 수 있습니다.

출처