fisher/man/man1/fisher.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "FISHER" "1" "March 2016" "" "fisherman"
.
.SH "NAME"
\fBfisher\fR \- Fish plugin manager
.
.SH "SYNOPSIS"
fisher \fIcommand\fR [\fIoptions\fR] [\-\-version] [\-\-help]
.
.br
.
.SH "DESCRIPTION"
Fisherman is a plugin manager for fish\.
.
.P
The Fisherman CLI consists of: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR and the following aliases: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\.
.
.SH "USAGE"
Run a command\.
.
.IP "" 4
.
.nf

fisher <command> [<options>]
.
.fi
.
.IP "" 0
.
.P
Get help about a command\.
.
.IP "" 4
.
.nf

fisher help <command>
.
.fi
.
.IP "" 0
.
.SH "OPTIONS"
.
.TP
\-v, \-\-version
Show version information\. Fisherman follows Semantic Versioning and uses Git annotated tags to track releases\.
.
.TP
\-h, \-\-help
Show usage help\.
.
.SH "EXAMPLES"
.
.IP "\(bu" 4
Install plugins\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher i fishtape shark get bobthefish
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install Oh My Fish! plugins\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher i omf/plugin\-{percol,jump,fasd}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install a plugin from a local directory\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher i \./path/to/plugin
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install a plugin from various URLs\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher i https://github\.com/some/plugin another/plugin bb:one/more
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install a plugin from a Gist\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher i gist\.github\.com/owner/1f40e1c6e0551b2666b2
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Update everything\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher u
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Update plugins\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher u shark get
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Uninstall plugins\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher uninstall fishtape debug
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Get help\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher h
.
.fi
.
.IP "" 0
.
.SH "LIST AND SEARCH"
The list command displays all the plugins you have installed\. The search command queries the index to show what\'s available to install\.
.
.P
List installed plugins\.
.
.IP "" 4
.
.nf

fisher list
  debug
* fishtape
> shellder
* spin
@ wipe
.
.fi
.
.IP "" 0
.
.P
Search the index\.
.
.IP "" 4
.
.nf

fisher search
  \.\.\.
* debug        Conditional debug logger
  errno        POSIX error code/string translator
* fishtape     TAP producing test runner
  flash        Flash\-inspired, thunder prompt
  fzf          Efficient keybindings for fzf
  get          Press any key to continue
  \.\.\.
> shellder     Powerline prompt optimized for speed
  \.\.\.
.
.fi
.
.IP "" 0
.
.P
Query the index using regular expressions\.
.
.IP "" 4
.
.nf

fisher search \-\-name~/git\-is/
git\-is\-dirty       Test if there are changes not staged for commit
git\-is\-empty       Test if a repository is empty
git\-is\-repo        Test if the current directory is a Git repo
git\-is\-staged      Test if there are changes staged for commit
git\-is\-stashed     Test if there are changes in the stash
git\-is\-touched     Test if there are changes in the working tree
.
.fi
.
.IP "" 0
.
.P
Search using tags\.
.
.IP "" 4
.
.nf

fisher search \-\-tag={git,test}
  \.\.\.
  * fishtape         TAP producing test runner
  git\-branch\-name    Get the name of the current Git branch
  git\-is\-dirty       Test if there are changes not staged for commit
  git\-is\-empty       Test if a repository is empty
  git\-is\-repo        Test if the current directory is a Git repo
  git\-is\-staged      Test if there are changes staged for commit
  git\-is\-stashed     Test if there are changes in the stash
  git\-is\-touched     Test if there are changes in the working tree
  \.\.\.
.
.fi
.
.IP "" 0
.
.P
The legend consists of:
.
.IP "\(bu" 4
\fB*\fR The plugin is enabled
.
.IP "\(bu" 4
\fB>\fR The plugin is a prompt
.
.IP "\(bu" 4
\fB@\fR The plugin is a symbolic link
.
.IP "" 0
.
.SH "PLUMBING"
Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\.
.
.P
Update plugins installed as symbolic links\.
.
.IP "" 4
.
.nf

fisher list \-\-link | fisher update \-
.
.fi
.
.IP "" 0
.
.P
Enable all the plugins currently disabled\.
.
.IP "" 4
.
.nf

