> A plugin manager for [Fish](https://fishshell.com)—your friendly interactive shell. [Snag fresh plugins!](https://github.com/jorgebucaran/awsm.fish#readme)
> A plugin manager for [Fish](https://fishshell.com)—the friendly interactive shell.
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!
Manage functions, completions, bindings, and snippets from the command line. Extend your shell capabilities, change the look of your prompt and create repeatable configurations across different systems effortlessly.
- Fisher is 100% pure-Fish, making it easy to contribute or modify
- Zero configuration out of the box. Need to tweak a thing? [You can do that too](#using-your-fish_plugins-file).
- Scorching fast concurrent plugin downloads that'll make you question reality
- 100% _pure_-Fish—easy to contribute to or modify.
- Zero configuration needed—we're not kidding!
- Blazing fast concurrent plugin downloads.
- Oh My Fish! plugins supported too
- Oh My Fish! plugin support.
> #### ☝️ [Upgrading from Fisher `3.x` or older? Strap in and read this!](https://github.com/jorgebucaran/fisher/issues/652)
Looking for plugins? Browse [git.io/awsm.fish](https://git.io/awesome.fish) or [search](https://github.com/topics/fish-plugins) [on](https://github.com/topics/fish-package) [GitHub](https://github.com/topics/fish-plugin).
Fisher lets you install, update, and remove plugins like a boss. Revel in Fish's [tab completion](https://fishshell.com/docs/current/index.html#completion) and rich syntax highlighting while you're at it.
You can install, update, and remove plugins interactively with Fisher, taking advantage of Fish [tab completion](https://fishshell.com/docs/current/index.html#completion) and rich syntax highlighting.
### Installing plugins
### Installing plugins
To install plugins, use the `install` command and point it to the GitHub repository.
Install plugins using the `install` command followed by the path to the repository on GitHub.
```console
```console
fisher install jorgebucaran/nvm.fish
fisher install ilancosman/tide
```
```
> Wanna install from GitLab? No problemo—just prepend `gitlab.com/` to the plugin path.
To get a specific version of a plugin add an `@` symbol after the plugin name followed by a tag, branch, or [commit](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefcommit-ishacommit-ishalsocommittish).
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](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefcommit-ishacommit-ishalsocommittish).
```console
```console
fisher install IlanCosman/tide@v5
fisher install jorgebucaran/nvm.fish@2.1.0
```
```
And hey, you can install plugins from a local directory too!
You can install plugins from a local directory too.
```console
```console
fisher install ~/path/to/plugin
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](https://github.com/jorgebucaran/fisher/issues/640)).
> Fisher expands plugins into your Fish configuration directory by default, overwriting existing files. If you wish to change this behavior, set `$fisher_path` to your preferred location and put it in your function path (#640).
### Listing plugins
### Listing plugins
Use the `list` command to see all your shiny installed plugins.
List all the plugins that are currently installed using the `list` command.
```console
```console
$ fisher list
$ fisher list
jorgebucaran/fisher
jorgebucaran/fisher
ilancosman/tide@v5
ilancosman/tide
jorgebucaran/nvm.fish
jorgebucaran/nvm.fish@2.1.0
/home/jb/path/to/plugin
/home/jb/path/to/plugin
```
```
The `list` command also plays nice with regular expressions for filtering the output.
The `list` command also accepts a regular expression to filter the output.
```console
```console
$ fisher list \^/
$ fisher list \^/
@ -66,23 +64,23 @@ $ fisher list \^/
### Updating plugins
### Updating plugins
`update` command to the rescue! It updates one or more plugins to their latest and greatest version.
The `update` command updates one or more plugins to their latest version.
```console
```console
fisher update jorgebucaran/fisher
fisher update jorgebucaran/fisher
```
```
> Just type `fisher update` to update everything in one fell swoop.
> Use just `fisher update` to update everything.
### Removing plugins
### Removing plugins
Say goodbye to installed plugins with the `remove` command.
Remove installed plugins using the `remove` command.
```console
```console
fisher remove jorgebucaran/nvm.fish
fisher remove jorgebucaran/nvm.fish@2.1.0
```
```
Feeling destructive? Wipe out everything, including Fisher itself.
You may want to remove everything, including Fisher.
```console
```console
fisher list | fisher remove
fisher list | fisher remove
@ -90,18 +88,18 @@ fisher list | fisher remove
## Using your `fish_plugins` file
## Using your `fish_plugins` file
Whenever you install or remove a plugin from the command line, Fisher jots down all the installed plugins in `$__fish_config_dir/fish_plugins`. Add this file to your dotfiles or version control to easily share your configuration across different systems.
Whenever you install or remove a plugin from the command line, Fisher will write down all the installed plugins plugins to `$__fish_config_dir/fish_plugins`. Adding this file to your dotfiles or version control is the easiest way to share your configuration across different systems.
You can also edit this file and run `fisher update` to commit changes like a pro:
You can also edit this file and run `fisher update` to commit changes. Here's an example:
```console
```console
$EDITOR $__fish_config_dir/fish_plugins
nano $__fish_config_dir/fish_plugins
```
```
```diff
```diff
jorgebucaran/fisher
jorgebucaran/fisher
ilancosman/tide@v5
ilancosman/tide
jorgebucaran/nvm.fish
jorgebucaran/nvm.fish@2.1.0
+ PatrickF1/fzf.fish
+ PatrickF1/fzf.fish
- /home/jb/path/to/plugin
- /home/jb/path/to/plugin
```
```
@ -110,84 +108,46 @@ jorgebucaran/nvm.fish
fisher update
fisher update
```
```
This will install **PatrickF1**/**fzf.fish**, remove /**home**/**jb**/**path**/**to**/**plugin**, and update everything else.
That will install **PatrickF1**/**fzf.fish**, remove /**home**/**jb**/**path**/**to**/**plugin**, and update everything else.
## Creating a plugin
## 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](https://fishshell.com/docs/current/index.html#configuration). Behold the anatomy of a typical plugin:
A plugin can be any number of files in a `functions`, `conf.d`, and `completions` directory. Most plugins consist of a single function, or [configuration snippet](https://fishshell.com/docs/current/#initialization-files). This is what a typical plugin looks like.
<pre>
<pre>
<b>flipper</b>
<b>ponyo</b>
├── <b>completions</b>
├── <b>completions</b>
│ └── flipper.fish
│ └── ponyo.fish
├── <b>conf.d</b>
├── <b>conf.d</b>
│ └── flipper.fish
│ └── ponyo.fish
└── <b>functions</b>
└── <b>functions</b>
└── flipper.fish
└── ponyo.fish
</pre>
</pre>
Non `.fish` files and directories inside these locations will be copied to `$fisher_path` under `functions`, `conf.d`, or `completions` respectively.
Non `.fish` files as well as directories inside those locations will be copied to `$fisher_path` under `functions`, `conf.d`, or `completions` respectively.
### Event system
### Event system
Fish [events](https://fishshell.com/docs/current/cmds/emit.html) notify plugins when they're being installed, updated, or removed.
Plugins are notified as they are being installed, updated, or removed via Fish [events](https://fishshell.com/docs/current/cmds/emit.html).
> Keep in mind, `--on-event` functions must be loaded when their event is emitted. So, place your event handlers in the `conf.d` directory.
> `--on-event` functions must already be loaded when their event is emitted. Thus, you should put your event handlers in the `conf.d` directory.
```fish
```fish
# Defined in flipper/conf.d/flipper.fish
# Defined in ponyo/conf.d/ponyo.fish
function _flipper_install --on-event flipper_install
function _ponyo_install --on-event ponyo_install
# Set universal variables, create bindings, and other initialization logic.
# Set universal variables, create bindings, and other initialization logic.
end
end
function _flipper_update --on-event flipper_update
function _ponyo_update --on-event ponyo_update
# Migrate resources, print warnings, and other update logic.
# Migrate resources, print warnings, and other update logic.
end
end
function _flipper_uninstall --on-event flipper_uninstall
function _ponyo_uninstall --on-event ponyo_uninstall
# Erase "private" functions, variables, bindings, and other uninstall logic.
# Erase "private" functions, variables, bindings, and other uninstall logic.
end
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`](https://github.com/fish-shell/fish-shell/releases/tag/3.4.0) 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:
<pre>
<b>gills</b>
├── <b>conf.d</b>
│ └── gills.fish
└── <b>themes</b>
└── gills.theme
</pre>
### 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](https://github.com/fish-shell/fish-shell/issues/9456).
Fear not! You can easily solve this by symlinking Fisher's `themes` directory into your Fish config. First, backup any existing themes directory.
Want to use theme plugins and maintain your own local themes? You can do that too ([#708](https://github.com/jorgebucaran/fisher/issues/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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics#adding-topics-to-your-repository) using [`fish-plugin`](https://github.com/topics/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!
## Acknowledgments
Fisher started its journey in 2016 by [@jorgebucaran](https://github.com/jorgebucaran) as a shell configuration manager for Fish. Along the way, many helped shape it into what it is today. [Oh My Fish](https://github.com/oh-my-fish/oh-my-fish) paved the way as the first popular Fish framework. [@jethrokuan](https://github.com/jethrokuan) provided crucial support during the early years. [@PatrickF1](https://github.com/PatrickF1)'s candid feedback proved invaluable time and again. Bootstrapping Fisher was originally [@IlanCosman](https://github.com/IlanCosman)'s brilliant idea. Thank you to all our contributors! <3
ifcommand curl -q--silent-L\$url |command tar -xzC\$temp -f- 2>/dev/null
if curl --silent\$url |tar--extract--gzip--directory\$temp --file- 2>/dev/null
command cp -Rf\$temp/*/* $source
command cp -Rf\$temp/*/* $source
else
else
echo fisher: Invalid plugin name or host unavailable: \\\"$plugin\\\">&2
echo fisher: Invalid plugin name or host unavailable: \\\"$plugin\\\">&2
command rm -rf$source
command rm -rf$source
end
end
command rm -rf\$temp
command rm -rf\$temp
end
end
setfiles$source/* &&string match --quiet--regex-- .+\.fish\\\$\$files
setfiles$source/* &&string match --quiet--regex-- .+\.fish\\\$\$files ||exit
echo\"fisher: Plugin not supported: \\\"$plugin\\\"\">&2
echo(set_color--bold red)\"Support for .fish files outside a functions directory is deprecated\"(set_color--underline)https://github.com/jorgebucaran/fisher/issues/651(set_color normal)>&2
" &
" &
set--appendpid_list(jobs--last--pid)
set--appendpid_list(jobs--last--pid)
@ -134,32 +124,31 @@ function fisher --argument-names cmd --description "A plugin manager for Fish"