fisher/man/man7/fisher-tour.md

fisher-tour(7) -- Fisherman Tour

DESCRIPTION

Fisherman is a blazing fast, modern plugin manager for fish(1).

Fisherman runs virtually no initialization code, making it as fast as no Fisherman. The cache mechanism lets you query the index offline and enable or disable plugins as you wish.

Other features include dependency management, excellent test coverage, plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and plugins.

This document describes Fisherman features and their implementation details. For usage and command help see fisher(1).

FLAT TREE

The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time.

To explain how this is possible, we need to make a digression and discuss function scope first. In fish, all functions share the same scope and you can use only one name per function.

In the following example:

function foo
    echo $_
    function bar
    end
end

function bar
    echo $_
end

foo and bar are available immediately at the command line prompt and both print their names. But there is a catch, calling foo at least once will create a new bar function, effectively erasing the previous bar definition. Subsequent calls to bar will print nothing.

By convention, functions that start with any number of underscores are intentionally private, but there is no mechanism that prevents you from calling them once they are loaded.

With this in mind, it's possible to improve the slow shell start problem using a flat tree structure whose path is loaded only once.

The overhead of juggling multiple path hierarchies in a per-plugin basis yields no benefits as everything is shared inside the same scope.

Loading a path simply means adding the desired location to the $fish_function_path array. See also functions(1).

Here is a snapshot of an example Fisherman configuration path with a single plugin and prompt:

$fisher_config
|-- cache/
|-- conf.d/
|-- |-- my_plugin.config.fish
|-- functions/
|   |-- my_plugin.fish
|   |-- fish_prompt.fish
|   |-- fish_right_prompt.fish
|-- completions/
|   |-- my_plugin.fish
|-- man/
    |-- man1/
        |-- my_plugin.1

If you are already familiar in the way Fish handles your user configuration, you will find the above structure similar to $XDG_CONFIG_HOME/fish. See Initialization Files in help fish to learn more about fish configuration.

conf.d, short for configuration directory, is used for initialization files, i.e., files that should run at the start of the shell. Files that follow the naming convention <my_plugin>.config.fish are added there. If a file does not follow the <my_plugin>.config.fish convention, <my_plugin> will be added during the installation process.

PLUGINS

Plugins are components that extend and add features to your shell. To see what plugins are available use fisher search. You can also type fisher install and hit tab once to get formatted plugin information. The same works for fisher update and fisher uninstall.

To learn how to create plugins, see fisher help plugins.

You can install a plugin by their name, URL or by indicating the path to a local plugin project.

In order to install a plugin by name, it must be already published in the index database. See Index.

fisher install shark

You can use an URL too if you have one.

fisher install simnalamburt/shellder

If the domain or host is not provided, Fisherman will use https://github.com by default.

In addition, all of the following owner/repo variations are accepted:

• owner/repo > https://github.com/owner/repo
  
• github/owner/repo > https://github.com/owner/repo
  
• gh/owner/repo > https://github.com/owner/repo
  

Shortcuts to other common Git repository hosting services are also available:

• bb/owner/repo > https://bitbucket.org/owner/repo
  
• gl/owner/repo > https://gitlab.com/owner/repo
  
• omf/owner/repo > https://github.com/oh-my-fish/repo
  

Because of Fisherman's flat tree model, there is no technical distinction between plugins or prompts. Installing a prompt is equivalent to switching themes in other systems. The interface is always install, update or uninstall.

Throughout this document and other Fisherman manuals you will find the term prompt when referring to the concept of a theme, i.e., a plugin that defines a fish_prompt / fish_right_prompt function/s.

INDEX

You can install, update and uninstall plugins by their name, querying the Fisherman index. The index is a plain text flat database independently managed. You can use a custom index file by setting $fisher_index to your own file or URL. Redirection URLs are currently not supported due to security and performance concerns. See fisher help config.

A copy of the index is downloaded each time a search query takes place, $fisher_update_interval seconds since the last update. $fisher_update_interval is 10 seconds by default if not set. This helps keeping the index up to date and allows you to search the database offline.

The index itself is a list of records, each consisting of the following fields:

• name, url, info, one or more tags and author.

Fields are separated by a new line '\n'. Tags are separated by one space. Here is a sample record:

shark
https://github.com/bucaran/shark
Fantastic Sparkline Generator
chart tool report sparkline graph
bucaran

To submit a new plugin for registration install the submit plugin:

fisher install submit

For usage see the bundled documentation fisher help submit.

You can also submit a new plugin manually and create a pull request in the index repository (github.com/fisherman/fisher-index):

git clone https://github.com/fisherman/fisher-index
cd index
echo "$name\n$URL\n$info\n$author\n$tags\n\n" >> index
git push origin master
open http://github.com

CACHE

Downloaded plugins are stored as Git repositories under $fisher_cache. See fisher help config to find out about other Fisherman configuration variables.

When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path. In this sense, this location works also like an intermediate stage. In addition, manual pages are added to the corresponding man directory and if a Makefile is also detected, the command make is run.

FISHFILES

Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using fisher --list.

Your fishfile is stored in $fisher_config/fishfile by default, but you can customize its location setting $fisher_file in your user fish configuration file.

Here is an example fishfile inside $fisher_config:

# Ahoy! This is my Fishfile
gitio
fishtape
shark
get

The fishfile updates as you install / uninstall plugins. See also fisher help install or fisher help uninstall.

CONFIGURATION

Fisherman allows a high level of configuration using $fisher_* variables. You can customize the home and configuration directories, cache and fishfile location, index source URL, command aliases, etc. See fisher help config.

You can also extend Fisherman by adding new commands and ship them as plugins. Fisherman automatically adds completions to commands based in the function description and usage help if provided. See fisher help help and fisher help commands.

To add completions to standalone utility plugins, use complete(1).

CLI

If you are already familiar with other UNIX tools, you'll find Fisherman commands behave intuitively.

Most commands read the standard input by default when no options are given and produce easy to parse output, making Fisherman commands ideal for plumbing and building upon each other.

Fisherman also ships with a CLI options parser and a job spinner you can use to implement your own CLIs. See getopts(1) and spin(1).

COMPATIBILITY

Fisherman supports Oh My Fish! themes and plugins, but some features are turned off by default for performance reasons.

Oh My Fish! evaluates every .fish file inside the root directory for every plugin installed during shell start. This is necessary in order to load any existing init event functions and immediately invoke them using fish emit(1).

Since it is not possible to determine whether a file defines an initialization event without evaluating its contents first, Oh My Fish! sources all *.fish files and then emits events for each plugin.

Not all plugins opt in the initialization mechanism, therefore support for this behavior is turned off by default. If you would like Fisherman to behave like Oh My Fish! at the start of the shell session, install the legacy compatibility plugin.

fisher install legacy

This plugin also adds definitions for some of Oh My Fish! Core Library functions.

SEE ALSO

fisher(1)
fisher help
fisher help config
fisher help plugins
fisher help commands
spin(1)
getopts(1)