mirror of
https://github.com/jorgebucaran/fisher
synced 2024-10-09 09:36:53 +02:00
parent
21a189b8f4
commit
57964e6842
18 changed files with 1515 additions and 1080 deletions
|
@ -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
5
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;\
|
||||
|
|
489
README.md
489
README.md
|
@ -14,12 +14,7 @@
|
|||
<br>
|
||||
</h1>
|
||||
|
||||
|
||||
**Fisherman** is a blazing fast, modern plugin manager for [fish].
|
||||
|
||||
|
||||
▸ **[Get Started]**<br>
|
||||
▸ **[Plugins]**<br>
|
||||
**[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]
|
||||
|
||||
<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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
|
|
@ -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"
|
||||
|
|
|
@ -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
|
|
@ -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"
|
||||
|
||||
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"
|
||||
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 <command> to access a man page.\n"
|
||||
end
|
||||
end
|
||||
|
|
|
@ -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
Symbolic link
1
man/man1/fisher-tutorial.1
Symbolic link
|
@ -0,0 +1 @@
|
|||
/Users/bucaran/c/fisherman/fisherman/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 <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,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/<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\.
|
||||
.
|
||||
|
|
|
@ -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.
|
||||
|
||||
```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<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
|
||||
|
||||
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 +0,0 @@
|
|||
fisher-config.7
|
|
@ -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)
|
|
@ -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 +0,0 @@
|
|||
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
|
|
@ -1 +0,0 @@
|
|||
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
|
|
@ -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
6
test/fixtures/help/usage.txt
vendored
|
@ -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]
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue