diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f16449..0a95840 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Change Log +## [1.2.0][v120] - TBA + +* Merge tutorial and CLI documentation into one document. + +* Update README with new simplified documentation. + +* Tweak fisher help menu to highlight command aliases. + ## [1.2.0][v120] - 2016-03-08 * Introduce set_color_custom function that prompts can define to customize *fish_color_* variables. The current color palette is saved to $fisher_config/fish_colors and restored when the prompt is disabled / uninstalled #144. diff --git a/Makefile b/Makefile index e6b4278..3125996 100644 --- a/Makefile +++ b/Makefile @@ -10,8 +10,7 @@ FISHER_FILE := $(FISHER_CONFIG)/fishfile MAN := $(FISHER_HOME)/man MAN1 := $(wildcard $(MAN)/man1/*.md) -MAN7 := $(wildcard $(MAN)/man7/*.md) -DOCS := $(MAN1:%.md=%.1) $(MAN7:%.md=%.7) +DOCS := $(MAN1:%.md=%.1) INDEX := $(FISHER_CACHE)/.index VERSION = `cat $(FISHER_HOME)/VERSION` @@ -57,7 +56,7 @@ $(FISHER_CACHE): $(FISHER_FILE): touch $@ -%.1 %.7: %.md +%.1 : %.md -@if type ronn 2>/dev/null 1>&2; then \ ronn --manual=fisherman --roff $? 1>&2 2> /dev/null;\ fi;\ diff --git a/README.md b/README.md index 6363e4c..b9cc730 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,7 @@
- -**Fisherman** is a blazing fast, modern plugin manager for [fish]. - - -  ▸   **[Get Started]**
-  ▸   **[Plugins]**
+**[Fisherman]** is a blazing fast, modern plugin manager for [fish]. ```fish curl -sL get.fisherman.sh | fish @@ -27,6 +22,485 @@ curl -sL get.fisherman.sh | fish [![play]][play-link] +If you don't have Fish, you need to install it too. Install instructions can be found here. + +## Setup + +Download Fisherman using Git and setup your system automatically. See [other] install options. + +```fish +curl -sL get.fisherman.sh | fish +``` + +## CLI + +The Fisherman CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*. + +Fisherman knows the following aliases too: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. + +### Examples + +* Update Fisherman. + +```fish +fisher update +``` + +* Install plugins. + +```fish +fisher install fishtape shark get +``` + +* Install a plugin from a local directory. + +```fish +fisher install ./path/to/plugin +``` + +* Install a plugin from a URL. + +```fish +fisher install owner/repo +``` + +* Install a plugin from a Gist URL. + +```fish +fisher install gist.github.com/owner/1f40e1c6e0551b2666b2 +``` + +* Update plugins. + +```fish +fisher update shark get +``` + +* Uninstall plugins. + +```fish +fisher uninstall fishtape debug +``` + +* Uninstall plugins and remove them from the cache. + +```fish +fisher uninstall fishtape debug -f +``` + +* Show the documentation. + +```fish +fisher help +``` + +## 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. + +* List installed plugins. + +``` +fisher list + debug +* fishtape +> shellder +* spin +@ wipe +``` + +The legend consists of: + +* `*` The plugin is currently enabled +* `>` The plugin is a prompt +* `@` The plugin is a symbolic link + + +* Search the index. + +``` +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 + ... +``` + +* Get detailed information about a plugin. + +``` +fisher search shellder +> shellder by simnalamburt +Powerline prompt optimized for speed +github.com/simnalamburt/shellder +``` + +* Search plugins using tags. + +``` +fisher search --tag={git,test} + ... +* fishtape TAP producing test runner + git-branch-name Get the name of the current Git branch + git-is-repo Test if the current directory is a Git repo + git-is-dirty Test if there are changes not staged for commit + git-is-stashed Test if there are changes in the stash + ... +``` + +## Plumbing + +Fisherman commands are pipe aware. Plumb one with another to create complex functionality. + +* Update all the plugins in the cache. + +```fish +fisher list | fisher update - +``` + +* Enable all the plugins that are currently disabled. + +```fish +fisher list --disabled | fisher install +``` + +* Uninstall all the plugins and remove them from the cache. + +```fish +fisher list | fisher uninstall --force +``` + +## Dotfiles + +When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled. + +* Customize the location of the fishfile. + +```fish +set -g fisher_file ~/.dotfiles/fishfile +``` + +## 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. + +The following illustrates an example Fisherman configuration path with a single plugin and prompt. + +``` +$fisher_config +|-- cache/ +|-- conf.d/ +| `-- my_plugin.config.fish +|-- fishfile +|-- functions/ +| |-- my_plugin.fish +| |-- fish_prompt.fish +| `-- fish_right_prompt.fish +|-- completions/ +| `-- my_plugin.fish +`-- man/ + `-- man1/ + `-- my_plugin.1 +``` + +## Index + +The index is a plain text database that lists Fisherman official plugins. + +The index 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*. + +``` +z +https://github.com/fishery/fish-z +Pure-fish z directory jumping +z search cd jump +jethrokuan +``` + +If you have a plugin you would like to submit to the index, use the submit plugin. + +``` +fisher install submit +fisher submit my_plugin +``` + +Otherwise, submit the plugin manually by creating a pull request in the index repository *https://github.com/fisherman/fisher-index*. + +``` +git clone https://github.com/fisherman/fisher-index +cd index +echo "$name\n$url\n$info\n$tags\n$author\n\n" >> index +git push origin master +``` + +## Fishfile + +Fisherman keeps track of a special file known as *fishfile* to know what plugins are currently enabled. + +``` +# My Fishfile +gitio +fishtape +shark +get +shellder +``` + +This file is automatically updated as you install and uninstall plugins. + +## Variables + +* $fisher_home
+ The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default. + +* $fisher_config
+ The configuration directory. This is default location of the *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. The default location is *XDG_CONFIG_HOME/fisherman*. + +* $fisher_file
+ See FISHFILE above. + +* $fisher_cache
+ The cache directory. Plugins are downloaded to this location. + +* $fisher_alias *command*=*alias*[,*alias2*] ...
+ Use this variable to customize Fisherman command aliases. + +## Plugins + +Plugins can be utilities, prompts, commands or snippets. + +### Utilities + +Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user. + +This example walks you through creating *wtc*, a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator. + +* Create a directory and initialize a Git repository. + +```fish +mkdir wtc +cd wtc +git init +git remote add origin https://github.com//wtc +``` + +* Add the wtc function. + +```fish +function wtc -d "Generate a random commit message" + switch "$argv" + case -h --help + printf "Usage: wtc [--help]\n\n" + printf " -h --help Show usage help\n" + return + end + curl -s whatthecommit.com/index.txt +end +``` + +* Install the plugin. + +```fish +fisher install . +wtc +(\ /) +(O.o) +(> <) Bunny approves these changes. +``` + +* Commit changes and push to your remote origin when you are done. + +```fish +git add --all +git commit -m "What the commit?" +git push origin master +``` + +### Submit + +To submit wtc to the official index. + +```fish +fisher install submit +fisher submit +``` + +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. + +```fish +fisher install wtc +``` + +See `fisher help submit` for more submit options. + +### Completions + +Create a completions directory and add a completions file. + +```fish +mkdir completions +cat > completions/wtc.fish +complete --command wtc --short h --long help --description "Show usage help" +^ +``` + +Alternatively, use `__fisher_complete` to create completions from wtc usage output. + +``` +wtc --help | __fisher_complete wtc +``` + +### Docs + +Create a man/man1 directory and add a man(1) page for wtc. + +There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1). + +To create a man page manually. + +```fish +mkdir -p man/man1 +cat > man/man1/wtc.1 + + .TH man 1 "Today" "1.0" "wtc man page" + .SH NAME + wtc \- Generate a random commit message + .SH SYNOPSIS + wtc [--help] + .SH OPTIONS + -h, --help: Display help information. + .SH SEE ALSO + https://github.com/ngerakines/commitment +^C +``` + +### Dependencies + +A plugin can list dependencies to other plugins using a *fishfile*. + +Create a new file in the root of your project and add the name or URL of your desired dependencies. + +```fish +cat > fishfile +my_plugin +https://github.com/owner/another_plugin +^D +``` + +### Prompts + +Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors. + +Create a `fish_prompt` function. + +```fish +function fish_prompt + printf "%s (%s) >> " (prompt_pwd) Fisherman +end +~ (Fisherman) >> type here +``` + +To add a right prompt, create a `fish_right_prompt` function. + +```fish +function fish_right_prompt + printf "%s" (date +%H:%M:%S) +end +``` + +Save the functions to a directory and install the prompt as a plugin. + +```fish +mkdir my_prompt +cd my_prompt +functions fish_prompt > fish_prompt.fish +functions fish_right_prompt > fish_right_prompt.fish +fisher install . +``` + +Customize the colors fish uses for syntax highlighting. + +```fish +function set_color_custom + set -U fish_color_normal normal + set -U fish_color_command yellow + set -U fish_color_param white +end +functions set_color_custom > set_color_custom.fish +fisher update . +``` + +### Commands + +Commands are plugins that extend the Fisherman CLI adding new `fisher `. + +Create a function `fisher_` + +```fish +function fisher_time -d "Say hello" + printf "It's %s\n" (date +%H:%M) +end +``` + +Test it works + +```fish +fisher time +It's 6:30 +``` + +Make it a plugin + + +```fish +fisher install fisher_time +``` + +This creates a new directory fisher_time in the current working directory and installs the plugin. + +The following example implements a command to format plugin information into columns. + +```fish +function fisher_info -d "Display information about plugins" + switch "$argv" + case -h --help + printf "Usage: fisher info [...]\n\n" + printf " -h --help Show usage help\n" + return + end + + for item in $argv + fisher search $item --name --info + end | sed -E 's/;/: /' | column +end + +fisher install fisher_info +``` + +### Snippets + +Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d. + +The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds. + +```fish +mkdir -p runtime/conf.d +cd runtime +cat > conf.d/fish_postexec.fish +function fish_postexec --on-event fish_postexec + printf "%sms\n" $CMD_DURATION > /dev/stderr +end +^D +fisher install ./postexec +``` [travis-link]: https://travis-ci.org/fisherman/fisherman [travis-badge]: https://img.shields.io/travis/fisherman/fisherman.svg?style=flat-square @@ -43,3 +517,6 @@ curl -sL get.fisherman.sh | fish [Get Started]: https://github.com/fisherman/fisherman/wiki [Plugins]: http://fisherman.sh/#search [fish]: https://github.com/fish-shell/fish-shell + +[other]: https://github.com/fisherman/fisherman/wiki/Installing-Fisherman#notes +[Fisherman]: http://fisherman.sh diff --git a/completions/fisher.fish b/completions/fisher.fish index 3c011a5..b087ec4 100644 --- a/completions/fisher.fish +++ b/completions/fisher.fish @@ -1,16 +1,11 @@ set -l IFS ";" complete -xc fisher - +complete -c fisher -a "fisherman" -d "Update Fisherman" -n "__fish_seen_subcommand_from update" +complete -c fisher -a "tutorial" -d "An introduction to Fisherman" -n "__fish_seen_subcommand_from help" complete -c fisher -n "__fish_use_subcommand" -s h -l help -d "Show usage help" complete -c fisher -n "__fish_use_subcommand" -s v -l version -d "Show version information" -complete -c fisher -a "fisherman" -d "Update Fisherman" -n "__fish_seen_subcommand_from update" - -__fisher_help_guides | while read -l guide info - complete -c fisher -n "__fish_seen_subcommand_from help" -a $guide -d "$info" -end - __fisher_help_commands | while read -l command info complete -c fisher -n "__fish_use_subcommand" -a $command -d "$info" complete -c fisher -n "__fish_seen_subcommand_from help" -a $command -d "$info" diff --git a/functions/__fisher_help_guides.fish b/functions/__fisher_help_guides.fish deleted file mode 100644 index 7271775..0000000 --- a/functions/__fisher_help_guides.fish +++ /dev/null @@ -1,4 +0,0 @@ -function __fisher_help_guides - sed -nE 's/(fisher-)?(.+)\([0-9]\) -- (.+)/\2;\3/p' \ - {$fisher_home,$fisher_config}/man/man{5,7}/fisher*.md | sort -r -end diff --git a/functions/fisher.fish b/functions/fisher.fish index f52e0ef..7ddffe6 100644 --- a/functions/fisher.fish +++ b/functions/fisher.fish @@ -33,7 +33,7 @@ function fisher -d "Fish plugin manager" case \* if test -z "$fisher_alias" - set fisher_alias install=i update=u search=s list=l help=h + set -g fisher_alias install=i update=u search=s list=l help=h end printf "%s\n" $fisher_alias | sed 's/[=,]/ /g' | while read -la alias @@ -66,27 +66,21 @@ function fisher -d "Fish plugin manager" sed 's/^/fisher version /' $fisher_home/VERSION case help - if test -z "$value" - set value commands - end - printf "Usage: fisher [] [--help] [--version]\n\n" - switch commands - case $value - printf "Available Commands:\n" - fisher_help --commands=bare - echo - end + set -l color (set_color $fish_color_command -u) + set -l color_normal (set_color normal) - switch guides - case $value - printf "Other Documentation:\n" - fisher_help --guides=bare - echo - end + printf "Available Commands:\n" - printf "Use 'fisher help -g' to list guides and other documentation.\n" - printf "See 'fisher help ' to access a man page.\n" + fisher_help --commands=bare | sed -E " + s/ (h)/ $color\1$color_normal/ + s/ (i)/ $color\1$color_normal/ + s/ (l)/ $color\1$color_normal/ + s/ (s)/ $color\1$color_normal/ + s/ (u)p/ $color\1$color_normal"p"/ + " + + printf "\nUse fisher help to access a man page.\n" end end diff --git a/functions/fisher_help.fish b/functions/fisher_help.fish index eb31379..f823a8d 100644 --- a/functions/fisher_help.fish +++ b/functions/fisher_help.fish @@ -13,14 +13,6 @@ function fisher_help -d "Show help" set option man set value $2 - case a all - set option guides commands - set value $2 - - case g guides - set option $option guides - set value $2 - case commands set option $option commands set value $2 @@ -30,10 +22,7 @@ function fisher_help -d "Show help" set value $value $2 case h - printf "Usage: fisher help [] [--all] [--guides] [--help]\n\n" - printf " -a --all List all the documentation\n" - printf " -g --guides List available guides\n" - printf " -h --help Show usage help\n" + printf "Usage: fisher help [] [--help]\n" return case \* @@ -68,14 +57,8 @@ function fisher_help -d "Show help" return end - begin - if contains -- commands $option - __fisher_help_commands - end - - if contains -- guides $option - __fisher_help_guides - end - end | sed 's/^/ /;s/;/'\t'/' | column -ts\t + if contains -- commands $option + __fisher_help_commands + end | sed 's/^/ /;s/;/'\t'/' | column -ts\t end end diff --git a/man/man1/fisher-tutorial.1 b/man/man1/fisher-tutorial.1 new file mode 120000 index 0000000..ba5e5c8 --- /dev/null +++ b/man/man1/fisher-tutorial.1 @@ -0,0 +1 @@ +/Users/bucaran/c/fisherman/fisherman/man/man1/fisher.1 \ No newline at end of file diff --git a/man/man1/fisher.1 b/man/man1/fisher.1 index ca23b4b..1352ef3 100644 --- a/man/man1/fisher.1 +++ b/man/man1/fisher.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "FISHER" "1" "February 2016" "" "fisherman" +.TH "FISHER" "1" "March 2016" "" "fisherman" . .SH "NAME" \fBfisher\fR \- Fish plugin manager @@ -15,7 +15,7 @@ fisher \fIcommand\fR [\fIarguments\fR] [\-\-version] [\-\-help] Fisherman is a plugin manager for fish\. . .P -The Fisherman CLI consists of the following commands: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR\. +The CLI consists of the following commands: \fIinstall\fR, \fIupdate\fR, \fIuninstall\fR, \fIlist\fR, \fIsearch\fR and \fIhelp\fR\. . .SH "USAGE" Run a command\. @@ -44,7 +44,7 @@ fisher help .IP "" 0 . .P -Fisherman knows the following aliases by default: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\. +Fisherman knows the following too: \fIi\fR for install, \fIu\fR for update, \fIl\fR for list, \fIs\fR for search and \fIh\fR for help\. . .SH "OPTIONS" . @@ -57,41 +57,7 @@ Show version information\. Fisherman follows Semantic Versioning and uses Git an Show usage help\. . .SH "EXAMPLES" -. -.IP "\(bu" 4 -Install plugins\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -fisher install fishtape shark get -. -.fi -. -.IP "" 0 -. -.IP "\(bu" 4 -Install a plugin as a symbolic link\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -fisher install \./path/to/plugin -. -.fi -. -.IP "" 0 -. -.IP "\(bu" 4 -Update Fisherman to the latest version\. -. -.IP "" 0 +Update Fisherman\. . .IP "" 4 . @@ -103,26 +69,100 @@ fisher update . .IP "" 0 . -.IP "\(bu" 4 -Search the Fisherman index\. -. -.IP "" 0 +.P +Install plugins\. . .IP "" 4 . .nf -fisher search +fisher install fishtape shark get . .fi . .IP "" 0 . -.IP "\(bu" 4 -Show all the documentation\. +.P +Install a plugin from a local directory\. +. +.IP "" 4 +. +.nf + +fisher install \./path/to/plugin +. +.fi . .IP "" 0 . +.P +Install a plugin from a URL\. +. +.IP "" 4 +. +.nf + +fisher install owner/repo +. +.fi +. +.IP "" 0 +. +.P +Install a plugin from a Gist URL\. +. +.IP "" 4 +. +.nf + +fisher install gist\.github\.com/owner/1f40e1c6e0551b2666b2 +. +.fi +. +.IP "" 0 +. +.P +Update plugins\. +. +.IP "" 4 +. +.nf + +fisher update shark get +. +.fi +. +.IP "" 0 +. +.P +Uninstall plugins\. +. +.IP "" 4 +. +.nf + +fisher uninstall fishtape debug +. +.fi +. +.IP "" 0 +. +.P +Uninstall plugins and remove them from the cache\. +. +.IP "" 4 +. +.nf + +fisher uninstall fishtape debug \-f +. +.fi +. +.IP "" 0 +. +.P +Show all the documentation\. +. .IP "" 4 . .nf @@ -133,9 +173,159 @@ fisher help \-\-all . .IP "" 0 . -.SH "CONCEPTS" +.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\. . -.SS "FLAT TREE" +.P +List installed plugins\. +. +.IP "" 4 +. +.nf + +fisher list + debug +* fishtape +> shellder +* spin +@ wipe +. +.fi +. +.IP "" 0 +. +.P +The legend consists of: +. +.P +\fB*\fR The plugin is currently enabled +. +.br +\fB>\fR The plugin is a prompt +. +.br +\fB@\fR The plugin is a symbolic link +. +.br +. +.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 +Get detailed information about a plugin\. +. +.IP "" 4 +. +.nf + +fisher search shellder +> shellder by simnalamburt +Powerline prompt optimized for speed +github\.com/simnalamburt/shellder +. +.fi +. +.IP "" 0 +. +.P +Search plugins 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\-repo Test if the current directory is a Git repo + git\-is\-dirty Test if there are changes not staged for commit + git\-is\-stashed Test if there are changes in the stash + \.\.\. +. +.fi +. +.IP "" 0 +. +.SH "PLUMBING" +Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\. +. +.P +Update all the plugins in the cache\. +. +.IP "" 4 +. +.nf + +fisher list | fisher update \- +. +.fi +. +.IP "" 0 +. +.P +Enable all the plugins that are 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 a file known as \fIfishfile\fR to track what plugins are currently enabled\. +. +.P +To customize its location: +. +.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 @@ -164,42 +354,7 @@ $fisher_config . .IP "" 0 . -.SS "PLUGINS" -To install plugins, type fisher install and press \fItab\fR once to list all the available plugins\. Similarly, use fisher update / uninstall and press \fItab\fR to see what plugins you can update or uninstall\. -. -.P -To search plugins use fisher search \fIname\fR\. You can by a specific field using fisher search \-\-\fIfield\fR=\fImatch\fR\. -. -.IP "" 4 -. -.nf - -fisher search \-\-tag={*keywords*} -. -.fi -. -.IP "" 0 -. -.P -or -. -.IP "" 4 -. -.nf - -fisher search \-\-name=*name* -. -.fi -. -.IP "" 0 -. -.P -See fisher help search for advanced options\. -. -.P -To learn how to create plugins enter fisher help tutorial\. -. -.SS "INDEX" +.SH "INDEX" The index is a plain text database that lists Fisherman official plugins\. . .P @@ -223,7 +378,7 @@ jethrokuan .IP "" 0 . .P -If you have a plugin you would like to submit to the index, use the submit plugin\. +If you have a plugin to submit to the index, use the \fIsubmit\fR plugin\. . .IP "" 4 . @@ -252,7 +407,7 @@ git push origin master . .IP "" 0 . -.SS "FISHFILE" +.SH "FISHFILE" Fisherman keeps track of a special file known as \fIfishfile\fR to know what plugins are currently enabled\. . .IP "" 4 @@ -273,7 +428,7 @@ shellder .P This file is automatically updated as you install and uninstall plugins\. . -.SS "VARIABLES" +.SH "VARIABLES" . .TP $fisher_home @@ -295,6 +450,379 @@ The cache directory\. Plugins are downloaded to this location\. $fisher_alias \fIcommand\fR=\fIalias\fR[,\fIalias2\fR] \.\.\. Use this variable to customize Fisherman command aliases\. . +.SH "PLUGINS" +Plugins can be utilities, prompts, commands or snippets\. +. +.SS "UTILITIES" +Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user\. +. +.P +This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\. +. +.P +Create a directory and initialize a Git repository\. +. +.IP "" 4 +. +.nf + +mkdir wtc +cd wtc +git init +git remote add origin https://github\.com//wtc +. +.fi +. +.IP "" 0 +. +.P +Add the wtc function\. +. +.IP "" 4 +. +.nf + +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 +. +.fi +. +.IP "" 0 +. +.P +Install the plugin\. +. +.IP "" 4 +. +.nf + +fisher install \. +wtc +(\e /) +(O\.o) +(> <) Bunny approves these changes\. +. +.fi +. +.IP "" 0 +. +.P +Commit changes and push to your remote origin when you are done\. +. +.IP "" 4 +. +.nf + +git add \-\-all +git commit \-m "What the commit?" +git push origin master +. +.fi +. +.IP "" 0 +. +.P +To submit wtc to the official index\. +. +.IP "" 4 +. +.nf + +fisher install submit +fisher submit +. +.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 +See \fBfisher help submit\fR for more submit options\. +. +.P +Create a completions directory and add a completions file\. +. +.IP "" 4 +. +.nf + +mkdir completions +cat > completions/wtc\.fish +complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help" +^ +. +.fi +. +.IP "" 0 +. +.P +Alternatively, use \fB__fisher_complete\fR to create completions from wtc usage output\. +. +.IP "" 4 +. +.nf + +wtc \-\-help | __fisher_complete wtc +. +.fi +. +.IP "" 0 +. +.P +Create a man/man1 directory and add a man(1) page for wtc\. +. +.P +There are utilities that can help you generate man pages from various text formats\. For example, pandoc(1) and ronn(1)\. +. +.P +To create a man page manually\. +. +.IP "" 4 +. +.nf + +mkdir \-p man/man1 +cat > man/man1/wtc\.1 + + \.TH man 1 "Today" "1\.0" "wtc man page" + \.SH NAME + wtc \e\- Generate a random commit message + \.SH SYNOPSIS + wtc [\-\-help] + \.SH OPTIONS + \-h, \-\-help: Display help information\. + \.SH SEE ALSO + https://github\.com/ngerakines/commitment +^C +. +.fi +. +.IP "" 0 +. +.P +A plugin can list dependencies to other plugins using a \fIfishfile\fR\. +. +.P +Create a new file in the root of your project and add the name or URL of your desired dependencies\. +. +.IP "" 4 +. +.nf + +cat > fishfile +my_plugin +https://github\.com/owner/another_plugin +^D +. +.fi +. +.IP "" 0 +. +.SS "PROMPTS" +Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors\. +. +.P +Create a \fBfish_prompt\fR function\. +. +.IP "" 4 +. +.nf + +function fish_prompt + printf "%s (%s) >> " (prompt_pwd) Fisherman +end +~ (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 \fR\. +. +.P +Create a function \fBfisher_\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 +. +.P +This creates a new directory fisher_time in the current working directory and installs the plugin\. +. +.P +The following example implements a command to format plugin information into columns\. +. +.IP "" 4 +. +.nf + +function fisher_info \-d "Display information about plugins" + switch "$argv" + case \-h \-\-help + printf "Usage: fisher info [\.\.\.]\en\en" + printf " \-h \-\-help Show usage help\en" + return + end + + for item in $argv + fisher search $item \-\-name \-\-info + end | sed \-E \'s/;/: /\' | column +end + +fisher install fisher_info +. +.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 the fish_postexec hook to display the runtime of the last command in milliseconds\. +. +.IP "" 4 +. +.nf + +mkdir \-p runtime/conf\.d +cd runtime +cat > conf\.d/fish_postexec\.fish +function fish_postexec \-\-on\-event fish_postexec + printf "%sms\en" $CMD_DURATION > /dev/stderr +end +^D +fisher install \./postexec +. +.fi +. +.IP "" 0 +. .SH "AUTHORS" Fisherman was created by Jorge Bucaran :: @bucaran :: \fIj@bucaran\.me\fR\. . diff --git a/man/man1/fisher.md b/man/man1/fisher.md index e97f80f..b41614b 100644 --- a/man/man1/fisher.md +++ b/man/man1/fisher.md @@ -9,7 +9,7 @@ fisher *command* [*arguments*] [--version] [--help]
Fisherman is a plugin manager for fish. -The Fisherman CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*. +The CLI consists of the following commands: *install*, *update*, *uninstall*, *list*, *search* and *help*. ## USAGE @@ -25,7 +25,7 @@ Get help about a command. fisher help ``` -Fisherman knows the following aliases by default: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. +Fisherman knows the following too: *i* for install, *u* for update, *l* for list, *s* for search and *h* for help. ## OPTIONS @@ -37,39 +37,152 @@ Fisherman knows the following aliases by default: *i* for install, *u* for updat ## EXAMPLES -* Install plugins. - -```fish -fisher install fishtape shark get -``` - -* Install a plugin as a symbolic link. - -```fish -fisher install ./path/to/plugin -``` - -* Update Fisherman to the latest version. +Update Fisherman. ```fish fisher update ``` -* Search the Fisherman index. +Install plugins. ```fish -fisher search +fisher install fishtape shark get ``` -* Show all the documentation. +Install a plugin from a local directory. + +```fish +fisher install ./path/to/plugin +``` + +Install a plugin from a URL. + +```fish +fisher install owner/repo +``` + +Install a plugin from a Gist URL. + +```fish +fisher install gist.github.com/owner/1f40e1c6e0551b2666b2 +``` + +Update plugins. + +``` +fisher update shark get +``` + +Uninstall plugins. + +``` +fisher uninstall fishtape debug +``` + +Uninstall plugins and remove them from the cache. + +``` +fisher uninstall fishtape debug -f +``` + +Show all the documentation. ```fish fisher help --all ``` -## CONCEPTS +## LIST AND SEARCH -### FLAT TREE +The list command displays all the plugins you have installed. The search command queries the index to show what's available to install. + +List installed plugins. + +``` +fisher list + debug +* fishtape +> shellder +* spin +@ wipe +``` + +The legend consists of: + +`*` The plugin is currently enabled
+`>` The plugin is a prompt
+`@` The plugin is a symbolic link
+ +Search the index. + +``` +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 + ... +``` + +Get detailed information about a plugin. + +``` +fisher search shellder +> shellder by simnalamburt +Powerline prompt optimized for speed +github.com/simnalamburt/shellder +``` + +Search plugins using tags. + +``` +fisher search --tag={git,test} + ... +* fishtape TAP producing test runner + git-branch-name Get the name of the current Git branch + git-is-repo Test if the current directory is a Git repo + git-is-dirty Test if there are changes not staged for commit + git-is-stashed Test if there are changes in the stash + ... +``` + +## PLUMBING + +Fisherman commands are pipe aware. Plumb one with another to create complex functionality. + +Update all the plugins in the cache. + +```fish +fisher list | fisher update - +``` + +Enable all the plugins that are currently disabled. + +```fish +fisher list --disabled | fisher install +``` + +Uninstall all the plugins and remove them from the cache. + +```fish +fisher list | fisher uninstall --force +``` + +## DOTFILES + +When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled. + +To customize its location: + +```fish +set -g fisher_file ~/.dotfiles/fishfile +``` + +## 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. @@ -92,27 +205,7 @@ $fisher_config `-- my_plugin.1 ``` -### PLUGINS - -To install plugins, type fisher install and press *tab* once to list all the available plugins. Similarly, use fisher update / uninstall and press *tab* to see what plugins you can update or uninstall. - -To search plugins use fisher search *name*. You can by a specific field using fisher search --*field*=*match*. - -```fish -fisher search --tag={*keywords*} -``` - -or - -```fish -fisher search --name=*name* -``` - -See fisher help search for advanced options. - -To learn how to create plugins enter fisher help tutorial. - -### INDEX +## INDEX The index is a plain text database that lists Fisherman official plugins. @@ -128,7 +221,7 @@ z search cd jump jethrokuan ``` -If you have a plugin you would like to submit to the index, use the submit plugin. +If you have a plugin to submit to the index, use the *submit* plugin. ``` fisher install submit @@ -144,7 +237,7 @@ echo "$name\n$url\n$info\n$tags\n$author\n\n" >> index git push origin master ``` -### FISHFILE +## FISHFILE Fisherman keeps track of a special file known as *fishfile* to know what plugins are currently enabled. @@ -159,7 +252,7 @@ shellder This file is automatically updated as you install and uninstall plugins. -### VARIABLES +## VARIABLES * $fisher_home: The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default. @@ -176,6 +269,255 @@ This file is automatically updated as you install and uninstall plugins. * $fisher_alias *command*=*alias*[,*alias2*] ...: Use this variable to customize Fisherman command aliases. + +## PLUGINS + +Plugins can be utilities, prompts, commands or snippets. + +### UTILITIES + +Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user. + +This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator. + +Create a directory and initialize a Git repository. + +```fish +mkdir wtc +cd wtc +git init +git remote add origin https://github.com//wtc +``` + +Add the wtc function. + +```fish +function wtc -d "Generate a random commit message" + switch "$argv" + case -h --help + printf "Usage: wtc [--help]\n\n" + printf " -h --help Show usage help\n" + return + end + curl -s whatthecommit.com/index.txt +end +``` + +Install the plugin. + +```fish +fisher install . +wtc +(\ /) +(O.o) +(> <) Bunny approves these changes. +``` + +Commit changes and push to your remote origin when you are done. + +```fish +git add --all +git commit -m "What the commit?" +git push origin master +``` + +#### SUBMIT + +To submit wtc to the official index. + +```fish +fisher install submit +fisher submit +``` + +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. + +```fish +fisher install wtc +``` + +See `fisher help submit` for more submit options. + +#### COMPLETIONS + +Create a completions directory and add a completions file. + +```fish +mkdir completions +cat > completions/wtc.fish +complete --command wtc --short h --long help --description "Show usage help" +^ +``` + +Alternatively, use `__fisher_complete` to create completions from wtc usage output. + +``` +wtc --help | __fisher_complete wtc +``` + +#### DOCS + +Create a man/man1 directory and add a man(1) page for wtc. + +There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1). + +To create a man page manually. + +```fish +mkdir -p man/man1 +cat > man/man1/wtc.1 + + .TH man 1 "Today" "1.0" "wtc man page" + .SH NAME + wtc \- Generate a random commit message + .SH SYNOPSIS + wtc [--help] + .SH OPTIONS + -h, --help: Display help information. + .SH SEE ALSO + https://github.com/ngerakines/commitment +^C +``` + +#### DEPENDENCIES + +A plugin can list dependencies to other plugins using a *fishfile*. + +Create a new file in the root of your project and add the name or URL of your desired dependencies. + +```fish +cat > fishfile +my_plugin +https://github.com/owner/another_plugin +^D +``` + +### PROMPTS + +Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors. + +Create a `fish_prompt` function. + +```fish +function fish_prompt + printf "%s (%s) >> " (prompt_pwd) Fisherman +end +~ (Fisherman) >> type here +``` + +To add a right prompt, create a `fish_right_prompt` function. + +```fish +function fish_right_prompt + printf "%s" (date +%H:%M:%S) +end +``` + +Save the functions to a directory and install the prompt as a plugin. + +```fish +mkdir my_prompt +cd my_prompt +functions fish_prompt > fish_prompt.fish +functions fish_right_prompt > fish_right_prompt.fish +fisher install . +``` + +Customize the colors fish uses for syntax highlighting. + +```fish +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 . +``` + +### COMMANDS + +Commands are plugins that extend the Fisherman CLI adding new `fisher `. + +Create a function `fisher_` + +```fish +function fisher_time -d "Say hello" + printf "It's %s\n" (date +%H:%M) +end +``` + +Test it works + +```fish +fisher time +It's 6:30 +``` + +Make it a plugin + + +```fish +fisher install fisher_time +``` + +This creates a new directory fisher_time in the current working directory and installs the plugin. + +The following example implements a command to format plugin information into columns. + +```fish +function fisher_info -d "Display information about plugins" + switch "$argv" + case -h --help + printf "Usage: fisher info [...]\n\n" + printf " -h --help Show usage help\n" + return + end + + for item in $argv + fisher search $item --name --info + end | sed -E 's/;/: /' | column +end + +fisher install fisher_info +``` + +### SNIPPETS + +Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d. + +The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds. + +```fish +mkdir -p runtime/conf.d +cd runtime +cat > conf.d/fish_postexec.fish +function fish_postexec --on-event fish_postexec + printf "%sms\n" $CMD_DURATION > /dev/stderr +end +^D +fisher install ./postexec +``` + ## AUTHORS Fisherman was created by Jorge Bucaran :: @bucaran :: *j@bucaran.me*. diff --git a/man/man7/fisher-configuration.7 b/man/man7/fisher-configuration.7 deleted file mode 120000 index 4eec581..0000000 --- a/man/man7/fisher-configuration.7 +++ /dev/null @@ -1 +0,0 @@ -fisher-config.7 \ No newline at end of file diff --git a/man/man7/fisher-tutorial.7 b/man/man7/fisher-tutorial.7 deleted file mode 100644 index d2e74e4..0000000 --- a/man/man7/fisher-tutorial.7 +++ /dev/null @@ -1,537 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "FISHER\-TUTORIAL" "7" "February 2016" "" "fisherman" -. -.SH "NAME" -\fBfisher\-tutorial\fR \- A tutorial introduction to Fisherman -. -.SH "DESCRIPTION" -This document tells you how to start using Fisherman key features\. -. -.SH "INSTALLING PLUGINS" -Install a plugin\. -. -.IP "" 4 -. -.nf - -fisher install -. -.fi -. -.IP "" 0 -. -.P -\fIplugin\fR can be name registered in the Fisherman index, a URL to a Git repository or a path in the local system\. Plugins are collected in a special location inside the Fisherman\'s configuration directory known as the cache\. -. -.SH "UPDATE AND UNINSTALL" -Update a plugin\. -. -.IP "" 4 -. -.nf - -fisher update -. -.fi -. -.IP "" 0 -. -.P -Uninstall a plugin\. -. -.IP "" 4 -. -.nf - -fisher uninstall -. -.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 -The legend consists of: -. -.P -\fB*\fR Indicate the plugin is currently installed -. -.br -\fB>\fR Indicate the plugin is a prompt -. -.br -\fB@\fR Indicate the plugin is a symbolic link -. -.br -. -.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 -Get detailed information about a plugin\. -. -.IP "" 4 -. -.nf - -fisher search shellder -> shellder by simnalamburt -Powerline prompt optimized for speed -github\.com/simnalamburt/shellder -. -.fi -. -.IP "" 0 -. -.P -Search plugins 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\-repo Test if the current directory is a Git repo - git\-is\-dirty Test if there are changes not staged for commit - git\-is\-stashed Test if there are changes in the stash - \.\.\. -. -.fi -. -.IP "" 0 -. -.SH "PLUMBING" -Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\. -. -.P -Update all the plugins in the cache\. -. -.IP "" 4 -. -.nf - -fisher list | fisher update \- -. -.fi -. -.IP "" 0 -. -.P -Install all the plugins that are currently disabled\. -. -.IP "" 4 -. -.nf - -fisher list \-\-disabled | fisher install -. -.fi -. -.IP "" 0 -. -.SH "DOTFILES" -When you install a plugin, Fisherman updates a file known as \fIfishfile\fR to track what plugins are currently enabled\. -. -.P -To customize its location: -. -.IP "" 4 -. -.nf - -set \-g fisher_file ~/\.dotfiles/fishfile -. -.fi -. -.IP "" 0 -. -.SH "PLUGINS" -Plugins can be utilities, prompts, commands or snippets\. -. -.SS "UTILITIES" -Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user\. -. -.P -This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\. -. -.IP "\(bu" 4 -Create a directory and initialize a Git repository\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -mkdir wtc -cd wtc -git init -git remote add origin https://github\.com//wtc -. -.fi -. -.IP "" 0 -. -.IP "\(bu" 4 -Add the wtc function\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -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 -. -.fi -. -.IP "" 0 -. -.IP "\(bu" 4 -Install the plugin\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -fisher install \. -wtc -(\e /) -(O\.o) -(> <) Bunny approves these changes\. -. -.fi -. -.IP "" 0 -. -.IP "\(bu" 4 -Commit changes and push to your remote origin when you are done\. -. -.IP "" 0 -. -.IP "" 4 -. -.nf - -git add \-\-all -git commit \-m "What the commit?" -git push origin master -. -.fi -. -.IP "" 0 -. -.P -To submit wtc to the official index\. -. -.IP "" 4 -. -.nf - -fisher install submit -fisher submit -. -.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 -See \fBfisher help submit\fR for more submit options\. -. -.P -Create a completions directory and add a completions file\. -. -.IP "" 4 -. -.nf - -mkdir completions -cat > completions/wtc\.fish -complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help" -^ -. -.fi -. -.IP "" 0 -. -.P -Alternatively, use \fB__fisher_complete\fR to create completions from wtc usage output\. -. -.IP "" 4 -. -.nf - -wtc \-\-help | __fisher_complete wtc -. -.fi -. -.IP "" 0 -. -.P -Create a man/man1 directory and add a man(1) page for wtc\. -. -.P -There are utilities that can help you generate man pages from various text formats\. For example, pandoc(1) and ronn(1)\. -. -.P -To create a man page manually\. -. -.IP "" 4 -. -.nf - -mkdir \-p man/man1 -cat > man/man1/wtc\.1 - - \.TH man 1 "Today" "1\.0" "wtc man page" - \.SH NAME - wtc \e\- Generate a random commit message - \.SH SYNOPSIS - wtc [\-\-help] - \.SH OPTIONS - \-h, \-\-help: Display help information\. - \.SH SEE ALSO - https://github\.com/ngerakines/commitment -^C -. -.fi -. -.IP "" 0 -. -.P -A plugin can list dependencies to other plugins using a \fIfishfile\fR\. -. -.P -Create a new file in the root of your project and add the name or URL of your desired dependencies\. -. -.IP "" 4 -. -.nf - -cat > fishfile -my_plugin -https://github\.com/owner/another_plugin -^D -. -.fi -. -.IP "" 0 -. -.SS "PROMPTS" -Prompts, also known as themes, are plugins that modify the appearance of the shell prompt\. -. -.P -Create a \fBfish_prompt\fR function\. -. -.IP "" 4 -. -.nf - -function fish_prompt - printf "%s (%s) >> " (prompt_pwd) Fisherman -end -~ (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 -. -.SS "COMMANDS" -Commands are plugins that extend the Fisherman CLI adding new \fBfisher \fR\. -. -.P -Create a function \fBfisher_\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 -. -.P -This creates a new directory fisher_time in the current working directory and installs the plugin\. -. -.P -The following example implements a command to format plugin information into columns\. -. -.IP "" 4 -. -.nf - -function fisher_info \-d "Display information about plugins" - switch "$argv" - case \-h \-\-help - printf "Usage: fisher info [\.\.\.]\en\en" - printf " \-h \-\-help Show usage help\en" - return - end - - for item in $argv - fisher search $item \-\-name \-\-info - end | sed \-E \'s/;/: /\' | column -end - -fisher install fisher_info -. -.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 the fish_postexec hook to display the runtime of the last command in milliseconds\. -. -.IP "" 4 -. -.nf - -mkdir \-p runtime/conf\.d -cd runtime -cat > conf\.d/fish_postexec\.fish -function fish_postexec \-\-on\-event fish_postexec - printf "%sms\en" $CMD_DURATION > /dev/stderr -end -^D -fisher install \./postexec -. -.fi -. -.IP "" 0 -. -.SH "SEE ALSO" -fisher(1) diff --git a/man/man7/fisher-tutorial.md b/man/man7/fisher-tutorial.md deleted file mode 100644 index 598c807..0000000 --- a/man/man7/fisher-tutorial.md +++ /dev/null @@ -1,336 +0,0 @@ -fisher-tutorial(7) -- A tutorial introduction to Fisherman -========================================================== - -## DESCRIPTION - -This document tells you how to start using Fisherman key features. - -## INSTALLING PLUGINS - -Install a plugin. - -``` -fisher install -``` - -*plugin* can be name registered in the Fisherman index, a URL to a Git repository or a path in the local system. Plugins are collected in a special location inside the Fisherman's configuration directory known as the cache. - -## UPDATE AND UNINSTALL - -Update a plugin. - -``` -fisher update -``` - -Uninstall a plugin. - -``` -fisher uninstall -``` - -## 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. - -List installed plugins. - -``` -fisher list - debug -* fishtape -> shellder -* spin -@ wipe -``` - -The legend consists of: - -`*` Indicate the plugin is currently installed
-`>` Indicate the plugin is a prompt
-`@` Indicate the plugin is a symbolic link
- -Search the index. - -``` -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 - ... -``` - -Get detailed information about a plugin. - -``` -fisher search shellder -> shellder by simnalamburt -Powerline prompt optimized for speed -github.com/simnalamburt/shellder -``` - -Search plugins using tags. - -``` -fisher search --tag={git,test} - ... -* fishtape TAP producing test runner - git-branch-name Get the name of the current Git branch - git-is-repo Test if the current directory is a Git repo - git-is-dirty Test if there are changes not staged for commit - git-is-stashed Test if there are changes in the stash - ... -``` - -## PLUMBING - -Fisherman commands are pipe aware. Plumb one with another to create complex functionality. - -Update all the plugins in the cache. - -```fish -fisher list | fisher update - -``` - -Install all the plugins that are currently disabled. - -```fish -fisher list --disabled | fisher install -``` - -## DOTFILES - -When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled. - -To customize its location: - -```fish -set -g fisher_file ~/.dotfiles/fishfile -``` - -## PLUGINS - -Plugins can be utilities, prompts, commands or snippets. - -### UTILITIES - -Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user. - -This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator. - -* Create a directory and initialize a Git repository. - -```fish -mkdir wtc -cd wtc -git init -git remote add origin https://github.com//wtc -``` - -* Add the wtc function. - -```fish -function wtc -d "Generate a random commit message" - switch "$argv" - case -h --help - printf "Usage: wtc [--help]\n\n" - printf " -h --help Show usage help\n" - return - end - curl -s whatthecommit.com/index.txt -end -``` - -* Install the plugin. - -```fish -fisher install . -wtc -(\ /) -(O.o) -(> <) Bunny approves these changes. -``` - -* Commit changes and push to your remote origin when you are done. - -```fish -git add --all -git commit -m "What the commit?" -git push origin master -``` - -#### SUBMIT - -To submit wtc to the official index. - -```fish -fisher install submit -fisher submit -``` - -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. - -```fish -fisher install wtc -``` - -See `fisher help submit` for more submit options. - -#### COMPLETIONS - -Create a completions directory and add a completions file. - -```fish -mkdir completions -cat > completions/wtc.fish -complete --command wtc --short h --long help --description "Show usage help" -^ -``` - -Alternatively, use `__fisher_complete` to create completions from wtc usage output. - -``` -wtc --help | __fisher_complete wtc -``` - -#### MAN - -Create a man/man1 directory and add a man(1) page for wtc. - -There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1). - -To create a man page manually. - -```fish -mkdir -p man/man1 -cat > man/man1/wtc.1 - - .TH man 1 "Today" "1.0" "wtc man page" - .SH NAME - wtc \- Generate a random commit message - .SH SYNOPSIS - wtc [--help] - .SH OPTIONS - -h, --help: Display help information. - .SH SEE ALSO - https://github.com/ngerakines/commitment -^C -``` - -#### DEPENDENCIES - -A plugin can list dependencies to other plugins using a *fishfile*. - -Create a new file in the root of your project and add the name or URL of your desired dependencies. - -```fish -cat > fishfile -my_plugin -https://github.com/owner/another_plugin -^D -``` - -### PROMPTS - -Prompts, also known as themes, are plugins that modify the appearance of the shell prompt. - -Create a `fish_prompt` function. - -```fish -function fish_prompt - printf "%s (%s) >> " (prompt_pwd) Fisherman -end -~ (Fisherman) >> type here -``` - -To add a right prompt, create a `fish_right_prompt` function. - -```fish -function fish_right_prompt - printf "%s" (date +%H:%M:%S) -end -``` - -Save the functions to a directory and install the prompt as a plugin. - -```fish -mkdir my_prompt -cd my_prompt -functions fish_prompt > fish_prompt.fish -functions fish_right_prompt > fish_right_prompt.fish -fisher install . -``` - -### COMMANDS - -Commands are plugins that extend the Fisherman CLI adding new `fisher `. - -Create a function `fisher_` - -```fish -function fisher_time -d "Say hello" - printf "It's %s\n" (date +%H:%M) -end -``` - -Test it works - -```fish -fisher time -It's 6:30 -``` - -Make it a plugin - - -```fish -fisher install fisher_time -``` - -This creates a new directory fisher_time in the current working directory and installs the plugin. - -The following example implements a command to format plugin information into columns. - -```fish -function fisher_info -d "Display information about plugins" - switch "$argv" - case -h --help - printf "Usage: fisher info [...]\n\n" - printf " -h --help Show usage help\n" - return - end - - for item in $argv - fisher search $item --name --info - end | sed -E 's/;/: /' | column -end - -fisher install fisher_info -``` - -### SNIPPETS - -Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d. - -The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds. - -```fish -mkdir -p runtime/conf.d -cd runtime -cat > conf.d/fish_postexec.fish -function fish_postexec --on-event fish_postexec - printf "%sms\n" $CMD_DURATION > /dev/stderr -end -^D -fisher install ./postexec -``` - -## SEE ALSO - -fisher(1) diff --git a/man/man7/fisher.7 b/man/man7/fisher.7 deleted file mode 120000 index a6d0070..0000000 --- a/man/man7/fisher.7 +++ /dev/null @@ -1 +0,0 @@ -/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7 \ No newline at end of file diff --git a/man/man7/fisherman.7 b/man/man7/fisherman.7 deleted file mode 120000 index a6d0070..0000000 --- a/man/man7/fisherman.7 +++ /dev/null @@ -1 +0,0 @@ -/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7 \ No newline at end of file diff --git a/test/fisher.fish b/test/fisher.fish index 18f1498..1e9210b 100644 --- a/test/fisher.fish +++ b/test/fisher.fish @@ -37,7 +37,7 @@ test "$TESTNAME - Display usage help" end test "$TESTNAME - Display basic information help info about 'help'" - (fisher | tail -n2 | xargs) = "Use fisher help -g to list guides and other documentation. See fisher help to access a man page." + (fisher | tail -n2 | xargs) = "Use fisher help to access a man page." end test "$TESTNAME - Display basic information about available commands" diff --git a/test/fixtures/help/usage.txt b/test/fixtures/help/usage.txt index e19c87a..1fa97a9 100644 --- a/test/fixtures/help/usage.txt +++ b/test/fixtures/help/usage.txt @@ -28,8 +28,4 @@ Usage: fisher install [] [--force] [--quiet] [--help] -f --force Reinstall given plugin/s -q --quiet Enable quiet mode -h --help Show usage help -Usage: fisher help [] [--all] [--guides] [--help] - - -a --all List all the documentation - -g --guides List available guides - -h --help Show usage help +Usage: fisher help [] [--help] diff --git a/test/help.fish b/test/help.fish index 2ab62a5..70e5365 100644 --- a/test/help.fish +++ b/test/help.fish @@ -17,14 +17,6 @@ function -S teardown rm -rf $path end -test "$TESTNAME - Show both available guides and command with help --all" - ! -z (fisher help --all | grep -E 'Available Commands:$|Other Documentation:$' | xargs) -end - -test "$TESTNAME - Show available guides/tutorials with --guides" - ! -z (fisher help --guides | grep -E 'Other Documentation:$' | xargs) -end - test "$TESTNAME - Show usage help with --usage=command" (fisher help --usage=help) = (fisher help -h) end