{"id":13569874,"url":"https://github.com/tavianator/bfs","last_synced_at":"2025-05-14T18:05:25.448Z","repository":{"id":4025203,"uuid":"37432557","full_name":"tavianator/bfs","owner":"tavianator","description":"A breadth-first version of the UNIX find command","archived":false,"fork":false,"pushed_at":"2025-04-12T15:54:32.000Z","size":3221,"stargazers_count":1038,"open_issues_count":6,"forks_count":40,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-13T13:16:24.567Z","etag":null,"topics":["breadth-first-search","bsd","command-line","directory-tree","filesystem","find","linux","macos","unix"],"latest_commit_sha":null,"homepage":"https://tavianator.com/projects/bfs.html","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tavianator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"tavianator"}},"created_at":"2015-06-14T22:46:19.000Z","updated_at":"2025-04-12T15:54:36.000Z","dependencies_parsed_at":"2024-02-19T04:25:05.991Z","dependency_job_id":"996df375-9273-4947-acd8-8c1ec9d801da","html_url":"https://github.com/tavianator/bfs","commit_stats":{"total_commits":1964,"total_committers":25,"mean_commits":78.56,"dds":"0.017820773930753542","last_synced_commit":"b00341a45238d383fa27289a53798eef856092bb"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tavianator%2Fbfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tavianator%2Fbfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tavianator%2Fbfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tavianator%2Fbfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tavianator","download_url":"https://codeload.github.com/tavianator/bfs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"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":["breadth-first-search","bsd","command-line","directory-tree","filesystem","find","linux","macos","unix"],"created_at":"2024-08-01T14:00:45.361Z","updated_at":"2025-05-14T18:05:20.435Z","avatar_url":"https://github.com/tavianator.png","language":"C","funding_links":["https://github.com/sponsors/tavianator"],"categories":["C","\u003ca name=\"find\"\u003e\u003c/a\u003eFile finding (alternatives to find)","Other"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003e\n\u003ccode\u003ebfs\u003c/code\u003e\n\u003cbr clear=\"all\"\u003e\n\u003ca href=\"https://github.com/tavianator/bfs/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/tag/tavianator/bfs?label=version\" alt=\"Version\" align=\"left\"\u003e\u003c/a\u003e\n\u003ca href=\"/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-0BSD-blue.svg\" alt=\"License\" align=\"left\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/tavianator/bfs/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/tavianator/bfs/actions/workflows/ci.yml/badge.svg\" alt=\"CI Status\" align=\"right\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/tavianator/bfs\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/github/tavianator/bfs?token=PpBVuozOVC\" alt=\"Code coverage\" align=\"right\"/\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\n**[Features]   •   [Installation]   •   [Usage]   •   [Building]   •   [Contributing]   •   [Changelog]**\n\n[Features]: #features\n[Installation]: #installation\n[Usage]: /docs/USAGE.md\n[Building]: /docs/BUILDING.md\n[Contributing]: /docs/CONTRIBUTING.md\n[Changelog]: /docs/CHANGELOG.md\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/tavianator/bfs/gh-pages/animation-dark.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/tavianator/bfs/gh-pages/animation-light.svg\"\u003e\n  \u003cimg alt=\"Screencast\" src=\"https://raw.githubusercontent.com/tavianator/bfs/gh-pages/animation-light.svg\"\u003e\n\u003c/picture\u003e\n\u003cp\u003e\u003c/p\u003e\n\n\u003c/div\u003e\n\n`bfs` is a variant of the UNIX `find` command that operates [**breadth-first**](https://en.wikipedia.org/wiki/Breadth-first_search) rather than [**depth-first**](https://en.wikipedia.org/wiki/Depth-first_search).\nIt is otherwise compatible with many versions of `find`, including\n\n\u003cdiv align=\"center\"\u003e\n\n**[POSIX]   •   [GNU]   •   [FreeBSD]   •   [OpenBSD]   •   [NetBSD]   •   [macOS]**\n\n[POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/utilities/find.html\n[GNU]: https://www.gnu.org/software/findutils/\n[FreeBSD]: https://www.freebsd.org/cgi/man.cgi?find(1)\n[OpenBSD]: https://man.openbsd.org/find.1\n[NetBSD]: https://man.netbsd.org/find.1\n[macOS]: https://ss64.com/osx/find.html\n\n\u003c/div\u003e\n\nIf you're not familiar with `find`, the [GNU find manual](https://www.gnu.org/software/findutils/manual/html_mono/find.html) provides a good introduction.\n\n\nFeatures\n--------\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ebfs\u003c/code\u003e operates breadth-first, which typically finds the file(s) you're looking for faster.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nImagine the following directory tree:\n\n\u003cpre\u003e\nhaystack\n├── deep\n│   └── 1\n│       └── 2\n│           └── 3\n│               └── 4\n│                   └── ...\n└── shallow\n    └── \u003cstrong\u003eneedle\u003c/strong\u003e\n\u003c/pre\u003e\n\n`find` will explore the entire `deep` directory tree before it ever gets to the `shallow` one that contains what you're looking for.\nOn the other hand, `bfs` lists files from shallowest to deepest, so you never have to wait for it to explore an entire unrelated subtree.\n\n\u003ctable\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\u003cth\u003e\u003ccode\u003ebfs\u003c/code\u003e\u003c/th\u003e\u003cth\u003e\u003ccode\u003efind\u003c/code\u003e\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"506\" valign=\"top\"\u003e\n\n```console\n$ bfs haystack\nhaystack\nhaystack/deep\nhaystack/shallow\nhaystack/deep/1\nhaystack/shallow/needle\n...\n```\n\n\u003c/td\u003e\n\u003ctd width=\"506\" valign=\"top\"\u003e\n\n```console\n$ find haystack\nhaystack\nhaystack/deep\nhaystack/deep/1\nhaystack/deep/1/2\nhaystack/deep/1/2/3\nhaystack/deep/1/2/3/4\n...\nhaystack/shallow\nhaystack/shallow/needle\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ebfs\u003c/code\u003e tries to be easier to use than \u003ccode\u003efind\u003c/code\u003e, while remaining compatible.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nFor example, `bfs` is less picky about where you put its arguments:\n\n\u003ctable\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\u003cth\u003e\u003ccode\u003ebfs\u003c/code\u003e\u003c/th\u003e\u003cth\u003e\u003ccode\u003efind\u003c/code\u003e\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"506\"\u003e\n\n```console\n$ bfs -L -name 'needle' haystack\nhaystack/needle\n\n$ bfs haystack -L -name 'needle'\nhaystack/needle\n\n$ bfs -L haystack -name 'needle'\nhaystack/needle\n```\n\n\u003c/td\u003e\n\u003ctd width=\"506\"\u003e\n\n```console\n$ find -L -name 'needle' haystack\nfind: paths must precede expression: haystack\n\n$ find haystack -L -name 'needle'\nfind: unknown predicate `-L'\n\n$ find -L haystack -name 'needle'\nhaystack/needle\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ebfs\u003c/code\u003e gives helpful errors and warnings.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nFor example, `bfs` will detect and suggest corrections for typos:\n\n```console\n$ bfs -nam needle\nbfs: error: bfs -nam needle\nbfs: error:     ~~~~\nbfs: error: Unknown argument; did you mean -name?\n```\n\n`bfs` also includes a powerful static analysis to help catch mistakes:\n\n```console\n$ bfs -print -name 'needle'\nbfs: warning: bfs -print -name needle\nbfs: warning:            ~~~~~~~~~~~~\nbfs: warning: The result of this expression is ignored.\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ebfs\u003c/code\u003e adds some options that make common tasks easier.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nFor example, the `-exclude` operator skips over entire subtrees whenever an expression matches.\n`-exclude` is both more powerful and easier to use than the standard `-prune` action; compare\n\n\u003cpre\u003e\n$ bfs -name config \u003cstrong\u003e-exclude -name .git\u003c/strong\u003e\n\u003c/pre\u003e\n\nto the equivalent\n\n\u003cpre\u003e\n$ find \u003cstrong\u003e! \\( -name .git -prune \\)\u003c/strong\u003e -name config\n\u003c/pre\u003e\n\nAs an additional shorthand, `-nohidden` skips over all hidden files and directories.\nSee the [usage documentation](/docs/USAGE.md#extensions) for more about the extensions provided by `bfs`.\n\u003c/details\u003e\n\n\nInstallation\n------------\n\n\u003cdetails open\u003e\n\u003csummary\u003e\n\u003ccode\u003ebfs\u003c/code\u003e may already be packaged for your operating system.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\n\u003ctable\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\u003cth\u003eLinux\u003c/th\u003e\u003cth\u003emacOS\u003c/th\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd width=\"506\" valign=\"top\" rowspan=\"3\"\u003e\n\n\u003cpre\u003e\n\u003cstrong\u003e\u003ca href=\"https://pkgs.alpinelinux.org/packages?name=bfs\"\u003eAlpine Linux\u003c/a\u003e\u003c/strong\u003e\n# apk add bfs\n\n\u003cstrong\u003e\u003ca href=\"https://archlinux.org/packages/extra/x86_64/bfs/\"\u003eArch Linux\u003c/a\u003e\u003c/strong\u003e\n# pacman -S bfs\n\n\u003cstrong\u003e\u003ca href=\"https://packages.debian.org/sid/bfs\"\u003eDebian\u003c/a\u003e/\u003ca href=\"https://packages.ubuntu.com/kinetic/bfs\"\u003eUbuntu\u003c/a\u003e\u003c/strong\u003e\n# apt install bfs\n\n\u003cstrong\u003e\u003ca href=\"https://src.fedoraproject.org/rpms/bfs\"\u003eFedora Linux\u003c/a\u003e\u003c/strong\u003e\n# dnf install bfs\n\n\u003cstrong\u003e\u003ca href=\"https://packages.gentoo.org/packages/sys-apps/bfs\"\u003eGentoo\u003c/a\u003e\u003c/strong\u003e\n# emerge sys-apps/bfs\n\n\u003cstrong\u003e\u003ca href=\"https://packages.guix.gnu.org/packages/bfs/\"\u003eGNU Guix\u003c/a\u003e\u003c/strong\u003e\n# guix install bfs\n\n\u003cstrong\u003e\u003ca href=\"https://search.nixos.org/packages?channel=unstable\u0026show=bfs\u0026from=0\u0026size=1\u0026sort=relevance\u0026type=packages\u0026query=bfs\"\u003eNixOS\u003c/a\u003e\u003c/strong\u003e\n# nix-env -i bfs\n\n\u003cstrong\u003e\u003ca href=\"https://voidlinux.org/packages/?arch=x86_64\u0026q=bfs\"\u003eVoid Linux\u003c/a\u003e\u003c/strong\u003e\n# xbps-install -S bfs\n\u003c/pre\u003e\n\n\u003c/td\u003e\n\u003ctd width=\"506\" valign=\"top\"\u003e\n\n\u003cpre\u003e\n\u003cstrong\u003e\u003ca href=\"https://formulae.brew.sh/formula/bfs\"\u003eHomebrew\u003c/a\u003e\u003c/strong\u003e\n$ brew install bfs\n\n\u003cstrong\u003e\u003ca href=\"https://ports.macports.org/port/bfs/\"\u003eMacPorts\u003c/a\u003e\u003c/strong\u003e\n# port install bfs\n\u003c/pre\u003e\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\u003cth height=\"1\"\u003eBSD\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"506\" valign=\"top\"\u003e\n\n\u003cpre\u003e\n\u003cstrong\u003e\u003ca href=\"https://www.freshports.org/sysutils/bfs\"\u003eFreeBSD\u003c/a\u003e\u003c/strong\u003e\n# pkg install bfs\n\n\u003cstrong\u003e\u003ca href=\"https://openports.pl/path/sysutils/bfs\"\u003eOpenBSD\u003c/a\u003e\u003c/strong\u003e\n# pkg_add bfs\n\u003c/pre\u003e\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nTo build \u003ccode\u003ebfs\u003c/code\u003e from source, you may need to install some dependencies.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nThe only absolute requirements for building `bfs` are a C compiler, [GNU make](https://www.gnu.org/software/make/), and [Bash](https://www.gnu.org/software/bash/).\nThese are installed by default on many systems, and easy to install on most others.\nRefer to your operating system's documentation on building software.\n\n`bfs` also depends on some system libraries for some of its features.\nHere's how to install them on some common platforms:\n\n\u003cpre\u003e\n\u003cstrong\u003eAlpine Linux\u003c/strong\u003e\n# apk add acl{,-dev} attr libcap{,-dev} liburing-dev oniguruma-dev\n\n\u003cstrong\u003eArch Linux\u003c/strong\u003e\n# pacman -S acl attr libcap liburing oniguruma\n\n\u003cstrong\u003eDebian/Ubuntu\u003c/strong\u003e\n# apt install acl libacl1-dev attr libattr1-dev libcap2-bin libcap-dev liburing-dev libonig-dev\n\n\u003cstrong\u003eFedora\u003c/strong\u003e\n# dnf install acl libacl-devel attr libcap-devel liburing-devel oniguruma-devel\n\n\u003cstrong\u003eNixOS\u003c/strong\u003e\n# nix-env -i acl attr libcap liburing oniguruma\n\n\u003cstrong\u003eVoid Linux\u003c/strong\u003e\n# xbps-install -S acl-{devel,progs} attr-progs libcap-{devel,progs} liburing-devel oniguruma-devel\n\n\u003cstrong\u003eHomebrew\u003c/strong\u003e\n$ brew install oniguruma\n\n\u003cstrong\u003eMacPorts\u003c/strong\u003e\n# port install oniguruma6\n\n\u003cstrong\u003eFreeBSD\u003c/strong\u003e\n# pkg install oniguruma\n\u003c/pre\u003e\n\nThese dependencies are technically optional, though strongly recommended.\nSee the [build documentation](/docs/BUILDING.md#dependencies) for how to disable them.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nOnce you have the dependencies, you can build \u003ccode\u003ebfs\u003c/code\u003e.\n\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\nDownload one of the [releases](https://github.com/tavianator/bfs/releases) or clone the [git repo](https://github.com/tavianator/bfs).\nThen run\n\n    $ ./configure\n    $ make\n\nThis will build the `./bin/bfs` binary.\nRun the test suite to make sure it works correctly:\n\n    $ make check\n\nIf you're interested in speed, you may want to build the release version instead:\n\n    $ ./configure --enable-release\n    $ make\n\nFinally, if you want to install it globally, run\n\n    # make install\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftavianator%2Fbfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftavianator%2Fbfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftavianator%2Fbfs/lists"}