Better Fisher

Improvement of https://github.com/jorgebucaran/fisher

• fisher install --overwrite
  • Overwrite local files
  • Dangerous!
• fisher update --overwrite
  • Overwrite local files
  • Dangerous!
• Never delete any line from ~/.config/fish/fish_plugins
  • Do nothing strange !
• list files from certain plugin
  • fisher list lengyijun/fisher
• list tracked files
  • fisher list (fisher list)
• list untracked files
  • fisher ls-untracked-files
• completion for fisher list
• Better ci

Fixed issues of https://github.com/jorgebucaran/fisher

• jorgebucaran#770
• jorgebucaran#790
• jorgebucaran#823
• jorgebucaran#746

Installation

curl -sL https://raw.githubusercontent.com/lengyijun/fisher/fishest/functions/fisher.fish | source && fisher install lengyijun/fisher --overwrite ; fisher ignore jorgebucaran/fisher

---

A plugin manager for Fish—your friendly interactive shell. Snag fresh plugins!

Take control of functions, completions, bindings, and snippets from the command line. Unleash your shell's true potential, perfect your prompt, and craft repeatable configurations across different systems effortlessly. Fisher's zero impact on shell startup keeps your shell zippy and responsive. No gimmicks, just smooth sailing!

• Fisher is 100% pure-Fish, making it easy to contribute or modify
• Scorching fast concurrent plugin downloads that'll make you question reality

Quickstart

Fisher lets you install, update, and remove plugins like a boss. Revel in Fish's tab completion and rich syntax highlighting while you're at it.

Installing plugins

To install plugins, use the install command and point it to the GitHub repository.

fisher install kfkonrad/last-working-dir-fish-pkg

Wanna install from GitLab? No problemo—just prepend gitlab.com/ to the plugin path.

You can also snag a specific version of a plugin by adding an @ symbol after the plugin name, followed by a tag, branch, or commit.

fisher install IlanCosman/tide@v6

And hey, you can install plugins from a local directory too!

fisher install ~/path/to/plugin

Heads up! Fisher expands plugins into your Fish configuration directory by default, overwriting existing files. If that's not your jam, set $fisher_path to your preferred location and put it in your function path (#640).

Listing plugins

Use the list command to see all your shiny installed plugins.

$ fisher list
lengyijun/fisher
ilancosman/tide@v6
kfkonrad/last-working-dir-fish-pkg
/home/jb/path/to/plugin

fisher list <plugin> list files provided by the plugin:

$ fisher list lengyijun/fisher
~/.config/fish/functions/fisher.fish
~/.config/fish/completions/fisher.fish

Notice: some generated files are unexpected not listed in output, e.g. gazorby/fish-exa

List files tracked by fisher

fisher list (fisher list)

Notice: some generated files are unexpected not listed in output, e.g. gazorby/fish-exa

List files not tracked by fisher

fisher ls-untracked-files

Notice: some generated files are unexpected listed in output, e.g. gazorby/fish-exa

Updating plugins

update command to the rescue! It updates one or more plugins to their latest and greatest version.

fisher update lengyijun/fisher

Just type fisher update to update everything in one fell swoop.

Removing plugins

Say goodbye to installed plugins with the remove command.

fisher remove kfkonrad/last-working-dir-fish-pkg

Feeling destructive? Wipe out everything, including Fisher itself.

fisher list | fisher remove

Ignore plugins

To fix broken fisher inner state, we usually:

fisher ignore <plugin>

fisher ignore will no longer track the plugin, while keep the plugin files.

Using your fish_plugins file

The main usage of fish_plugins is to be tracked in your dotfiles manages(e.g. chezmoi) or version control.

Although we support following editing, we strongly recommand you to use fisher install/fisher remove to manage plugins.

Whenever you install or remove a plugin from the command line, Fisher jots down all the installed plugins in $__fish_config_dir/fish_plugins.

You can also edit this file and run fisher update to commit changes like a pro:

$EDITOR $__fish_config_dir/fish_plugins

lengyijun/fisher
ilancosman/tide@v6
kfkonrad/last-working-dir-fish-pkg
+ PatrickF1/fzf.fish
- /home/jb/path/to/plugin

fisher update

This will install PatrickF1/fzf.fish, remove /home/jb/path/to/plugin, and update everything else.

Creating a plugin

Plugins can include any number of files in functions, conf.d, and completions directories. Most plugins are just a single function or a configuration snippet. Behold the anatomy of a typical plugin:

flipper
├── completions
│   └── flipper.fish
├── conf.d
│   └── flipper.fish
└── functions
    └── flipper.fish

Non .fish files and directories inside these locations will be copied to $fisher_path under functions, conf.d, or completions respectively.

Event system

Fish events notify plugins when they're being installed, updated, or removed.

Keep in mind, --on-event functions must be loaded when their event is emitted. So, place your event handlers in the conf.d directory.

# Defined in flipper/conf.d/flipper.fish

function _flipper_install --on-event flipper_install
    # Set universal variables, create bindings, and other initialization logic.
end

function _flipper_update --on-event flipper_update
    # Migrate resources, print warnings, and other update logic.
end

function _flipper_uninstall --on-event flipper_uninstall
    # Erase "private" functions, variables, bindings, and other uninstall logic.
end

Creating a theme

A theme is like any other Fish plugin, but with a .theme file in the themes directory. Themes were introduced in Fish 3.4 and work with the fish_config builtin. A theme can also have files in functions, conf.d, or completions if necessary. Check out what a typical theme plugin looks like:

gills
├── conf.d
│   └── gills.fish
└── themes
    └── gills.theme

Using $fisher_path with themes

If you customize $fisher_path to use a directory other than $__fish_config_dir, your themes won't be available via fish_config. That's because Fish expects your themes to be in $__fish_config_dir/themes, not $fisher_path/themes. This isn't configurable in Fish yet, but there's a request to add that feature.

Fear not! You can easily solve this by symlinking Fisher's themes directory into your Fish config. First, backup any existing themes directory.

mv $__fish_config_dir/themes $__fish_config_dir/themes.bak

Next, create a symlink for Fisher's themes directory.

ln -s $fisher_path/themes $__fish_config_dir/themes

Want to use theme plugins and maintain your own local themes? You can do that too (#708).

Discoverability

While Fisher doesn't rely on a central plugin repository, discovering new plugins doesn't have to feel like navigating uncharted waters. To boost your plugin's visibility and make it easier for users to find, add relevant topics to your repository using fish-plugin. By doing so, you're not only contributing to the Fisher community but also enabling users to explore new plugins and enhance their Fish shell experience. Don't let plugin discovery be a fishy business, tag your plugins today!

See also https://github.com/lengyijun/awsm.fish

Acknowledgments

Fisher started its journey in 2016 by @jorgebucaran as a shell configuration manager for Fish. Along the way, many helped shape it into what it is today. Oh My Fish paved the way as the first popular Fish framework. @jethrokuan provided crucial support during the early years. @PatrickF1's candid feedback proved invaluable time and again. Bootstrapping Fisher was originally @IlanCosman's brilliant idea. Thank you to all our contributors! <3

Because @jorgebucaran refuse to solve jorgebucaran#790 and many other issues, @jorgebucaran neglects real-world issues. @lengyijun forked and fixed them.

License

MIT