{"id":16059628,"url":"https://github.com/jhbabon/scout","last_synced_at":"2025-04-09T12:09:32.359Z","repository":{"id":20915194,"uuid":"88588898","full_name":"jhbabon/scout","owner":"jhbabon","description":"Friendly fuzzy finder made with rust","archived":false,"fork":false,"pushed_at":"2023-09-19T16:29:15.000Z","size":15009,"stargazers_count":98,"open_issues_count":5,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T11:03:32.725Z","etag":null,"topics":["async","cli","fuzzy-search","fuzzyfinder","rust","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/jhbabon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2017-04-18T06:16:02.000Z","updated_at":"2025-03-07T14:20:53.000Z","dependencies_parsed_at":"2024-10-26T21:19:41.807Z","dependency_job_id":"da171d99-1c1a-4449-b93a-d1a23c718398","html_url":"https://github.com/jhbabon/scout","commit_stats":{"total_commits":318,"total_committers":3,"mean_commits":106.0,"dds":"0.16352201257861632","last_synced_commit":"66ea0301f9b8f20ba86aa8b4f94d1ce94f23cc80"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhbabon%2Fscout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhbabon%2Fscout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhbabon%2Fscout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhbabon%2Fscout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhbabon","download_url":"https://codeload.github.com/jhbabon/scout/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036067,"owners_count":21037092,"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":["async","cli","fuzzy-search","fuzzyfinder","rust","terminal","tui"],"created_at":"2024-10-09T04:01:28.148Z","updated_at":"2025-04-09T12:09:32.336Z","avatar_url":"https://github.com/jhbabon.png","language":"Rust","funding_links":[],"categories":["Search"],"sub_categories":[],"readme":"# Scout\n\n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fjhbabon%2Fscout%2Fbadge%3Fref%3Dmain\u0026style=flat-square)](https://actions-badge.atrox.dev/jhbabon/scout/goto?ref=main)\n\nScout is a small fuzzy finder for your terminal built in [Rust][rustlang].\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/demo.gif\" style=\"max-width=100%\" alt=\"scout demo\" /\u003e\n\u003c/p\u003e\n\nIt is heavily inspired by other tools like [selecta][selecta] and the omnipresent [fzf][fzf].\n\nThe main features of `scout` are:\n\n* Async architecture thanks to the [`async-std`][asyncstd] library. This means that it won't block the UI to wait for the `STDIN` to finish, you can start typing right away.\n* Customizable UI. You can change the colors and symbols of all the elements in the UI.\n* Fast fuzzy matching algorithm based on the [`fuzzaldrin-plug`][fuzzaldrin-plus] package used in the Atom editor.\n\n## WARNING\n\nThis tool uses the system's pseudo terminal located in `/dev/tty` to print the UI and capture inputs, which means it only works on UNIX systems (like Linux or macOS) as far as I know.\n\n## Installation\n\n### Install via release packages\n\nEach release, since version `v1.0.0` (not included), has a package with `scout` compiled for different architectures. You can try to donwload and install the package that match your architecture.\n\nYou can find the releases in their [GitHub page][github-releases].\n\n### Install via cargo\n\nScout is in the main [crates][] repository, so you can install it with `cargo`:\n\n```\n$ cargo install scout\n```\n\nRemember to put `cargo` bin path to the main `$PATH` env variable:\n\n```\nexport PATH=$PATH:~/.cargo/bin\n```\n\n### Install via homebrew (macOS only)\n\nYou can use my custom tap repository to install `scout` with [homebrew](https://brew.sh):\n\n```\n$ brew tap jhbabon/tap\n$ brew install scout\n```\n\n### Install via MacPorts (macOS)\n\nOn macOS, you can also install `scout` via [MacPorts](https://www.macports.org):\n\n```\n$ sudo port install scout\n```\n\n### Install from source\n\nSince `scout` is a Rust project, you will need to have Rust installed in your system. Check [`rustup`][rustup] to see how to install Rust. To build `scout` you will need Rust `v1.43` or higher.\n\nClone the repository and run `cargo install` from it:\n\n```\n$ git clone https://github.com/jhbabon/scout.git path/to/scout\n$ cd path/to/scout\n$ cargo install --path .\n```\n\nYou can also run `cargo build --release` if you just want to play with it. The binary file will be in the `./target/release/scout` path.\n\n## Usage\n\nThe main idea behind `scout`, or any other fuzzy finder, is to filter a list of items (for example a list of paths to files) and then do something with the selection. For that you run a command, pipe its output to `scout` and then pipe `scout`'s output to another command.\n\nFor example, you can try to find a file and `cat` its contents:\n\n```\n$ find * -type f | scout | xargs -n1 cat\n```\n\n`scout` has a set of options that allows you to control how it looks. It also supports a set of control sequences and keys to navigate the UI.\n\nYou can see these options in the main help of the program with the `--help` flag:\n\n```\nscout 2.0.0\nYour friendly fuzzy finder\n\nUSAGE:\n    scout [FLAGS] [OPTIONS]\n\nFLAGS:\n    -f, --full-screen    Show scout in full screen (default)\n    -h, --help           Prints help information\n    -i, --inline         Show scout under the current line\n    -p, --preserve-order Do not sort the result by score\n    -v, --version        Prints version information\n\nOPTIONS:\n    -c, --config \u003cFILE\u003e     Uses a custom config file\n    -l, --lines \u003cLINES\u003e     Number of lines to display in inline mode, including prompt\n    -s, --search \u003cQUERY\u003e    Start searching with the given query\n\nSUPPORTED KEYS:\n    - Enter to select the current highlighted match and print it to STDOUT\n    - ^u to clear the prompt\n    - ^n or Down arrow key to select the next match\n    - ^p or Up arrow key to select the previous match\n    - ^e to go to the end of the prompt\n    - ^a to go to the beginning of the prompt\n    - Left arrow key to move the cursor to the left in the prompt\n    - Right arrow key to move the cursor to the right in the prompt\n    - ESC to quit without selecting a match\n\nEXAMPLE:\n    $ find * -type f | scout\n\n    # Pass an initial query to start filtering right away\n    $ find * -type f | scout --search=foo\n\n    # Use a custom config file\n    $ find * -type f | scout --config=\"./config.toml\"\n\n    # Select a git branch and check it out with an inline menu\n    $ git branch --sort=-committerdate| cut -c 3- | scout -i -p | xargs git checkout\n```\n\n### Configuration\n\nYou can configure `scout`'s UI with a config file. By default the program will try to find this file in the path `$HOME/.config/scout.toml`, but you can pass a custom path with the `--config` option.\n\nThis is how `scout` looks like without any defined style:\n\n\u003cimg src=\"media/default.png\" style=\"max-width=100%\" alt=\"default UI\" /\u003e\n\nThis is an example of a configuration file with all the possible settings:\n\n```toml\n# General screen options\n[screen]\n# Display inline (under the current line) or in full screen\nmode = \"inline\" # or \"full\"\n# Max number of lines to display the whole UI. Only used in inline mode\nlines = 8\n\n# The prompt is where you type your query\n[prompt]\n# Symbol displayed before the text you will type\nsymbol = \"❯ \"\n# Style for the query (your text)\nstyle = \"bold underline\"\n# Style for the symbol\nstyle_symbol = \"fg:green\"\n\n# The gauge indicates the number of matches vs total number of lines\n[gauge]\n# Symbol used to separate both numbers\nsymbol = \" ⚡\"\n# Text before the numbers\nprefix = \"- \"\n# Style for the numbers\nstyle = \"fg:bright-yellow\"\n\n# A candidate is an item in the list that is not selected\n[candidate]\n# Symbol displayed before the candidate's text\nsymbol = \"❔ \"\n# Style for the candidate's text\nstyle = \"bg:red fg:black\"\n# Style for the symbol\nstyle_symbol = \"bg:red\"\n# A match is a character that is in both the query and the candidate\nstyle_match = \"underline bg:black fg:red bold\"\n\n# The selected candidate\n[selection]\n# Symbol displayed before the selection's text\nsymbol = \"✅ \"\n# Style for the selection's text\nstyle = \"bg:green fg:black\"\n# Style for the symbol\nstyle_symbol = \"bg:green\"\n# A match is a character that is in both the query and the selection\nstyle_match = \"underline fg:bright-green bg:black\"\n```\n\nThat configuration placed in the `$HOME/.config/scout.toml` would generate this UI:\n\n\u003cimg src=\"media/custom.png\" style=\"max-width=100%\" alt=\"customized UI\" /\u003e\n\nIt is not the prettiest, but it is just an example of what you can do.\n\nA style is defined with a `string` of space separated values. I ~~copied~~ based the syntax on [starship.rs][starship] configuration system.\n\nThese are the possible values you can use to define a style:\n\n* `underline`: Put a line under the text\n* `strikethrough`: Cross the text with a line\n* `reverse`: Reverse the current terminal colors\n* `bold`: Use bold font\n* `italic`: Use italic font (if the terminal supports it)\n* `dimmed`: Fade the foreground color a bit\n* `none`: Reset any color, using terminal's defaults. This will ignore any other rule in the style definition\n* `fg:\u003ccolor-name\u003e`: Use the named color as foreground (text) color. Possible names are `black`, `red`, `yellow`, `green`, `blue`, `purple`, `cyan`, `white`. You can also use their bright version with the `bright-*` prefix\n* `fg:\u003cnumber\u003e`: Use the given [ANSI Color][ansi-color] number as the foreground color\n* `fg:#\u003chex\u003e`: Use the given hexadecimal representation of an RGB color as the foreground color. For example `fg:#ffbbcc` would be  `rgb(255, 187, 204)`\n* `bg:\u003ccolor-name\u003e`: Same as with `fg:` but for the background\n* `bg:\u003cnumber\u003e`: Same as with `fg:` but for the background\n* `bg:#\u003chex\u003e`: Same as with `fg:` but for the background\n\nFor color setting it really depends on your terminal color capabilities. Most modern terminals allow you to set any color, though.\n\n## Fuzzy matching algorithm\n\nYou can learn more about the fuzzy matching algorithm in the `README` in the repository page of the  [`fuzzaldrin-plus`][fuzzaldrin-plus] package. The only missing part from that algorithm is the path scoring bonus.\n\nFrom all the algorithms for fuzzy matching out there this is one of the most complete I found, so I decided to try to port it.\n\n## Development\n\nCheck the [contributing][contributing] guidelines.\n\n## Neovim integration\n\nOne of the main reasons I've built this was to have a general purpose fuzzy finder I could use inside [Neovim][]. If you want to do the same you can use my [`scout.vim`][scoutvim] plugin.\n\n## FAQ\n\n##### Is this better than X?\n\nI don't know. Maybe? It really depends on your needs. I built this tool first to learn some Rust and second because I didn't like much other more heavy tools. That doesn't mean is better or worse. It is probably simpler. Give `scout` a try, see if it works for you, and if not try any other tool, it's cool.\n\n##### Is this faster than X?\n\nI don't know, I haven't run any benchmark, to be honest. It is fast enough for me and most probably for most of the people.\n\n##### Is this any good?\n\nYes.\n\n\n[rustlang]: https://www.rust-lang.org/\n[selecta]: https://github.com/garybernhardt/selecta\n[fzf]: https://github.com/junegunn/fzf\n[asyncstd]: https://async.rs/\n[starship]: https://starship.rs/\n[fuzzaldrin-plus]: https://github.com/jeancroy/fuzz-aldrin-plus/\n[crates]: https://crates.io/crates/scout\n[github-releases]: https://github.com/jhbabon/scout/releases\n[rustup]: https://rustup.rs/\n[ansi-color]: https://i.stack.imgur.com/KTSQa.png\n[rustfmt]: https://github.com/rust-lang/rustfmt\n[scoutvim]: https://github.com/jhbabon/scout.vim\n[Neovim]: https://neovim.io/\n[contributing]: ./CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhbabon%2Fscout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhbabon%2Fscout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhbabon%2Fscout/lists"}