fisher list \-\-disabled | fisher install
.
.fi
.
.IP "" 0
.
.P
Uninstall all the plugins and remove them from the cache\.
.
.IP "" 4
.
.nf

fisher list | fisher uninstall \-\-force
.
.fi
.
.IP "" 0
.
.SH "DOTFILES"
When you install a plugin, Fisherman updates the \fIfishfile\fR to track what plugins are currently enabled\.
.
.IP "\(bu" 4
Customize the location of the fishfile\.
.
.IP "" 0
.
.IP "" 4
.
.nf

set \-g fisher_file ~/\.dotfiles/fishfile
.
.fi
.
.IP "" 0
.
.SH "FLAT TREE"
Fisherman merges the directory trees of all the plugins it installs into a single flat tree\. Since the flat tree is loaded only once at the start of the shell, Fisherman performs equally well, regardless of the number of plugins installed\.
.
.P
The following illustrates an example Fisherman configuration path with a single plugin and prompt\.
.
.IP "" 4
.
.nf

$fisher_config
|\-\- cache/
|\-\- conf\.d/
|   `\-\- my_plugin\.fish
|\-\- fishfile
|\-\- functions/
|   |\-\- my_plugin\.fish
|   |\-\- fish_prompt\.fish
|   `\-\- fish_right_prompt\.fish
|\-\- completions/
|   `\-\- my_plugin\.fish
`\-\- man/
    `\-\- man1/
        `\-\- my_plugin\.1
.
.fi
.
.IP "" 0
.
.SH "INDEX"
The index is a plain text database that lists Fisherman official plugins\.
.
.P
The index lists records, each consisting the fields: \fIname\fR, \fIurl\fR, \fIinfo\fR, one or more \fItags\fR and \fIauthor\fR\.
.
.IP "" 4
.
.nf

z
https://github\.com/fishery/fish\-z
Pure\-fish z directory jumping
z search cd jump
jethrokuan
.
.fi
.
.IP "" 0
.
.P
If you have a plugin you would like to submit to the index, use the submit plugin\.
.
.IP "" 4
.
.nf

fisher install submit
fisher submit my_plugin description tags url
.
.fi
.
.IP "" 0
.
.P
Or, submit the plugin manually by creating a pull request in the index \fIhttps://github\.com/fisherman/fisher\-index\fR repository\.
.
.SH "VARIABLES"
.
.TP
$fisher_home
The home directory\. If you installed Fisherman using the recommended method, the location ought to be \fIXDG_DATA_HOME/fisherman\fR\.
.
.TP
$fisher_config
The configuration directory\. This is default location of your \fIfishfile\fR, \fIkey_bindings\.fish\fR, \fIcache\fR, \fIfunctions\fR, \fIcompletions\fR and \fIconf\.d\fR directories\. \fIXDG_CONFIG_HOME/fisherman\fR by default\.
.
.TP
$fisher_file
See FISHFILE above\.
.
.TP
$fisher_cache
The cache directory\. Plugins are downloaded to this location\.
.
.TP
$fisher_alias \fIcommand\fR=\fIalias\fR \.\.\.
Use this variable to create aliases of Fisherman commands\.
.
.SH "PLUGINS"
Plugins can be utilities, prompts, commands or snippets\. To create a plugin from a template, install the new command\.
.
.IP "" 4
.
.nf

fisher install new
fisher new plugin < meta\.yml
.
.fi
.
.IP "" 0
.
.P
See the documentation of new for details\.
.
.SS "UTILITIES"
Utilities are plugins that define one or more functions\.
.
.P
Below is a plugin based in ngerakines/commitment \fIhttps://github/ngerakines/commitment\fR random commit message generator\.
.
.IP "" 4
.
.nf

mkdir wtc
cd wtc

function wtc \-d "Generate a random commit message"
    switch "$argv"
        case \-h \-\-help
            printf "Usage: wtc [\-\-help]\en\en"
            printf "  \-h \-\-help  Show usage help\en"
            return
    end
    curl \-s whatthecommit\.com/index\.txt
end
functions wtc > wtc\.fish

fisher install \.
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf

wtc
(\e /)
(O\.o)
(> <) Bunny approves these changes\.
.
.fi
.
.IP "" 0
.
.P
To submit wtc to the official index\.
.
.IP "" 4
.
.nf

