10 releases (4 breaking)
new 0.5.0 | May 8, 2025 |
---|---|
0.4.0 | Mar 23, 2025 |
0.3.0 | Feb 23, 2025 |
0.2.3 | Feb 7, 2025 |
0.1.2 | Nov 17, 2024 |
#1946 in Command line utilities
131 downloads per month
210KB
5.5K
SLoC
scooter
Scooter is an interactive find-and-replace terminal UI app.
Search with either a fixed string or a regular expression, enter a replacement, and interactively toggle which instances you want to replace.
If the instance you're attempting to replace has changed since the search was performed, e.g. if you've switched branches and that line no longer exists, that particular replacement won't occur: you'll see all such cases at the end.
You can use custom themes for syntax highlighting (see here for more info):
Contents
Features
Scooter respects both .gitignore
and .ignore
files.
You can add capture groups to the search regex and use them in the replacement string: for instance, if you use (\d) - (\w+)
for the search text and ($2) "$1"
as the replacement, then 9 - foo
would be replaced with (foo) "9"
.
When viewing search results, you can open the selected file at the relevant line by pressing o
. This will use the editor defined by your EDITOR
environment variable. Scooter will automatically attempt to open the editor at the correct line number, but if you'd like to override the command used then you can set editor_open
in your config file.
Usage
Run
scooter
in a terminal to launch Scooter. By default the current directory is used to search and replace in, but you can pass in a directory as the first argument to override this behaviour:
scooter ../foo/bar
A set of keymappings will be shown at the bottom of the window: these vary slightly depending on the screen you're on.
By default, Scooter uses a regex engine that supports only a subset of features to maximise performance. To use the full range of regex features, such as negative lookahead, start Scooter with the -a
(--advanced-regex
) flag.
Hidden files (such as those starting with a .
) are ignored by default, but can be included by using the --hidden
flag.
Search fields
When on the search screen the following fields are available:
- Search text: Text to search with. Defaults to regex, unless "Fixed strings" is enabled, in which case this reverts to case-sensitive string search.
- Replace text: Text to replace the search text with. If searching with regex, this can include capture groups.
- Fixed strings: If enabled, search with plain strings. If disabled, search with regex.
- Match whole word: If enabled, only match when the search string forms an entire word and not a substring in a larger word. For instance, if the search string is "foo", "foo bar" would be matched but not "foobar".
- Match case: If enabled, match the case of the search string exactly, e.g. a search string of
Bar
would matchfoo Bar baz
but notfoo bar baz
. - Files to include: Glob patterns, separated by commas (
,
), that file paths must match. For instance,*.rs, *.py
matches all files with the.rs
or.py
extensions. - Files to exclude: Glob patterns, separated by commas (
,
), that file paths must not match. For instance,env/**
ignores all files in theenv
directory. This field takes precedence over the pattern in the "Files to include" field.
Note that the glob matching library used in Scooter comes from the brilliant ripgrep, and matches the behaviour there: for instance, if you wanted to include only files in the directory dir1
, you'd need to add dir1/**
in the "Files to include" field - dir1
alone would not work.
Installation
Homebrew
On macOS and Linux, you can install Scooter using Homebrew:
brew install scooter
Nix
Scooter is available as scooter
in nixpkgs, currently on the unstable channel.
AUR
Install from the Arch User Repository with:
yay -S scooter
Or, to build from the latest commit:
yay -S scooter-git
Winget
Install from Winget with
winget install thomasschafer.scooter
Prebuilt binaries
Download the appropriate binary for your system from the releases page:
Platform | Architecture | Download file |
---|---|---|
Linux | Intel/AMD | *-x86_64-unknown-linux-musl.tar.gz |
Linux | ARM64 | *-aarch64-unknown-linux-musl.tar.gz |
macOS | Apple Silicon | *-aarch64-apple-darwin.tar.gz |
macOS | Intel | *-x86_64-apple-darwin.tar.gz |
Windows | x64 | *-x86_64-pc-windows-msvc.zip |
After downloading, extract the binary and move it to a directory in your PATH
.
Cargo
Ensure you have cargo installed (see here), then run:
cargo install scooter
Building from source
Ensure you have cargo installed (see here), then run the following commands:
git clone git@github.com:thomasschafer/scooter.git
cd scooter
cargo install --path scooter --locked
Configuration options
Scooter looks for a TOML configuration file at:
- Linux or macOS:
~/.config/scooter/config.toml
- Windows:
%AppData%\scooter\config.toml
The following options can be set in your configuration file:
[editor_open]
section
command
The command used when pressing o
on the search results page. Two variables are available: %file
, which will be replaced
with the file path of the seach result, and %line
, which will be replaced with the line number of the result. For example:
[editor_open]
command = "vi %file +%line"
exit
Whether to exit after running the command defined by editor_open.command
.
[preview]
section
syntax_highlighting
Whether to apply syntax highlighting to the preview.
syntax_highlighting_theme
The theme to use when syntax highlighting is enabled.
The default is "base16-eighties.dark"
. Other built-in options are
"base16-mocha.dark"
, "base16-ocean.dark"
, "base16-ocean.light"
, "InspiredGitHub"
, "Solarized (dark)"
and "Solarized (light)"
.
You can use other themes by adding .tmTheme
files to ~/.config/scooter/themes/
on Linux or macOS, or %AppData%\scooter\themes\
on Windows,
and then specifying their name here. For instance, to use Catppuccin Macchiato (from here), on Linux or macOS run:
wget -P ~/.config/scooter/themes https://github.com/catppuccin/bat/raw/main/themes/Catppuccin%20Macchiato.tmTheme
and then set syntax_highlighting_theme = "Catppuccin Macchiato"
.
Editor configuration
Below are a couple of ways to configure Scooter to run in a floating window, without leaving your editor.
Helix
If you are using Helix in Tmux, you can add a keymap like the following to your Helix config to open Scooter with <enter> s
:
[keys.select.ret]
s = ":sh tmux popup -xC -yC -w90% -h90% -E scooter"
You can also add the following to your Scooter config file to open files from the search results page with o
:
[editor_open]
command = 'tmux send-keys -t "$TMUX_PANE" ":open %file:%line" Enter'
exit = true
Neovim
Install Toggleterm as per the instructions here, and then add the following Lua configuration, which opens up Scooter with <leader>s
:
local Terminal = require("toggleterm.terminal").Terminal
local scooter = Terminal:new({ cmd = "scooter", hidden = true })
function _scooter_toggle()
scooter:toggle()
end
vim.keymap.set("n", "<leader>s", "<cmd>lua _scooter_toggle()<CR>", {
noremap = true,
silent = true,
desc = "Toggle Scooter"
})
Contributing
Contributions are very welcome! I'd be especially grateful for any contributions to add Scooter to popular package managers. If you'd like to add a new feature, please create an issue first so we can discuss the idea, then create a PR with your changes.
Development
Once you've pulled down the repo, you can run Scooter with:
cargo run --bin scooter
If you make any changes to either the readme or config, you'll need to run the following to regenerate the docs:
cargo xtask readme
Dependencies
~17–34MB
~455K SLoC