{"id":13588923,"url":"https://github.com/natecraddock/zf","last_synced_at":"2025-05-15T10:07:11.111Z","repository":{"id":41550654,"uuid":"399270517","full_name":"natecraddock/zf","owner":"natecraddock","description":"a commandline fuzzy finder and zig module designed for filtering filepaths","archived":false,"fork":false,"pushed_at":"2025-04-28T22:03:54.000Z","size":317,"stargazers_count":536,"open_issues_count":8,"forks_count":22,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-28T23:25:00.339Z","etag":null,"topics":["cli","fuzzy","fuzzy-search","library","unix","zig","zig-library","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/natecraddock.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-08-23T23:02:10.000Z","updated_at":"2025-04-28T22:03:58.000Z","dependencies_parsed_at":"2022-07-08T05:22:50.068Z","dependency_job_id":"e5e3eec7-66bc-431f-b188-fca5ce178793","html_url":"https://github.com/natecraddock/zf","commit_stats":{"total_commits":312,"total_committers":7,"mean_commits":44.57142857142857,"dds":"0.019230769230769273","last_synced_commit":"bb27a917c3513785c6a91f0b1c10002a5029cacc"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fzf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fzf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fzf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fzf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/natecraddock","download_url":"https://codeload.github.com/natecraddock/zf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319720,"owners_count":22051073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","fuzzy","fuzzy-search","library","unix","zig","zig-library","zig-package"],"created_at":"2024-08-01T15:07:01.529Z","updated_at":"2025-05-15T10:07:06.091Z","avatar_url":"https://github.com/natecraddock.png","language":"Zig","readme":"# zf\n\n[![shield showing current tests status](https://github.com/natecraddock/zf/actions/workflows/tests.yml/badge.svg)](https://github.com/natecraddock/zf/actions/workflows/tests.yml) [![Packaging status](https://repology.org/badge/tiny-repos/zf.svg)](https://repology.org/project/zf/versions)\n\nzf is a fuzzy finder that excels at filtering filepaths:\n\n* [because filenames are usually unique](https://nathancraddock.com/blog/in-search-of-a-better-finder/#data-collection), matches on filenames are prioritized\n* when the query resembles a file path, zf [uses heuristics for a more accurate match](#strict-path-matching)\n\nThe goal of zf is to be more accurate than other fuzzy finders when filtering filepaths, but it also functions as a general-purpose fuzzy finder.\n\nzf is also available as an allocation-free library for fuzzy filtering. [See the docs for more info](https://github.com/natecraddock/zf/blob/main/doc/lib.md).\n\n[Try zf online!](https://nathancraddock.com/zf-playground/)\n\n## Demo\n\nhttps://user-images.githubusercontent.com/7967463/225198950-a6ab568f-644f-40a1-b202-c12a35aeaed8.mp4\n\n## Features\n\n* fuzzy matching algorithm designed for file paths\n* refine search results with whitespace separated query terms\n* smartcase (case insensitive unless the query contains uppercase letters)\n* multiselect to output multiple selected lines\n* preview window\n* Zig and C libraries for the zf ranking algorithm\n\n## Docs\n\n* [Usage Documentation](https://github.com/natecraddock/zf/blob/main/doc/zf.md)\n* [Library Documentation](https://github.com/natecraddock/zf/blob/main/doc/lib.md)\n\n## Why use zf?\n\nzf was designed knowing that a frequent use case for fuzzy finders is filtering filepaths. It also works great for any arbitrary string, but it is especially good at filtering filepaths with precision.\n\nSpecifically,\n\n* Matches on filenames are prioritized over filepath matches\n* Matches on the beginning of a word are prioritized over matches in the middle of a word\n* Non-sequential character matches are penalized\n* Strict path matching offers even more precision\n\nHere are some concrete examples.\n\n### Filename priority\n\nThe query is matched first on the filename and then on the path if the filename doesn't match. This example comes from Blender's source code, and was my original inspiration for designing zf.\n\n```text\n\u003e make\n./GNUmakefile\n./source/blender/makesdna/DNA_genfile.h\n./source/blender/makesdna/intern/dna_genfile.c\n./source/blender/makesrna/intern/rna_cachefile.c\n./source/blender/makesdna/DNA_curveprofile_types.h\n```\n\nFzf and fzy both rank `source/blender/makesdna/DNA_genfile.h` first in the results, with `GNUmakefile` 10 items down the list.\n\n### Space-separated tokens\n\nBut not every filename is unique. Sometimes there are codebases where there are many files with the same or similar names, like an `__init__.py` in Python, or `.c` and `.h` file pairs in C. In zf each space separated query term is used to narrow down the results. Imagine searching for an `__init__.py` file in a Python project.\n\n```text\n\u003e init\n./__init__.py\n./ui/__init__.py\n./data/__init__.py\n./config/__init__.py\n```\n\nAt this point you can either move the selection down with \u003ckdb\u003eDown\u003c/kbd\u003e or `c-n` to find\n`./config/__init__.py`, or you can add a new token to the query string.\n\n```text\n\u003e init c\n./config/__init__.py\n```\n\nTreating the query string as a sequence of tokens makes filtering more\nefficient.\n\n### Strict path matching\n\nThis feature is a \"do what I mean\" feature, more easily used than explained. When the query looks like a path (contains at least one path separator) strict path matching is enabled.\n\nPath segments are the portions of a path delimited by path separators. `foo/bar` has segments `foo` and `bar`. With strict path matching the path segments of the query token must not span across path segments in the candidate. As an example, the query `foo/` would match `foo/bar/` but not `fo/obar/` because the characters `\"foo\"` must appear in a single path segment.\n\nThis is useful for narrowing down results when you know the exact path structure of your files. With the following paths\n\n```\n./app/models/foo/bar/baz.rb\n./app/models/foo/bar-baz.rb\n./app/models/foo-bar-baz.rb\n./app/monsters/dungeon/foo/bar/baz.rb\n```\n\nStrict path matching ensures that the intended path structure is found.\n\n```\n\u003e a/m/f/b/baz\n./app/models/foo/bar/baz.rb\n```\n\nIn other fuzzy finders the string `app/monsters/dungeon/foo/bar/baz.rb` is also included in the results. Strict path matching prevents this because there is a slash between `onsters/dungeon` and nothing in the query matches the `dungeon` segment.\n\nTo end strict path matching, just add a space to start a new query token.\n\n## Installation\n\n### Arch Linux\n\nAn [AUR package](https://aur.archlinux.org/packages/zf/) is available.\n\n### Void Linux\n\nInstall from official repository\n\n```\nsudo xbps-install zf\n```\n\n### macOS\n\nInstall with Homebrew\n\n```\nbrew install zf\n```\n\n### Nix\n\n```\nnix-env --install zf\n```\n\n### Binaries\n\nEach [release](https://github.com/natecraddock/zf/releases/latest) has binaries attached for macOS and Linux.\n\n### Building from source\n\nFor compatibility with system package managers, zf targets the latest stable release of Zig.\n\n```\ngit clone https://github.com/natecraddock/zf\ncd zf\nzig build -Doptimize=ReleaseSafe --summary all\n```\n\nThe executable will be created in `./zig-out/bin/zf`. For debug builds omit `-Doptimize=ReleaseSafe`.\n\n## Integrations\n\nWould you like to use zf in an editor? Try one of the following plugins\n\n* [zf.vim](https://github.com/ratfactor/zf.vim): zf integrated with vim for\n  fuzzy file finding. Similar to fzf.vim.\n* [telescope-zf-native.nvim](https://github.com/natecraddock/telescope-zf-native.nvim)\n  a neovim [telescope](https://github.com/nvim-telescope/telescope.nvim)\n  extension to override the default Lua sorter with zf.\n\n## Contributing\n\nI am open to contributions of all kinds, but be aware that I want to keep zf small and easy to maintain.\n","funding_links":[],"categories":["Zig","cli","Command Line Tools"],"sub_categories":["Other"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatecraddock%2Fzf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnatecraddock%2Fzf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatecraddock%2Fzf/lists"}