# Fisher > A plugin manager for [Fish](https://fishshell.com)—your friendly interactive shell. [Snag fresh plugins!](https://git.io/awesome.fish) 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 without breaking a sweat. 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 - Zero configuration needed—we're not kidding! - Oh My Fish! plugins supported too > #### ☝️ [Upgrading from Fisher `3.x` or older? Strap in and read this!](https://github.com/jorgebucaran/fisher/issues/652) ## Installation ```console curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher ``` ## Quickstart 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. ### Installing plugins To install plugins, use the `install` command and point it to the GitHub repository. ```console fisher install jorgebucaran/nvm.fish ``` > 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](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefcommit-ishacommit-ishalsocommittish). ```console fisher install IlanCosman/tide@v5 ``` And hey, you can install plugins from a local directory too! ```console 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)). ### Listing plugins Use the `list` command to see all your shiny installed plugins. ```console $ fisher list jorgebucaran/fisher ilancosman/tide@v5 jorgebucaran/nvm.fish /home/jb/path/to/plugin ``` The `list` command also plays nice with regular expressions for filtering the output. ```console $ fisher list \^/ /home/jb/path/to/plugin ``` ### Updating plugins `update` command to the rescue! It updates one or more plugins to their latest and greatest version. ```console fisher update jorgebucaran/fisher ``` > Just type `fisher update` to update everything in one fell swoop. ### Removing plugins Say goodbye to installed plugins with the `remove` command. ```console fisher remove jorgebucaran/nvm.fish ``` Feeling destructive? Wipe out everything, including Fisher itself. ```console fisher list | fisher remove ``` ## 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. You can also edit this file and run `fisher update` to commit changes like a pro: ```console $EDITOR $__fish_config_dir/fish_plugins ``` ```diff jorgebucaran/fisher ilancosman/tide@v5 jorgebucaran/nvm.fish + PatrickF1/fzf.fish - /home/jb/path/to/plugin ``` ```console 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](https://fishshell.com/docs/current/index.html#configuration). 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](https://fishshell.com/docs/current/cmds/emit.html) 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. ```fish # 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`](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: 
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](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. ```console mv $__fish_config_dir/themes $__fish_config_dir/themes.bak ``` Next, create a symlink for Fisher's themes directory. ```console 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](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 ## License [MIT](LICENSE.md)