mirror of
https://github.com/jorgebucaran/fisher
synced 2024-11-17 15:25:48 +00:00
6c5cac3a18
Notable changes: + Now fisher list does not show plugins that are disabled, but available in the cache. To preview these items use fisher list --disabled. + Welcome aboard @orangecms and @xrain0610. + Fisherman is now available in AUR, thanks @orangecms. + Fix load order during installation. Now snippets can safely invoke functions defined in the plugin function directory. Thanks @orangecms. #170. + Fisherman **installs and updates plugins ⌁concurrently**. Performance may vary, but if you can see 5 to 10 times faster network times, it's working well.
728 lines
11 KiB
Groff
728 lines
11 KiB
Groff
.\" 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
|
|
> superman
|
|
* 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
|
|
\.\.\.
|
|
> superman Powerline prompt based on Superman
|
|
\.\.\.
|
|
.
|
|
.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\.
|