fishmarks

Fishmarks lets you save and jump to frequently used directories in Fish shell. It is fast, script-friendly, and compatible with existing bashmarks data.

Quickstart (15 seconds)

fisher install techwizrd/fishmarks
s proj
g proj
l

s <name> saves the current directory
g <name> jumps to a saved directory
l lists saved bookmarks

Demo

fishmarks demo

This demo is recorded with asciinema and rendered with agg.

Installation

Automatic Installation

To install fishmarks automatically, paste the following in your terminal.

curl -fsSL https://raw.githubusercontent.com/techwizrd/fishmarks/master/install.fish | fish

Please note that you should never install things by piping untrusted install scripts downloaded through curl directly into your shell (whether bash or fish). Even if you read through the install script and think you understand it, you could still be prone to a man-in-the-middle attack or other security vulnerabilities. While manual installations are tedious, they are recommended for situations where security is a concern (and it should almost always be a concern).

Fisher Installation

If you use Fisher, install fishmarks with:

fisher install techwizrd/fishmarks

Fundle Installation

If you use Fundle, add fishmarks to your fish config:

fundle plugin 'techwizrd/fishmarks'
fundle init

Then install plugins:

fundle install

Fish plugin managers load fishmarks from functions/, conf.d/, and completions/. The top-level marks.fish file remains as a compatibility loader for existing manual installs.

Manual Installation

To install fishmarks manually:

Clone fishmarks into ~/.fishmarks.

git clone https://github.com/techwizrd/fishmarks.git ~/.fishmarks

Source ~/.fishmarks/marks.fish from a file in ~/.config/fish/conf.d/.

mkdir -p ~/.config/fish/conf.d
printf '# Load fishmarks (https://github.com/techwizrd/fishmarks)\n' \
  'source ~/.fishmarks/marks.fish\n' > ~/.config/fish/conf.d/fishmarks.fish

Update to the latest version

To update to the latest version of fishmarks:

Navigate to the directory where fishmarks is installed (~/.fishmarks by default).

cd ~/.fishmarks

Use git to fetch the latest version.

git fetch --all

Pull the latest version.

git pull --ff-only

Compared to other directory-jump tools

Popular alternatives you might know:
- zoxide: fast, frecency-based jumping across shells
- autojump: classic usage-history directory jumping
- z: original "jump around" script that inspired later tools
- z.lua: modern Lua implementation with broad shell support
Use fishmarks when you want explicit, named bookmarks (g work, g dotfiles)
Use history/frecency tools when you want automatic ranking by usage

Many users combine both: automatic jumping for exploration, fishmarks for stable project bookmarks.

Usage

Commands

save_bookmark [--force] [bookmark_name] (or s) - Saves the current directory as "bookmark_name"
rename_bookmark <old_name> <new_name> - Renames an existing bookmark
bookmark_exists <bookmark_name> - Returns success if bookmark exists
go_to_bookmark <bookmark_name> (or g) - Goes (cd) to the directory associated with "bookmark_name"
print_bookmark <bookmark_name> (or p) - Prints the directory associated with "bookmark_name"
delete_bookmark <bookmark_name> (or d) - Deletes the bookmark
list_bookmarks [--names-only] (or l) - Lists all available bookmarks
fishmarks_doctor - Checks bookmarks file for common issues
fishmarks_version - Prints the installed fishmarks version

Configuration Variables

All variables must be set before marks.fish is sourced in fish startup files.

SDIRS - default: ~/.sdirs; location where bookmarks are stored.
NO_FISHMARKS_COMPAT_ALIASES - disable bashmark-compatible aliases such as p.

Example

[~]$ cd /var/www/
[/var/www]$ s webfolder
[/usr/local/lib]$ cd /usr/local/lib/
[/usr/local/lib]$ s locallib
[/usr/local/lib]$ l
locallib             /usr/local/lib
webfolder            /var/www
[/usr/local/lib]$ g webfolder
[/var/www]$

Running tests

Run the test suite with:

fish tests/run.fish

Run syntax and formatting checks with:

fish tests/check.fish

Or with make:

make check

Run all checks and tests with:

make test

Development workflow

Install prek (or pre-commit) hooks locally:

prek install

Run all hooks on demand:

prek run --all-files

GitHub Actions CI runs checks (tests/check.fish, tests/run.fish), installer smoke tests, and plugin-manager smoke tests for Fisher and Fundle on every push and pull request.

Versioning

fishmarks follows Semantic Versioning. Notable changes are tracked in CHANGELOG.md.

Contributing

See CONTRIBUTING.md for setup, validation commands, and pull request guidelines.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Fishmarks

Install / Use

README