fisher submit wtc "Random commit message generator" "commit random fun" https://github\.com/owner/wtc
.
.fi
.
.IP "" 0
.
.P
This will create a PR in the Fisherman index repository\. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index\.
.
.IP "" 4
.
.nf

fisher install wtc
.
.fi
.
.IP "" 0
.
.P
A plugin can list dependencies to other plugins using a \fIfishfile\fR\.
.
.P
Create a \fIfishfile\fR in the root of your project and add the name or URL of your dependencies\.
.
.IP "" 4
.
.nf

my_plugin
https://github\.com/owner/another_plugin
.
.fi
.
.IP "" 0
.
.SS "PROMPTS"
Prompts, or themes, are plugins that modify the appearance of the shell prompt and colors\.
.
.P
Create a \fBfish_prompt\fR function\.
.
.IP "" 4
.
.nf

function fish_prompt
    printf "%s (%s) >> " (prompt_pwd) Fisherman
end
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf

~ (Fisherman) >> type here
.
.fi
.
.IP "" 0
.
.P
To add a right prompt, create a \fBfish_right_prompt\fR function\.
.
.IP "" 4
.
.nf

function fish_right_prompt
    printf "%s" (date +%H:%M:%S)
end
.
.fi
.
.IP "" 0
.
.P
Save the functions to a directory and install the prompt as a plugin\.
.
.IP "" 4
.
.nf

mkdir my_prompt
cd my_prompt

functions fish_prompt > fish_prompt\.fish
functions fish_right_prompt > fish_right_prompt\.fish

fisher install \.
.
.fi
.
.IP "" 0
.
.P
Customize the colors fish uses for syntax highlighting\.
.
.IP "" 4
.
.nf

function set_color_custom
    # set \-U fish_color_normal
    # set \-U fish_color_command
    # set \-U fish_color_param
    # set \-U fish_color_redirection
    # set \-U fish_color_comment
    # set \-U fish_color_error
    # set \-U fish_color_escape
    # set \-U fish_color_operator
    # set \-U fish_color_end
    # set \-U fish_color_quote
    # set \-U fish_color_autosuggestion
    # set \-U fish_color_valid_path
    # set \-U fish_color_cwd
    # set \-U fish_color_cwd_root
    # set \-U fish_color_match
    # set \-U fish_color_search_match
    # set \-U fish_color_selection
    # set \-U fish_pager_color_prefix
    # set \-U fish_pager_color_completion
    # set \-U fish_pager_color_description
    # set \-U fish_pager_color_progress
    # set \-U fish_color_history_current
end

functions set_color_custom > set_color_custom\.fish

fisher update \.
.
.fi
.
.IP "" 0
.
.SS "COMMANDS"
Commands are plugins that extend the Fisherman CLI adding new \fBfisher <commands>\fR\.
.
.P
Create a function \fBfisher_<command>\fR
.
.IP "" 4
.
.nf

function fisher_time \-d "Say hello"
    printf "It\'s %s\en" (date +%H:%M)
end
.
.fi
.
.IP "" 0
.
.P
Test it works
.
.IP "" 4
.
.nf

fisher time
It\'s 6:30
.
.fi
.
.IP "" 0
.
.P
Make it a plugin
.
.IP "" 4
.
.nf

fisher install fisher_time
.
.fi
.
.IP "" 0
.
.SS "SNIPPETS"
Snippets are plugins that run code at the start of the shell\. Snippets must be placed inside a sub directory named conf\.d\.
.
.P
The following example implements a fish_postexec hook to display the duration of the last command in milliseconds\.
.
.IP "" 4
.
.nf

mkdir \-p runtime/conf\.d
cd runtime
$EDITOR conf\.d/fish_postexec\.fish
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf

function fish_postexec \-\-on\-event fish_postexec
    printf "%sms\en" $CMD_DURATION > /dev/stderr
end

fisher install \./postexec
.
.fi
.
.IP "" 0
.
.SH "AUTHORS"
Fisherman was created by Jorge Bucaran :: @bucaran :: \fIj@bucaran\.me\fR\.
.
.P
See THANKS\.md file for a complete list of contributors\.