Archives
/
fisher
mirror of https://github.com/jorgebucaran/fisher
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Close #149, #150.

Browse Source
pull/445/head
Jorge Bucaran 8 years ago
parent c076b703b4
commit bb8a8663fc
No known key found for this signature in database
GPG Key ID: E54BA3C0E646DB30
18 changed files with 1464 additions and 1029 deletions
Show Stats Download Patch File Download Diff File

8
CHANGELOG.md
Unescape Escape View File

@ -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.

5
Makefile
Unescape Escape View File

@ -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;\

485
README.md
Unescape Escape View File

@ -14,19 +14,493 @@
<br>
</h1>
**[Fisherman]** is a blazing fast, modern plugin manager for [fish].
**Fisherman** is a blazing fast, modern plugin manager for [fish].
```fish
curl -sL get.fisherman.sh | fish
```
[![play]][play-link]
&nbsp; ▸ &nbsp; **[Get Started]**<br>
&nbsp; ▸ &nbsp; **[Plugins]**<br>
<sub>If you don't have Fish, you need to install it too. Install instructions can be found <a href="https://github.com/fisherman/fisherman/wiki/Installing-Fish">here</a>.</sub>
## Setup
Download Fisherman using Git and setup your system automatically. See [other] install options.
```fish
curl -sL get.fisherman.sh | fish
```
[![play]][play-link]
## 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<br>
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<br>
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<br>
See FISHFILE above.
* $fisher_cache<br>
The cache directory. Plugins are downloaded to this location.
* $fisher_alias *command*=*alias*[,*alias2*] ...<br>
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/<you>/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 <commands>`.
Create a function `fisher_<command>`
```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 <name or URL> [...]\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

9
completions/fisher.fish
Unescape Escape View File

@ -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"

4
functions/__fisher_help_guides.fish
Unescape Escape View File

@ -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

32
functions/fisher.fish
Unescape Escape View File

@ -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 <command> [<arguments>] [--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"
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 "Use 'fisher help -g' to list guides and other documentation.\n"
printf "See 'fisher help <command or concept>' to access a man page.\n"
printf "\nUse fisher help <command> to access a man page.\n"
end
end

25
functions/fisher_help.fish
Unescape Escape View File

@ -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 [<keyword>] [--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 [<keyword>] [--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

1
man/man1/fisher-tutorial.1
Unescape Escape View File

@ -0,0 +1 @@
/Users/bucaran/c/fisherman/fisherman/man/man1/fisher.1

620
man/man1/fisher.1
Unescape Escape View File

@ -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 <command>
.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,12 +57,21 @@ Show version information\. Fisherman follows Semantic Versioning and uses Git an
Show usage help\.
.
.SH "EXAMPLES"
Update Fisherman\.
.
.IP "\(bu" 4
Install plugins\.
.IP "" 4
.
.nf
fisher update
.
.fi
.
.IP "" 0
.
.P
Install plugins\.
.
.IP "" 4
.
.nf
@ -73,133 +82,279 @@ fisher install fishtape shark get
.
.IP "" 0
.
.IP "\(bu" 4
Install a plugin as a symbolic link\.
.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 \./path/to/plugin
fisher install owner/repo
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Update Fisherman to the latest version\.
.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
fisher update shark get
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Search the Fisherman index\.
.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 search
fisher uninstall fishtape debug \-f
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
.P
Show all the documentation\.
.
.IP "" 4
.
.nf
fisher help \-\-all
.
.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 help \-\-all
fisher list
debug
* fishtape
> shellder
* spin
@ wipe
.
.fi
.
.IP "" 0
.
.SH "CONCEPTS"
.P
The legend consists of:
.
.SS "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
\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
The following illustrates an example Fisherman configuration path with a single plugin and prompt\.
Search the index\.
.
.IP "" 4
.
.nf
$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
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
.
.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\.
.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
To search plugins use fisher search \fIname\fR\. You can by a specific field using fisher search \-\-\fIfield\fR=\fImatch\fR\.
Enable all the plugins that are currently disabled\.
.
.IP "" 4
.
.nf
fisher search \-\-tag={*keywords*}
fisher list \-\-disabled | fisher install
.
.fi
.
.IP "" 0
.
.P
or
Uninstall all the plugins and remove them from the cache\.
.
.IP "" 4
.
.nf
fisher search \-\-name=*name*
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
See fisher help search for advanced options\.
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
To learn how to create plugins enter fisher help tutorial\.
The following illustrates an example Fisherman configuration path with a single plugin and prompt\.
.
.IP "" 4
.
.nf
$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
.
.fi
.
.SS "INDEX"
.IP "" 0
.
.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/<you>/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 <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
.
.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 <name or URL> [\.\.\.]\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\.
.

412
man/man1/fisher.md
Unescape Escape View File

@ -9,7 +9,7 @@ fisher *command* [*arguments*] [--version] [--help]<br>
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 <command>
```
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.
Update Fisherman.
```fish
fisher update
```
Install plugins.
```fish
fisher install fishtape shark get
```
* Install a plugin as a symbolic link.
Install a plugin from a local directory.
```fish
fisher install ./path/to/plugin
```
* Update Fisherman to the latest version.
Install a plugin from a URL.
```fish
fisher update
fisher install owner/repo
```
* Search the Fisherman index.
Install a plugin from a Gist URL.
```fish
fisher search
fisher install gist.github.com/owner/1f40e1c6e0551b2666b2
```
Update plugins.
```
fisher update shark get
```
* Show all the documentation.
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
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<br>
`>` The plugin is a prompt<br>
`@` The plugin is a symbolic link<br>
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
### FLAT TREE
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/<you>/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 <commands>`.
Create a function `fisher_<command>`
```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 <name or URL> [...]\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*.

1
man/man7/fisher-configuration.7
Unescape Escape View File

@ -1 +0,0 @@
fisher-config.7

537
man/man7/fisher-tutorial.7
Unescape Escape View File

@ -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 <plugin>
.
.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 <plugin>
.
.fi
.
.IP "" 0
.
.P
Uninstall a plugin\.
.
.IP "" 4
.
.nf
fisher uninstall <plugin>
.
.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/<you>/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 <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
.
.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 <name or URL> [\.\.\.]\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)

336
man/man7/fisher-tutorial.md
Unescape Escape View File

@ -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>
```
*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 <plugin>
```
Uninstall a plugin.
```
fisher uninstall <plugin>
```
## 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<br>
`>` Indicate the plugin is a prompt<br>
`@` Indicate the plugin is a symbolic link<br>
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/<you>/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 <commands>`.
Create a function `fisher_<command>`
```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 <name or URL> [...]\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)

1
man/man7/fisher.7
Unescape Escape View File

@ -1 +0,0 @@
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7

1
man/man7/fisherman.7
Unescape Escape View File

@ -1 +0,0 @@
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7

2
test/fisher.fish
Unescape Escape View File

@ -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 <command or concept> to access a man page."
(fisher | tail -n2 | xargs) = "Use fisher help <command> to access a man page."
end
test "$TESTNAME - Display basic information about available commands"

6
test/fixtures/help/usage.txt vendored
Unescape Escape View File

@ -28,8 +28,4 @@ Usage: fisher install [<plugins>] [--force] [--quiet] [--help]
-f --force Reinstall given plugin/s
-q --quiet Enable quiet mode
-h --help Show usage help
Usage: fisher help [<keyword>] [--all] [--guides] [--help]
-a --all List all the documentation
-g --guides List available guides
-h --help Show usage help
Usage: fisher help [<keyword>] [--help]

8
test/help.fish
Unescape Escape View File

@ -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

Write Preview
Loading…
Cancel
Save