mirror of https://github.com/jorgebucaran/fisher
Fisherman 1.0 RC
* Deprecate fisher --list in favor of a new command fisher list. The behavior is roughly the same. See fisher help list for usage. tl;dr: Use list to query the local system / cache and search to query the index. * Teach fisher_plugin_walk about fish_postexec, fish_command_not_found and fish_preexec event emitters and erase them during uninstall if they were defined in a snippet. * Fisherman now recognizes the following aliases by default: i for install, u for update, l for list, s for search and h for help. * Large documentation rewrite. Better, simpler, more concise and more consistent. * Fisherman now detects if users have modified their fish prompt using fish_config and if so, uninstalls $fisher_prompt.pull/445/head
Jorge Bucaran
8 years ago
parent
0240f2884b
commit
ebec1eaa01
@ -1,72 +1,41 @@
|
||||
[![Slack Room][slack-badge]][slack-link]
|
||||
|
||||
# Contributing to Fisherman
|
||||
# Contributing
|
||||
|
||||
If you are looking for ways to help, peruse the [open issues][issues] or send us your PR if you are already working on something.
|
||||
If you are looking for ways to help, browse [open issues][issues] or send us your PR if you are already working on something.
|
||||
|
||||
## Guidelines
|
||||
|
||||
* Fork the repo and create your feature branch from master.
|
||||
|
||||
* If you make significant changes, please add tests too. Get familiar with [Fishtape][fishtape].
|
||||
* If you make significant changes, please add tests too. Get familiar with [Fishtape].
|
||||
|
||||
* If you've changed APIs, please update the documentation.
|
||||
|
||||
* Follow the [seven rules][rules] of a great git commit message.
|
||||
* Follow the [seven rules] of a great Git commit message.
|
||||
|
||||
## Plugins
|
||||
|
||||
The fastest way to create a plugin is using the `scaffold` plugin.
|
||||
1. Create a new plugin with `scaffold`.
|
||||
```fish
|
||||
fisher install scaffold
|
||||
fisher scaffold
|
||||
```
|
||||
|
||||
1. Install
|
||||
|
||||
```fish
|
||||
fisher install scaffold
|
||||
```
|
||||
|
||||
2. Create a new plugin using the default template.
|
||||
> See the `fisher help scaffold` for other usage instructions.
|
||||
|
||||
```fish
|
||||
fisher scaffold
|
||||
```
|
||||
|
||||
To browse the available content use `fisher search` or browse the [Fishery][fishery].
|
||||
|
||||
To submit a new plugin to the [index][index], use the `submit` plugin.
|
||||
|
||||
1. Install
|
||||
|
||||
```fish
|
||||
fisher install submit
|
||||
```
|
||||
|
||||
2. Submit
|
||||
|
||||
```fish
|
||||
fisher submit my_plugin
|
||||
```
|
||||
2. Submit a plugin to the [index] with `submit`.
|
||||
```fish
|
||||
fisher install submit
|
||||
fisher submit my_plugin
|
||||
```
|
||||
|
||||
## Translations
|
||||
|
||||
If you would like to translate a portion of the documentation, you can begin with the [Quickstart Guide][quick-start]. Use any of the existing translations as a reference to get started.
|
||||
|
||||
<!-- Badges -->
|
||||
If you would like to translate a portion of the documentation, you can begin with the [Quickstart Guide].
|
||||
|
||||
[slack-link]: https://fisherman-wharf.herokuapp.com/
|
||||
[slack-badge]: https://img.shields.io/badge/slack-join%20the%20chat-00B9FF.svg?style=flat-square
|
||||
|
||||
<!-- Links -->
|
||||
|
||||
[rules]: http://chris.beams.io/posts/git-commit/#seven-rules
|
||||
[issues]: https://github.com/fisherman/fisherman/issues?q=is%3Aopen+is%3Aissue
|
||||
[fishtape]: https://github.com/fisherman/fishtape
|
||||
|
||||
<!-- Plugins -->
|
||||
|
||||
[seven rules]: http://chris.beams.io/posts/git-commit/#seven-rules
|
||||
[open issues]: https://github.com/fisherman/fisherman/issues?q=is%3Aopen+is%3Aissue
|
||||
[Fishtape]: https://github.com/fisherman/fishtape
|
||||
[index]: https://github.com/fisherman/fisher-index
|
||||
[fishery]: https://github.com/fishery
|
||||
|
||||
<!-- Translations -->
|
||||
|
||||
[quick-start]: https://github.com/fisherman/fisherman/wiki/Quickstart-Guide
|
||||
[Quickstart Guide]: https://github.com/fisherman/fisherman/wiki/Quickstart-Guide
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
function __fisher_cache_list
|
||||
find -L $fisher_cache/* -maxdepth 0 -type d ^ /dev/null | sed 's|.*/||'
|
||||
find -L $fisher_cache/* -maxdepth 0 -type d ^ /dev/null | sed 's|.*/||'
|
||||
end
|
||||
|
||||
@ -1,64 +0,0 @@
|
||||
function __fisher_list -a source
|
||||
switch "$source"
|
||||
case bare
|
||||
__fisher_cache_list
|
||||
|
||||
case url
|
||||
for i in (__fisher_cache_list)
|
||||
__fisher_url_from_path $fisher_cache/$i
|
||||
end
|
||||
|
||||
case "" all cache
|
||||
set -l enabled (__fisher_list $fisher_file)
|
||||
set -l cache (__fisher_cache_list)
|
||||
|
||||
if test -z "$cache"
|
||||
return 1
|
||||
end
|
||||
|
||||
set -l legend " "
|
||||
|
||||
if test -z "$enabled"
|
||||
set legend ""
|
||||
end
|
||||
|
||||
for i in $cache
|
||||
if contains -- $i $enabled
|
||||
if test $i = "$fisher_prompt"
|
||||
printf "%s%s\n" ">" $i
|
||||
|
||||
else if test -L $fisher_cache/$i
|
||||
printf "%s%s\n" "@" $i
|
||||
|
||||
else
|
||||
printf "%s%s\n" "*" $i
|
||||
end
|
||||
else
|
||||
printf "%s%s\n" "$legend" $i
|
||||
end
|
||||
end
|
||||
|
||||
case enabled installed
|
||||
__fisher_list $fisher_file
|
||||
|
||||
case disabled
|
||||
set -l enabled (__fisher_list $fisher_file)
|
||||
|
||||
for name in (__fisher_cache_list)
|
||||
if not contains -- $name $enabled
|
||||
printf "%s\n" $name
|
||||
end
|
||||
end
|
||||
|
||||
case theme prompt
|
||||
printf "%s\n" $fisher_prompt
|
||||
|
||||
case -
|
||||
__fisher_file | __fisher_name
|
||||
|
||||
case \*
|
||||
if test -s "$source"
|
||||
__fisher_list - < $source
|
||||
end
|
||||
end
|
||||
end
|
||||
@ -1,7 +1,9 @@
|
||||
function __fisher_plugin_unlink -a name file
|
||||
debug "Unlink '%s'" $file
|
||||
function __fisher_plugin_unlink -a file name
|
||||
debug "Unlink %s" $file
|
||||
command rm -f $file
|
||||
|
||||
debug "Erase function '%s'" $name
|
||||
functions -e $name
|
||||
|
||||
if test ! -z "$name"
|
||||
debug "Erase %s" $name
|
||||
functions -e $name
|
||||
end
|
||||
end
|
||||
|
||||
@ -0,0 +1,28 @@
|
||||
function fish_config -d "Launch fish's web based configuration" -a tab
|
||||
set -l config ~/.config
|
||||
|
||||
if set -q XDG_CONFIG_HOME
|
||||
set config $XDG_CONFIG_HOME
|
||||
end
|
||||
|
||||
set -l file $config/fish/functions/fish_prompt.fish
|
||||
set -l sum_before (cksum $file ^ /dev/null | awk '{ print $1 + $2 }')
|
||||
|
||||
debug "fish_config start"
|
||||
|
||||
eval $__fish_datadir/tools/web_config/webconfig.py $tab
|
||||
|
||||
debug "fish_config end"
|
||||
|
||||
if test ! -z "$fisher_prompt"
|
||||
set -l sum_after (cksum $file ^ /dev/null | awk '{ print $1 + $2 }')
|
||||
|
||||
debug "fish_prompt check sum before: %s" $sum_before
|
||||
debug "fish_prompt check sum after: %s" $sum_after
|
||||
|
||||
if test "$sum_before" != "$sum_after"
|
||||
debug "Uninstall %s" "$fisher_prompt"
|
||||
fisher_uninstall "$fisher_prompt" -q
|
||||
end
|
||||
end
|
||||
end
|
||||
@ -0,0 +1,69 @@
|
||||
function fisher_list -a key -d "List installed plugins"
|
||||
switch "$key"
|
||||
case -b --bare
|
||||
__fisher_cache_list
|
||||
|
||||
case ""
|
||||
set -l enabled (fisher_list $fisher_file)
|
||||
set -l cache (__fisher_cache_list)
|
||||
|
||||
if test -z "$cache"
|
||||
return 1
|
||||
end
|
||||
|
||||
set -l indent " "
|
||||
|
||||
if test -z "$enabled"
|
||||
set indent ""
|
||||
end
|
||||
|
||||
for i in $cache
|
||||
if contains -- $i $enabled
|
||||
if test $i = "$fisher_prompt"
|
||||
printf "%s%s\n" ">$indent" $i
|
||||
|
||||
else if test -L $fisher_cache/$i
|
||||
|
||||
printf "%s%s\n" "@$indent" $i
|
||||
|
||||
else
|
||||
printf "%s%s\n" "*$indent" $i
|
||||
end
|
||||
else
|
||||
printf "%s%s\n" "$indent$indent" $i
|
||||
end
|
||||
end
|
||||
|
||||
case -l --link
|
||||
find $fisher_cache/* -maxdepth 0 -type l ^ /dev/null | sed 's|.*/||'
|
||||
|
||||
case --enabled
|
||||
fisher_list $fisher_file
|
||||
|
||||
case --disabled
|
||||
set -l enabled (fisher_list $fisher_file)
|
||||
|
||||
for name in (__fisher_cache_list)
|
||||
if not contains -- $name $enabled
|
||||
printf "%s\n" $name
|
||||
end
|
||||
end
|
||||
|
||||
case -
|
||||
__fisher_file | __fisher_name
|
||||
|
||||
case -h
|
||||
printf "Usage: fisher list [<file>] [--enabled] [--disabled] [--bare] [--link] \n\n"
|
||||
printf " -b --bare List plugin without decorators\n"
|
||||
printf " -l --link List plugins that are symbolic links\n"
|
||||
printf " --enabled List plugins that are enabled\n"
|
||||
printf " --disabled List plugins that are disabled\n"
|
||||
printf " -h --help Show usage help\n"
|
||||
return
|
||||
|
||||
case \*
|
||||
if test -s "$key"
|
||||
fisher_list - < $key
|
||||
end
|
||||
end
|
||||
end
|
||||
@ -0,0 +1,78 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-LIST" "1" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-list\fR \- List installed plugins
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
fisher list [\fIfile\fR]
|
||||
.
|
||||
.br
|
||||
fisher list [\-\-bare] [\-\-link] [\-\-enabled] [\-\-disabled] [\-\-help]
|
||||
.
|
||||
.br
|
||||
.
|
||||
.SH "USAGE"
|
||||
fisher list [\fIfile\fR]
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
The list command displays all the plugins you have installed\.
|
||||
.
|
||||
.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
|
||||
.
|
||||
.SH "OPTIONS"
|
||||
.
|
||||
.TP
|
||||
\-b, \-\-bare
|
||||
List plugin without decorators
|
||||
.
|
||||
.TP
|
||||
\-l, \-\-link
|
||||
List plugins that are symbolic links
|
||||
.
|
||||
.TP
|
||||
\-\-enabled
|
||||
List plugins that are enabled
|
||||
.
|
||||
.TP
|
||||
\-\-disabled
|
||||
List plugins that are disabled
|
||||
.
|
||||
.TP
|
||||
\-h, \-\-help
|
||||
Show usage help
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
fisher help search
|
||||
.
|
||||
.br
|
||||
|
||||
@ -0,0 +1,51 @@
|
||||
fisher-list(1) -- List installed plugins
|
||||
========================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
fisher list [*file*]<br>
|
||||
fisher list [--bare] [--link] [--enabled] [--disabled] [--help]<br>
|
||||
|
||||
## USAGE
|
||||
|
||||
fisher list [*file*]
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
The list command displays all the plugins you have installed.
|
||||
|
||||
```
|
||||
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>
|
||||
|
||||
## OPTIONS
|
||||
|
||||
* -b, --bare:
|
||||
List plugin without decorators
|
||||
|
||||
* -l, --link:
|
||||
List plugins that are symbolic links
|
||||
|
||||
* --enabled:
|
||||
List plugins that are enabled
|
||||
|
||||
* --disabled:
|
||||
List plugins that are disabled
|
||||
|
||||
* -h, --help:
|
||||
Show usage help
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
fisher help search<br>
|
||||
@ -1,48 +1,47 @@
|
||||
fisher-update(1) -- Update Fisherman and Plugins
|
||||
================================================
|
||||
fisher-update(1) -- Update plugins
|
||||
==================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
fisher `update` [*plugins* ...] [`--quiet`] [`--help`] <br>
|
||||
fisher update [*plugins* ...] [--quiet] [--help] <br>
|
||||
|
||||
## USAGE
|
||||
|
||||
fisher `update` *url* ...<br>
|
||||
fisher `update` *name* ...<br>
|
||||
fisher `update` *path* ...<br>
|
||||
fisher `update` *owner/repo* ...<br>
|
||||
fisher update *url* ...<br>
|
||||
fisher update *name* ...<br>
|
||||
fisher update *path* ...<br>
|
||||
fisher update *owner/repo* ...<br>
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
Update one or more plugins, by name, URL or a local path. If no arguments are given, update Fisherman to the latest release. If you try to update a plugin that is currently disabled, but present in the cache, it will be updated and then enabled. Use a dash `-` to read from the standard input.
|
||||
Update one or more plugins, by name, URL or path. If no arguments are given, update Fisherman to the latest release. If you try to update a plugin that is currently disabled, but exists in the cache, it will be updated and then enabled. Use a dash `-` to read from the standard input.
|
||||
|
||||
One exception to the process described above is updating a prompt which is not the current one. In this case the repository is updated, but it will not be activated as that is probably not what the user wants.
|
||||
|
||||
If a plugin is missing dependencies, they will be installed. If any dependencies are already installed they will not be updated. See `Plugins` in `fisher help fishfile`.
|
||||
If a plugin is missing dependencies, they will be installed. If any dependencies are already installed they will not be updated.
|
||||
|
||||
## OPTIONS
|
||||
|
||||
* `-q --quiet`:
|
||||
* -q, --quiet:
|
||||
Enable quiet mode.
|
||||
|
||||
* `-h --help`:
|
||||
* -h, --help:
|
||||
Show usage help.
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
* Update Fisherman
|
||||
* Update Fisherman.
|
||||
|
||||
```fish
|
||||
fisher update
|
||||
```
|
||||
|
||||
* Update all the plugins in the cache *concurrently*.
|
||||
* Update all the plugins in the cache.
|
||||
|
||||
```fish
|
||||
fisher --list | cut -c 2- | xargs -n1 -P0 fish -c 'fisher update'
|
||||
fisher list | fisher update -
|
||||
```
|
||||
|
||||
## SEE ALSO
|
||||
* Update all the plugins in the cache concurrently.
|
||||
|
||||
`fisher`(1)<br>
|
||||
`fisher help plugins`<br>
|
||||
```fish
|
||||
fisher list --bare | xargs -n1 -P0 fish -c "fisher update -"
|
||||
```
|
||||
|
||||
@ -1,59 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-FISHFILE" "5" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-fishfile\fR \- Fishfile Format
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using \fBfisher \-\-list\fR\.
|
||||
.
|
||||
.P
|
||||
Your fishfile is stored in \fB$fisher_config/fishfile\fR by default, but you can customize this location overriding the \fB$fisher_file\fR variable in your fish configuration file\.
|
||||
.
|
||||
.SH "USAGE"
|
||||
Fishfiles list one or more plugins by their name, URL or path to a local project\.
|
||||
.
|
||||
.P
|
||||
Here is an example:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
# Ahoy!
|
||||
|
||||
gitio
|
||||
fishtape
|
||||
shark
|
||||
get
|
||||
some_user/her_plugin
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
A fishfile may contain any amount of whitespace and comments\.
|
||||
.
|
||||
.P
|
||||
If you need to parse a fishfile to list its plugins, for example, to pipe the input into \fBfisher install\fR or \fBfisher update\fR, you can use \fBfisher \-\-list=path/to/fishfile\fR\. Notice that Oh My Fish! bundle file syntax is also supported\.
|
||||
.
|
||||
.SH "PLUGINS"
|
||||
Plugins may list any number of dependencies to other plugins in a fishfile at the root of the project\.
|
||||
.
|
||||
.P
|
||||
When a plugin is installed, its dependencies are downloaded for the first time\. If a dependency is already installed, it is not updated in order to prevent breaking other plugins using a different version\. Currently, uninstalling a plugin does not remove any its dependencies either\.
|
||||
.
|
||||
.P
|
||||
To understand this behavior, it helps to recall the shell\'s single scope for functions\. The lack of private functions means that, it is \fInot\fR possible to single\-lock a specific dependency version\. See also \fBFlat Tree\fR in \fBfisher help tour\fR\.
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
\fBfisher\fR(1)
|
||||
.
|
||||
.br
|
||||
\fBfisher help config\fR
|
||||
.
|
||||
.br
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
fisher-fishfile(5) -- Fishfile Format
|
||||
=====================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using `fisher --list`.
|
||||
|
||||
Your fishfile is stored in `$fisher_config/fishfile` by default, but you can customize this location overriding the `$fisher_file` variable in your fish configuration file.
|
||||
|
||||
## USAGE
|
||||
|
||||
Fishfiles list one or more plugins by their name, URL or path to a local project.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```
|
||||
# Ahoy!
|
||||
|
||||
gitio
|
||||
fishtape
|
||||
shark
|
||||
get
|
||||
some_user/her_plugin
|
||||
```
|
||||
|
||||
A fishfile may contain any amount of whitespace and comments.
|
||||
|
||||
If you need to parse a fishfile to list its plugins, for example, to pipe the input into `fisher install` or `fisher update`, you can use `fisher --list=path/to/fishfile`. Notice that Oh My Fish! bundle file syntax is also supported.
|
||||
|
||||
## PLUGINS
|
||||
|
||||
Plugins may list any number of dependencies to other plugins in a fishfile at the root of the project.
|
||||
|
||||
When a plugin is installed, its dependencies are downloaded for the first time. If a dependency is already installed, it is not updated in order to prevent breaking other plugins using a different version. Currently, uninstalling a plugin does not remove any its dependencies either.
|
||||
|
||||
To understand this behavior, it helps to recall the shell's single scope for functions. The lack of private functions means that, it is *not* possible to single-lock a specific dependency version. See also `Flat Tree` in `fisher help tour`.
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`fisher`(1)<br>
|
||||
`fisher help config`<br>
|
||||
@ -1 +0,0 @@
|
||||
fisher-fishfile.5
|
||||
@ -1,106 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-COMMANDS" "7" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-commands\fR \- Creating Fisherman Commands
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
This document describes how to add new commands to Fisherman\. A Fisherman command is a function that you can invoke using the \fBfisher\fR CLI, for example:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher my_command [*options*]
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
To add a command, create a function \fBfisher_<my_command>\fR:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
function fisher_hello \-d "Hello, how are you?"
|
||||
echo hello
|
||||
end
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Test it works: \fBfisher hello\fR\.
|
||||
.
|
||||
.P
|
||||
To make this function available to future fish sessions, add it to \fB$XDG_CONFIG_HOME/fish/functions\fR:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
funcsave fisher_hello
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
You can also create a local plugin and install it with Fisherman:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
mkdir fisher_hello
|
||||
cd fisher_hello
|
||||
functions fisher_hello > fisher_hello\.fish
|
||||
fisher install \.
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
The method described above will create a symbolic link to the \fBfisher_hello\fR directory and \fBfisher_hello\.fish\fR inside \fB$fisher_config/functions\fR\.
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
The following example implements a command to retrieve plugin information and format the output into columns\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
function fisher_info \-d "Display information about plugins"
|
||||
switch "$argv"
|
||||
case \-h \-\-help
|
||||
printf "Usage: fisher info name | 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
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
\fBfisher\fR(1), \fBfuncsave\fR(1)
|
||||
.
|
||||
.br
|
||||
\fBfisher help tour\fR
|
||||
.
|
||||
.br
|
||||
\fBfisher help plugins\fR
|
||||
.
|
||||
.br
|
||||
|
||||
@ -1,64 +0,0 @@
|
||||
fisher-commands(7) -- Creating Fisherman Commands
|
||||
=================================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
This document describes how to add new commands to Fisherman. A Fisherman command is a function that you can invoke using the `fisher` CLI, for example:
|
||||
|
||||
```fish
|
||||
fisher my_command [*options*]
|
||||
```
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
To add a command, create a function `fisher_<my_command>`:
|
||||
|
||||
```fish
|
||||
function fisher_hello -d "Hello, how are you?"
|
||||
echo hello
|
||||
end
|
||||
```
|
||||
|
||||
Test it works: `fisher hello`.
|
||||
|
||||
To make this function available to future fish sessions, add it to `$XDG_CONFIG_HOME/fish/functions`:
|
||||
|
||||
```fish
|
||||
funcsave fisher_hello
|
||||
```
|
||||
|
||||
You can also create a local plugin and install it with Fisherman:
|
||||
|
||||
```fish
|
||||
mkdir fisher_hello
|
||||
cd fisher_hello
|
||||
functions fisher_hello > fisher_hello.fish
|
||||
fisher install .
|
||||
```
|
||||
|
||||
The method described above will create a symbolic link to the `fisher_hello` directory and `fisher_hello.fish` inside `$fisher_config/functions`.
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
The following example implements a command to retrieve plugin information and format the output into columns.
|
||||
|
||||
```fish
|
||||
function fisher_info -d "Display information about plugins"
|
||||
switch "$argv"
|
||||
case -h --help
|
||||
printf "Usage: fisher info name | 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
|
||||
```
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`fisher`(1), `funcsave`(1)<br>
|
||||
`fisher help tour`<br>
|
||||
`fisher help plugins`<br>
|
||||
@ -1,62 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-CONFIG" "7" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-config\fR \- Fisherman Configuration
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
This document describes how to use Fisherman configuration variables\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
Your fish user configuration, usually located in \fB$XDG_CONFIG_HOME/fish/config\.fish\fR is updated after installing Fisherman to add the global variables \fB$fisher_home\fR and \fB$fisher_config\fR\.
|
||||
.
|
||||
.P
|
||||
Using the following variables, you can customize the locations of the cache, index URL, fishfile, create command aliases, etc\.
|
||||
.
|
||||
.SH "VARIABLES"
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_home\fR
|
||||
The home directory\. If you installed Fisherman using the recommended method \fBcurl \-sL install\.fisherman\.sh | fish\fR, the location will be \fB$XDG_DATA_HOME/fisherman\fR\. If you clone Fisherman and run \fBmake\fR yourself, \fB$fisher_home\fR will the current working directory\.
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_config\fR
|
||||
The user configuration directory\. This is default location of your user \fIfishfile\fR, Fisherman \fIkey_bindings\.fish\fR file and the \fIcache\fR, \fIfunctions\fR, \fIcompletions\fR and \fIconf\.d\fR directories\. \fB$XDG_CONFIG_HOME/fisherman\fR by default\.
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_file\fR
|
||||
This file keeps a list of what plugins you have installed and are currently enabled\. \fB$fisher_config/fishfile\fR by default\. See \fBfisher help fishfile\fR for details\.
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_cache\fR
|
||||
The cache directory\. Plugins are downloaded first here and installed to \fB$fisher_config/functions\fR afterwards\. The cache is \fB$fisher_config/cache\fR by default\.
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_index\fR
|
||||
The URL to the index database\. To use a different index set this to a file or URL\. Redirect URLs are currently not supported due to security and performance concerns\. The underlying request and fetch mechanism is based in \fBcurl\fR(1)\.
|
||||
.
|
||||
.TP
|
||||
\fB$fisher_alias command=alias[,\.\.\.] [command2=alias[,\.\.\.]]\fR
|
||||
Use this variable to define custom aliases for fisher commands\. See \fBExamples\fR below\.
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
Create aliases for fisher \fBinstall\fR to \fIi\fR, \fIin\fR and \fIinst\fR; and for fisher \fBupdate\fR to \fIup\fR\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
set fisher_alias install=i,in,inst update=up
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
\fBfisher help tour\fR
|
||||
@ -1,44 +0,0 @@
|
||||
fisher-config(7) -- Fisherman Configuration
|
||||
===========================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
This document describes how to use Fisherman configuration variables.
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
Your fish user configuration, usually located in `$XDG_CONFIG_HOME/fish/config.fish` is updated after installing Fisherman to add the global variables `$fisher_home` and `$fisher_config`.
|
||||
|
||||
Using the following variables, you can customize the locations of the cache, index URL, fishfile, create command aliases, etc.
|
||||
|
||||
## VARIABLES
|
||||
|
||||
* `$fisher_home`:
|
||||
The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location will be `$XDG_DATA_HOME/fisherman`. If you clone Fisherman and run `make` yourself, `$fisher_home` will the current working directory.
|
||||
|
||||
* `$fisher_config`:
|
||||
The user configuration directory. This is default location of your user *fishfile*, Fisherman *key_bindings.fish* file and the *cache*, *functions*, *completions* and *conf.d* directories. `$XDG_CONFIG_HOME/fisherman` by default.
|
||||
|
||||
* `$fisher_file`:
|
||||
This file keeps a list of what plugins you have installed and are currently enabled. `$fisher_config/fishfile` by default. See `fisher help fishfile` for details.
|
||||
|
||||
* `$fisher_cache`:
|
||||
The cache directory. Plugins are downloaded first here and installed to `$fisher_config/functions` afterwards. The cache is `$fisher_config/cache` by default.
|
||||
|
||||
* `$fisher_index`:
|
||||
The URL to the index database. To use a different index set this to a file or URL. Redirect URLs are currently not supported due to security and performance concerns. The underlying request and fetch mechanism is based in `curl`(1).
|
||||
|
||||
* `$fisher_alias command=alias[,...] [command2=alias[,...]]`:
|
||||
Use this variable to define custom aliases for fisher commands. See `Examples` below.
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
* Create aliases for fisher `install` to *i*, *in* and *inst*; and for fisher `update` to *up*.
|
||||
|
||||
```
|
||||
set fisher_alias install=i,in,inst update=up
|
||||
```
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`fisher help tour`
|
||||
@ -1,180 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-FAQ" "7" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-faq\fR \- Frequently Asked Questions
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
This document attempts to answer some of Fisherman most frequently asked questions\. Feel free to create a new issue in the Fisherman issue tracker if your question is not answered here\.
|
||||
.
|
||||
.SS "What is Fisherman?"
|
||||
Fisherman is a fish plugin manager that lets you share and reuse code, prompts and configurations easily\.
|
||||
.
|
||||
.SS "What do I need to know to use Fisherman?"
|
||||
Nothing, continue to use fish as usual\. Ready to learn more? Type \fBfisher help\fR or \fBfisher help tour\fR\.
|
||||
.
|
||||
.SS "How do I access the documentation?"
|
||||
Fisherman documentation is based in UNIX \fBman\fR(1) pages\. For basic usage and command enter \fBfisher help\fR\. For help about a specific \fIcommand\fR, enter \fBfisher help <command>\fR\. The following guides are also available:
|
||||
.
|
||||
.P
|
||||
fisher help \fBfaq\fR: Fisherman FAQ
|
||||
.
|
||||
.br
|
||||
fisher help \fBtour\fR: Fisherman Tour
|
||||
.
|
||||
.br
|
||||
fisher help \fBconfig\fR: Fisherman Configuration
|
||||
.
|
||||
.br
|
||||
fisher help \fBplugins\fR: Creating Fisherman Plugins
|
||||
.
|
||||
.br
|
||||
fisher help \fBcommands\fR: Creating Fisherman Commands
|
||||
.
|
||||
.br
|
||||
fisher help \fBfishfile\fR: Fishfile Format
|
||||
.
|
||||
.br
|
||||
.
|
||||
.SS "What are Fisherman plugins?"
|
||||
Plugins are written in fish and extend the shell core functionality, run initialization code, add completions or documentations to other commands, etc\. See \fBfisher help plugins\fR\.
|
||||
.
|
||||
.P
|
||||
Plugins may list any number of dependencies to other plugins using a \fIfishfile\fR\.
|
||||
.
|
||||
.SS "What is a Fishfile?"
|
||||
A plain text file consists of a lists of installed plugins or dependencies to other plugins\.
|
||||
.
|
||||
.P
|
||||
Fishfiles let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure\. See also \fBfisher help fishfile\fR\.
|
||||
.
|
||||
.SS "What kind of Fisherman plugins are there?"
|
||||
There is no technical distinction between plugins, themes, commands, etc\., but there is a \fIconceptual\fR difference\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBStandalone Utilities\fR: Plugins that define one or more functions, meant to be used at the command line\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBPrompts / Themes\fR: Plugins that modify the appearance of the fish prompt by defining a \fBfish_prompt\fR and / or \fBfish_right_prompt\fR functions\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBExtension Commands\fR: Plugins that extend Fisherman default commands\. An extension plugin must define one or more functions like \fBfisher_<my_command>\fR\. For specific information about commands, see \fBfisher help commands\fR and then return to this guide\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBConfiguration Plugins\fR: Plugins that include one or more \fBmy_plugin\.config\.fish\fR files\. Files that follow this convention are evaluated at the start of the session\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
See \fBfisher help plugins\fR and \fBfisher help commands\fR\.
|
||||
.
|
||||
.SS "Does Fisherman support Oh My Fish plugins and themes?"
|
||||
Yes\. To install either a plugin or theme use their URL:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install omf/plugin\-{rbenv,tab} omf/theme\-scorphish
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
You can use the same mechanism to install any valid plugin from any given URL\. See also \fBCompatibility\fR in \fBfisher help tour\fR\.
|
||||
.
|
||||
.SS "What does Fisherman do exactly every time I create a new shell session?"
|
||||
Essentially, add Fisherman functions and completions to the \fB$fish_{function,complete}_path\fR and evaluate files that follow the convention \fB*\.config\.fish\fR\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
set fish_function_path {$fisher_config,$fisher_home}/functions $fish_function_path
|
||||
set fish_complete_path {$fisher_config,$fisher_home}/completions $fish_complete_path
|
||||
|
||||
for file in $fisher_config/conf\.d/*\.config\.fish
|
||||
source $file
|
||||
end
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
See \fB$fisher_home/config\.fish\fR for the full code\.
|
||||
.
|
||||
.SS "How is Fisherman faster than Oh My Fish and other systems?"
|
||||
Fisherman ameliorates the slow shell start problem using a flat dependency tree instead of loading a directory hierarchy per plugin\. This also means that Fisherman performance does not decline depending on the number of plugins installed\. See also \fBFlat Tree\fR in \fBfisher help tour\fR\.
|
||||
.
|
||||
.SS "How can I upgrade from an existing Oh My Fish! installation?"
|
||||
Remove the \fB$OMF_PATH\fR and \fB$OMF_CONFIG\fR variables from your \fBconfig\.fish\fR\.
|
||||
.
|
||||
.P
|
||||
Backup dotfiles and other sensitive data\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
rm \-rf {$OMF_PATH,$OMF_CONFIG}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Install Fisherman\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
curl \-sL install\.fisherman\.sh | fish
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SS "How do I use fish as my default shell?"
|
||||
Add Fish to \fB/etc/shells\fR:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
echo "/usr/local/bin/fish" | sudo tee \-a /etc/shells
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Make Fish your default shell:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
chsh \-s /usr/local/bin/fish
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
To switch back to another shell\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
chsh \-s /bin/another/shell
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
|
||||
@ -1,116 +0,0 @@
|
||||
fisher-faq(7) -- Frequently Asked Questions
|
||||
===========================================
|
||||
|
||||
## SYNOPSIS
|
||||
|
||||
This document attempts to answer some of Fisherman most frequently asked questions. Feel free to create a new issue in the Fisherman issue tracker if your question is not answered here.
|
||||
|
||||
### What is Fisherman?
|
||||
|
||||
Fisherman is a fish plugin manager that lets you share and reuse code, prompts and configurations easily.
|
||||
|
||||
### What do I need to know to use Fisherman?
|
||||
|
||||
Nothing, continue to use fish as usual. Ready to learn more? Type `fisher help` or `fisher help tour`.
|
||||
|
||||
### How do I access the documentation?
|
||||
|
||||
Fisherman documentation is based in UNIX `man`(1) pages. For basic usage and command enter `fisher help`. For help about a specific *command*, enter `fisher help <command>`. The following guides are also available:
|
||||
|
||||
fisher help `faq`: Fisherman FAQ<br>
|
||||
fisher help `tour`: Fisherman Tour<br>
|
||||
fisher help `config`: Fisherman Configuration<br>
|
||||
fisher help `plugins`: Creating Fisherman Plugins<br>
|
||||
fisher help `commands`: Creating Fisherman Commands<br>
|
||||
fisher help `fishfile`: Fishfile Format<br>
|
||||
|
||||
### What are Fisherman plugins?
|
||||
|
||||
Plugins are written in fish and extend the shell core functionality, run initialization code, add completions or documentations to other commands, etc. See `fisher help plugins`.
|
||||
|
||||
Plugins may list any number of dependencies to other plugins using a *fishfile*.
|
||||
|
||||
### What is a Fishfile?
|
||||
|
||||
A plain text file consists of a lists of installed plugins or dependencies to other plugins.
|
||||
|
||||
Fishfiles let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure. See also `fisher help fishfile`.
|
||||
|
||||
### What kind of Fisherman plugins are there?
|
||||
|
||||
There is no technical distinction between plugins, themes, commands, etc., but there is a *conceptual* difference.
|
||||
|
||||
* `Standalone Utilities`: Plugins that define one or more functions, meant to be used at the command line.
|
||||
|
||||
* `Prompts / Themes`: Plugins that modify the appearance of the fish prompt by defining a `fish_prompt` and / or `fish_right_prompt` functions.
|
||||
|
||||
* `Extension Commands`: Plugins that extend Fisherman default commands. An extension plugin must define one or more functions like `fisher_<my_command>`. For specific information about commands, see `fisher help commands` and then return to this guide.
|
||||
|
||||
* `Configuration Plugins`: Plugins that include one or more `my_plugin.config.fish` files. Files that follow this convention are evaluated at the start of the session.
|
||||
|
||||
See `fisher help plugins` and `fisher help commands`.
|
||||
|
||||
### Does Fisherman support Oh My Fish plugins and themes?
|
||||
|
||||
Yes. To install either a plugin or theme use their URL:
|
||||
|
||||
```
|
||||
fisher install omf/plugin-{rbenv,tab} omf/theme-scorphish
|
||||
```
|
||||
|
||||
You can use the same mechanism to install any valid plugin from any given URL. See also `Compatibility` in `fisher help tour`.
|
||||
|
||||
### What does Fisherman do exactly every time I create a new shell session?
|
||||
|
||||
Essentially, add Fisherman functions and completions to the `$fish_{function,complete}_path` and evaluate files that follow the convention `*.config.fish`.
|
||||
|
||||
```fish
|
||||
set fish_function_path {$fisher_config,$fisher_home}/functions $fish_function_path
|
||||
set fish_complete_path {$fisher_config,$fisher_home}/completions $fish_complete_path
|
||||
|
||||
for file in $fisher_config/conf.d/*.config.fish
|
||||
source $file
|
||||
end
|
||||
```
|
||||
|
||||
See `$fisher_home/config.fish` for the full code.
|
||||
|
||||
### How is Fisherman faster than Oh My Fish and other systems?
|
||||
|
||||
Fisherman ameliorates the slow shell start problem using a flat dependency tree instead of loading a directory hierarchy per plugin. This also means that Fisherman performance does not decline depending on the number of plugins installed. See also `Flat Tree` in `fisher help tour`.
|
||||
|
||||
### How can I upgrade from an existing Oh My Fish! installation?
|
||||
|
||||
Remove the `$OMF_PATH` and `$OMF_CONFIG` variables from your `config.fish`.
|
||||
|
||||
Backup dotfiles and other sensitive data.
|
||||
|
||||
```fish
|
||||
rm -rf {$OMF_PATH,$OMF_CONFIG}
|
||||
```
|
||||
|
||||
Install Fisherman.
|
||||
|
||||
```
|
||||
curl -sL install.fisherman.sh | fish
|
||||
```
|
||||
|
||||
### How do I use fish as my default shell?
|
||||
|
||||
Add Fish to `/etc/shells`:
|
||||
|
||||
```sh
|
||||
echo "/usr/local/bin/fish" | sudo tee -a /etc/shells
|
||||
```
|
||||
|
||||
Make Fish your default shell:
|
||||
|
||||
```sh
|
||||
chsh -s /usr/local/bin/fish
|
||||
```
|
||||
|
||||
To switch back to another shell.
|
||||
|
||||
```sh
|
||||
chsh -s /bin/another/shell
|
||||
```
|
||||
@ -1 +0,0 @@
|
||||
fisher-tour.7
|
||||
@ -1,218 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-PLUGINS" "7" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-plugins\fR \- Creating Fisherman Plugins
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
This document describes how to create Fisherman plugins\. This includes stand\-alone utilities, prompts, extension commands and configuration plugins\.
|
||||
.
|
||||
.P
|
||||
There is no technical distinction between any of the terms aforementioned, but there is a \fIconceptual\fR difference\.
|
||||
.
|
||||
.SH "DEFINITIONS"
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBStandalone Utilities\fR: Plugins that define one or more functions\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBPrompts / Themes\fR: Plugins that modify the appearance of the fish prompt by defining a \fBfish_prompt\fR / \fBfish_right_prompt\fR function/s\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBExtension Commands\fR: Plugins that extend Fisherman default commands\. An extension plugin must define one or more functions like \fBfisher_<my_command>\fR\. For specific information about commands, see \fBfisher help commands\fR\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBConfiguration Plugins\fR: Plugins that include one or more \fBmy_plugin\.config\.fish\fR files\. Files that follow this convention are evaluated at the start of the session\. If a file does not follow the \fB<my_plugin>\.config\.fish\fR convention, it must be added to \fBconf\.d/*\.fish\fR and the \fB<my_plugin>\fR name will be prepended to the file during the installation process\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
An example plugin that follows several of the conventions proposed above\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
my_plugin
|
||||
|\-\- fisher_my_plugin\.fish
|
||||
|\-\- my_plugin\.fish
|
||||
|\-\- fish_prompt\.fish
|
||||
|\-\- fish_right_prompt\.fish
|
||||
|\-\- my_plugin\.config\.fish
|
||||
|\-\- functions
|
||||
| `\-\- my_plugin_helper\.fish
|
||||
|\-\- conf\.d
|
||||
| `\-\- *\.fish
|
||||
|\-\- completions
|
||||
| `\-\- my_plugin\.fish
|
||||
`\-\- man
|
||||
`\-\- man1
|
||||
`\-\- my_plugin\.1
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "DEPENDENCIES"
|
||||
A plugin may list any number of dependencies to other plugins using a \fIfishfile\fR, see \fBfisher help fishfile\fR\.
|
||||
.
|
||||
.P
|
||||
For example, if \fB<my_plugin>\fR depends on \fB<your_plugin>\fR, add this dependency into a fishfile at the root of the project:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
cat > my_plugin/fishfile
|
||||
your_plugin
|
||||
CTRL^D
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Plugins may also define completions using \fBcomplete\fR(1) and provide documentation in the form of \fBman\fR(1) pages\.
|
||||
.
|
||||
.SH "EXAMPLE"
|
||||
This section walks you through creating \fIwtc\fR, a stand\-alone plugin based in \fIgithub\.com/ngerakines/commitment\fR random commit message generator\.
|
||||
.
|
||||
.TP
|
||||
Navigate to your preferred workspace and create the plugin\'s directory and Git repository:
|
||||
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
mkdir \-p my/workspace/wtc; and cd my/workspace/wtc
|
||||
git init
|
||||
git remote add origin https://github\.com/<owner>/wtc
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
Add the implementation\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
cat > wtc\.fish
|
||||
|
||||
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
|
||||
^C
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
Add completions\. \fIwtc\fR is simple enough that you could get away without \fB__fisher_parse_help\fR, but more complex utilities, or utilities whose CLI evolves over time, can benefit using automatic completion generation\. Note that in order to use \fB__fisher_parse_help\fR, your command must provide a \fB\-\-help\fR option that prints usage information to standard output\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
mkdir completions
|
||||
cat > completions/wtc\.fish
|
||||
|
||||
set \-l IFS ";"
|
||||
wtc \-\-help | __fisher_parse_help | while read \-l info long short
|
||||
complete \-c wtc \-s "$short" \-l "$long" \-d "$info"
|
||||
end
|
||||
^C
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.TP
|
||||
Add basic documentation\. Fisherman uses standard manual pages for displaying help information\. There are utilities that can help you generate man pages from other text formats, such as Markdown\. One example is \fBronn\fR(1)\. For this example, type will do:
|
||||
|
||||
.
|
||||
.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
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
Commit changes and push to the remote repository\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
git add \-\-all
|
||||
git commit \-m "What the commit? 1\.0"
|
||||
git push origin master
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
Install with Fisherman\. If you would like to submit your package for registration install the \fBsubmit\fR plugin or send a pull request to the main index repository in \fIhttps://github\.com/fisherman/index\fR\. See \fBIndex\fR in \fBfisher help tour\fR\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install github/*owner*/wtc
|
||||
wtc
|
||||
(\e /)
|
||||
(O\.o)
|
||||
(> <) Bunny approves these changes\.
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
\fBman\fR(1), \fBcomplete\fR(1)
|
||||
.
|
||||
.br
|
||||
\fBfisher help commands\fR
|
||||
.
|
||||
.br
|
||||
\fBfisher help fishfile\fR
|
||||
.
|
||||
.br
|
||||
|
||||
@ -1,136 +0,0 @@
|
||||
fisher-plugins(7) -- Creating Fisherman Plugins
|
||||
===============================================
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
This document describes how to create Fisherman plugins. This includes stand-alone utilities, prompts, extension commands and configuration plugins.
|
||||
|
||||
There is no technical distinction between any of the terms aforementioned, but there is a *conceptual* difference.
|
||||
|
||||
## DEFINITIONS
|
||||
|
||||
* `Standalone Utilities`: Plugins that define one or more functions.
|
||||
|
||||
* `Prompts / Themes`: Plugins that modify the appearance of the fish prompt by defining a `fish_prompt` / `fish_right_prompt` function/s.
|
||||
|
||||
* `Extension Commands`: Plugins that extend Fisherman default commands. An extension plugin must define one or more functions like `fisher_<my_command>`. For specific information about commands, see `fisher help commands`.
|
||||
|
||||
* `Configuration Plugins`: Plugins that include one or more `my_plugin.config.fish` files. Files that follow this convention are evaluated at the start of the session. If a file does not follow the `<my_plugin>.config.fish` convention, it must be added to `conf.d/*.fish` and the `<my_plugin>` name will be prepended to the file during the installation process.
|
||||
|
||||
An example plugin that follows several of the conventions proposed above.
|
||||
|
||||
```
|
||||
my_plugin
|
||||
|-- fisher_my_plugin.fish
|
||||
|-- my_plugin.fish
|
||||
|-- fish_prompt.fish
|
||||
|-- fish_right_prompt.fish
|
||||
|-- my_plugin.config.fish
|
||||
|-- functions
|
||||
| `-- my_plugin_helper.fish
|
||||
|-- conf.d
|
||||
| `-- *.fish
|
||||
|-- completions
|
||||
| `-- my_plugin.fish
|
||||
`-- man
|
||||
`-- man1
|
||||
`-- my_plugin.1
|
||||
```
|
||||
|
||||
## DEPENDENCIES
|
||||
|
||||
A plugin may list any number of dependencies to other plugins using a *fishfile*, see `fisher help fishfile`.
|
||||
|
||||
For example, if `<my_plugin>` depends on `<your_plugin>`, add this dependency into a fishfile at the root of the project:
|
||||
|
||||
```
|
||||
cat > my_plugin/fishfile
|
||||
your_plugin
|
||||
CTRL^D
|
||||
```
|
||||
|
||||
Plugins may also define completions using `complete`(1) and provide documentation in the form of `man`(1) pages.
|
||||
|
||||
## EXAMPLE
|
||||
|
||||
This section walks you through creating *wtc*, a stand-alone plugin based in *github.com/ngerakines/commitment* random commit message generator.
|
||||
|
||||
* Navigate to your preferred workspace and create the plugin's directory and Git repository:
|
||||
|
||||
```fish
|
||||
mkdir -p my/workspace/wtc; and cd my/workspace/wtc
|
||||
git init
|
||||
git remote add origin https://github.com/<owner>/wtc
|
||||
```
|
||||
|
||||
* Add the implementation.
|
||||
|
||||
```fish
|
||||
cat > wtc.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
|
||||
^C
|
||||
```
|
||||
|
||||
* Add completions. *wtc* is simple enough that you could get away without `__fisher_parse_help`, but more complex utilities, or utilities whose CLI evolves over time, can benefit using automatic completion generation. Note that in order to use `__fisher_parse_help`, your command must provide a `--help` option that prints usage information to standard output.
|
||||
|
||||
```fish
|
||||
mkdir completions
|
||||
cat > completions/wtc.fish
|
||||
|
||||
set -l IFS ";"
|
||||
wtc --help | __fisher_parse_help | while read -l info long short
|
||||
complete -c wtc -s "$short" -l "$long" -d "$info"
|
||||
end
|
||||
^C
|
||||
```
|
||||
|
||||
* Add basic documentation. Fisherman uses standard manual pages for displaying help information. There are utilities that can help you generate man pages from other text formats, such as Markdown. One example is `ronn`(1). For this example, type will do:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
* Commit changes and push to the remote repository.
|
||||
|
||||
```fish
|
||||
git add --all
|
||||
git commit -m "What the commit? 1.0"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
* Install with Fisherman. If you would like to submit your package for registration install the `submit` plugin or send a pull request to the main index repository in *https://github.com/fisherman/index*. See `Index` in `fisher help tour`.
|
||||
|
||||
```fish
|
||||
fisher install github/*owner*/wtc
|
||||
wtc
|
||||
(\ /)
|
||||
(O.o)
|
||||
(> <) Bunny approves these changes.
|
||||
```
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`man`(1), `complete`(1)<br>
|
||||
`fisher help commands`<br>
|
||||
`fisher help fishfile`<br>
|
||||
@ -1,340 +0,0 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "FISHER\-TOUR" "7" "February 2016" "" "fisherman"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBfisher\-tour\fR \- Fisherman Tour
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
Fisherman is a blazing fast, modern plugin manager for \fBfish\fR(1)\.
|
||||
.
|
||||
.P
|
||||
Fisherman runs virtually no initialization code, making it \fBas fast as no Fisherman\fR\. The cache mechanism lets you query the index offline and enable or disable plugins as you wish\.
|
||||
.
|
||||
.P
|
||||
Other features include dependency management, excellent test coverage, plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and plugins\.
|
||||
.
|
||||
.P
|
||||
This document describes Fisherman features and their implementation details\. For usage and command help see \fBfisher\fR(1)\.
|
||||
.
|
||||
.SH "FLAT TREE"
|
||||
The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time\.
|
||||
.
|
||||
.P
|
||||
To explain how this is possible, we need to make a digression and discuss function scope first\. In fish, all functions share the same scope and you can use only one name per function\.
|
||||
.
|
||||
.P
|
||||
In the following example:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
function foo
|
||||
echo $_
|
||||
function bar
|
||||
end
|
||||
end
|
||||
|
||||
function bar
|
||||
echo $_
|
||||
end
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
\fIfoo\fR and \fIbar\fR are available immediately at the command line prompt and both print their names\. But there is a catch, calling \fIfoo\fR at least once will create a new \fIbar\fR function, effectively erasing the previous \fIbar\fR definition\. Subsequent calls to \fIbar\fR will print nothing\.
|
||||
.
|
||||
.P
|
||||
By convention, functions that start with any number of underscores are \fIintentionally\fR private, but there is no mechanism that prevents you from calling them once they are loaded\.
|
||||
.
|
||||
.P
|
||||
With this in mind, it\'s possible to improve the slow shell start problem using a \fIflat\fR tree structure whose path is loaded only once\.
|
||||
.
|
||||
.P
|
||||
The overhead of juggling multiple path hierarchies in a per\-plugin basis yields no benefits as everything is shared inside the same scope\.
|
||||
.
|
||||
.P
|
||||
Loading a path simply means adding the desired location to the \fB$fish_function_path\fR array\. See also \fBfunctions\fR(1)\.
|
||||
.
|
||||
.P
|
||||
Here is a snapshot of 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
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
If you are already familiar in the way Fish handles your user configuration, you will find the above structure similar to \fB$XDG_CONFIG_HOME/fish\fR\. See \fBInitialization Files\fR in \fBhelp fish\fR to learn more about fish configuration\.
|
||||
.
|
||||
.P
|
||||
\fBconf\.d\fR, short for configuration directory, is used for initialization files, i\.e\., files that should run at the start of the shell\. Files that follow the naming convention \fB<my_plugin>\.config\.fish\fR are added there\. If a file does not follow the \fB<my_plugin>\.config\.fish\fR convention, \fB<my_plugin>\fR will be added during the installation process\.
|
||||
.
|
||||
.SS "PLUGINS"
|
||||
Plugins are components that extend and add features to your shell\. To see what plugins are available use \fBfisher search\fR\. You can also type \fBfisher install\fR and hit \fItab\fR once to get formatted plugin information\. The same works for \fBfisher update\fR and \fBfisher uninstall\fR\.
|
||||
.
|
||||
.P
|
||||
To learn how to create plugins, see \fBfisher help plugins\fR\.
|
||||
.
|
||||
.P
|
||||
You can install a plugin by their name, URL or by indicating the path to a local plugin project\.
|
||||
.
|
||||
.P
|
||||
In order to install a plugin by \fIname\fR, it must be already published in the index database\. See \fBIndex\fR\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install shark
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
You can use an URL too if you have one\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install simnalamburt/shellder
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
If the domain or host is not provided, Fisherman will use \fBhttps://github\.com\fR by default\.
|
||||
.
|
||||
.P
|
||||
In addition, all of the following \fBowner/repo\fR variations are accepted:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
owner/repo \fB>\fR https://github\.com/owner/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fIgithub\fR/owner/repo \fB>\fR https://github\.com/owner/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fIgh\fR/owner/repo \fB>\fR https://github\.com/owner/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Shortcuts to other common Git repository hosting services are also available:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fIbb\fR/owner/repo \fB>\fR https://bitbucket\.org/owner/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fIgl\fR/owner/repo \fB>\fR https://gitlab\.com/owner/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fIomf\fR/owner/repo \fB>\fR https://github\.com/oh\-my\-fish/repo
|
||||
.
|
||||
.br
|
||||
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Because of Fisherman\'s flat tree model, there is no technical distinction between plugins or prompts\. Installing a prompt is equivalent to switching themes in other systems\. The interface is always \fIinstall\fR, \fIupdate\fR or \fIuninstall\fR\.
|
||||
.
|
||||
.P
|
||||
Throughout this document and other Fisherman manuals you will find the term prompt when referring to the \fIconcept\fR of a theme, i\.e\., a plugin that defines a \fBfish_prompt\fR / \fBfish_right_prompt\fR function/s\.
|
||||
.
|
||||
.SS "INDEX"
|
||||
You can install, update and uninstall plugins by their name, querying the Fisherman index\. The index is a plain text flat database independently managed\. You can use a custom index file by setting \fB$fisher_index\fR to your own file or URL\. Redirection URLs are currently not supported due to security and performance concerns\. See \fBfisher help config\fR\.
|
||||
.
|
||||
.P
|
||||
A copy of the index is downloaded each time a search query takes place, \fB$fisher_update_interval\fR seconds since the last update\. \fB$fisher_update_interval\fR is 10 seconds by default if not set\. This helps keeping the index up to date and allows you to search the database offline\.
|
||||
.
|
||||
.P
|
||||
The index itself is a list of records, each consisting of the following fields:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBname\fR, \fBurl\fR, \fBinfo\fR, one or more \fBtags\fR and \fBauthor\fR\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Fields are separated by a new line \fB\'\en\'\fR\. Tags are separated by one \fIspace\fR\. Here is a sample record:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
shark
|
||||
https://github\.com/bucaran/shark
|
||||
Fantastic Sparkline Generator
|
||||
chart tool report sparkline graph
|
||||
bucaran
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
To submit a new plugin for registration install the \fBsubmit\fR plugin:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install submit
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
For usage see the bundled documentation \fBfisher help submit\fR\.
|
||||
.
|
||||
.P
|
||||
You can also submit a new plugin manually and create a pull request in the index repository (github\.com/fisherman/fisher\-index):
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
git clone https://github\.com/fisherman/fisher\-index
|
||||
cd index
|
||||
echo "$name\en$URL\en$info\en$author\en$tags\en\en" >> index
|
||||
git push origin master
|
||||
open http://github\.com
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SS "CACHE"
|
||||
Downloaded plugins are stored as Git repositories under \fB$fisher_cache\fR\. See \fBfisher help config\fR to find out about other Fisherman configuration variables\.
|
||||
.
|
||||
.P
|
||||
When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path\. In this sense, this location works also like an intermediate \fBstage\fR\. In addition, manual pages are added to the corresponding man directory and if a Makefile is also detected, the command \fBmake\fR is run\.
|
||||
.
|
||||
.SS "FISHFILES"
|
||||
Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using \fBfisher \-\-list\fR\.
|
||||
.
|
||||
.P
|
||||
Your fishfile is stored in \fB$fisher_config/fishfile\fR by default, but you can customize its location setting \fB$fisher_file\fR in your user fish configuration file\.
|
||||
.
|
||||
.P
|
||||
Here is an example fishfile inside \fB$fisher_config\fR:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
# Ahoy! This is my Fishfile
|
||||
gitio
|
||||
fishtape
|
||||
shark
|
||||
get
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
The fishfile updates as you install / uninstall plugins\. See also \fBfisher help install\fR or \fBfisher help uninstall\fR\.
|
||||
.
|
||||
.SS "CONFIGURATION"
|
||||
Fisherman allows a high level of configuration using \fB$fisher_*\fR variables\. You can customize the home and configuration directories, cache and fishfile location, index source URL, command aliases, etc\. See \fBfisher help config\fR\.
|
||||
.
|
||||
.P
|
||||
You can also extend Fisherman by adding new commands and ship them as plugins\. Fisherman automatically adds completions to \fIcommands\fR based in the function \fIdescription\fR and usage help if provided\. See \fBfisher help help\fR and \fBfisher help commands\fR\.
|
||||
.
|
||||
.P
|
||||
To add completions to standalone utility plugins, use \fBcomplete\fR(1)\.
|
||||
.
|
||||
.SS "CLI"
|
||||
If you are already familiar with other UNIX tools, you\'ll find Fisherman commands behave intuitively\.
|
||||
.
|
||||
.P
|
||||
Most commands read the standard input by default when no options are given and produce easy to parse output, making Fisherman commands ideal for plumbing and building upon each other\.
|
||||
.
|
||||
.P
|
||||
Fisherman also ships with a CLI options parser and a job spinner you can use to implement your own CLIs\. See \fBgetopts\fR(1) and \fBspin\fR(1)\.
|
||||
.
|
||||
.SH "COMPATIBILITY"
|
||||
Fisherman supports Oh My Fish! themes and plugins, but some features are turned off by default for performance reasons\.
|
||||
.
|
||||
.P
|
||||
Oh My Fish! evaluates every \fI\.fish\fR file inside the root directory for every plugin installed during shell start\. This is necessary in order to load any existing \fBinit\fR event functions and immediately invoke them using fish \fBemit\fR(1)\.
|
||||
.
|
||||
.P
|
||||
Since it is not possible to determine whether a file defines an initialization event without evaluating its contents first, Oh My Fish! sources all \fB*\.fish\fR files and then emits events for each plugin\.
|
||||
.
|
||||
.P
|
||||
Not all plugins opt in the initialization mechanism, therefore support for this behavior is turned off by default\. If you would like Fisherman to behave like Oh My Fish! at the start of the shell session, install the \fBlegacy\fR compatibility plugin\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
fisher install legacy
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
This plugin also adds definitions for some of Oh My Fish! Core Library functions\.
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
\fBfisher\fR(1), \fBspin\fR(1), \fBgetopts\fR(1)
|
||||
.
|
||||
.br
|
||||
\fBfisher help\fR
|
||||
.
|
||||
.br
|
||||
\fBfisher help config\fR
|
||||
.
|
||||
.br
|
||||
\fBfisher help plugins\fR
|
||||
.
|
||||
.br
|
||||
\fBfisher help commands\fR
|
||||
.
|
||||
.br
|
||||
|
||||
@ -1,206 +0,0 @@
|
||||
fisher-tour(7) -- Fisherman Tour
|
||||
================================
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
Fisherman is a blazing fast, modern plugin manager for `fish`(1).
|
||||
|
||||
Fisherman runs virtually no initialization code, making it **as fast as no Fisherman**. The cache mechanism lets you query the index offline and enable or disable plugins as you wish.
|
||||
|
||||
Other features include dependency management, excellent test coverage, plugin search capabilities and full compatibility with Tackle, Oh My Fish! and Wahoo themes and plugins.
|
||||
|
||||
This document describes Fisherman features and their implementation details. For usage and command help see `fisher`(1).
|
||||
|
||||
## FLAT TREE
|
||||
|
||||
The configuration directory structure is optimized to help your shell start new sessions as quickly as possible, regardless of the numbers of plugins or prompts enabled at any given time.
|
||||
|
||||
To explain how this is possible, we need to make a digression and discuss function scope first. In fish, all functions share the same scope and you can use only one name per function.
|
||||
|
||||
In the following example:
|
||||
|
||||
```
|
||||
function foo
|
||||
echo $_
|
||||
function bar
|
||||
end
|
||||
end
|
||||
|
||||
function bar
|
||||
echo $_
|
||||
end
|
||||
```
|
||||
|
||||
*foo* and *bar* are available immediately at the command line prompt and both print their names. But there is a catch, calling *foo* at least once will create a new *bar* function, effectively erasing the previous *bar* definition. Subsequent calls to *bar* will print nothing.
|
||||
|
||||
By convention, functions that start with any number of underscores are *intentionally* private, but there is no mechanism that prevents you from calling them once they are loaded.
|
||||
|
||||
With this in mind, it's possible to improve the slow shell start problem using a *flat* tree structure whose path is loaded only once.
|
||||
|
||||
The overhead of juggling multiple path hierarchies in a per-plugin basis yields no benefits as everything is shared inside the same scope.
|
||||
|
||||
Loading a path simply means adding the desired location to the `$fish_function_path` array. See also `functions`(1).
|
||||
|
||||
Here is a snapshot of 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
|
||||
```
|
||||
|
||||
If you are already familiar in the way Fish handles your user configuration, you will find the above structure similar to `$XDG_CONFIG_HOME/fish`. See `Initialization Files` in `help fish` to learn more about fish configuration.
|
||||
|
||||
`conf.d`, short for configuration directory, is used for initialization files, i.e., files that should run at the start of the shell. Files that follow the naming convention `<my_plugin>.config.fish` are added there. If a file does not follow the `<my_plugin>.config.fish` convention, `<my_plugin>` will be added during the installation process.
|
||||
|
||||
### PLUGINS
|
||||
|
||||
Plugins are components that extend and add features to your shell. To see what plugins are available use `fisher search`. You can also type `fisher install` and hit *tab* once to get formatted plugin information. The same works for `fisher update` and `fisher uninstall`.
|
||||
|
||||
To learn how to create plugins, see `fisher help plugins`.
|
||||
|
||||
You can install a plugin by their name, URL or by indicating the path to a local plugin project.
|
||||
|
||||
In order to install a plugin by *name*, it must be already published in the index database. See `Index`.
|
||||
|
||||
```
|
||||
fisher install shark
|
||||
```
|
||||
|
||||
You can use an URL too if you have one.
|
||||
|
||||
```
|
||||
fisher install simnalamburt/shellder
|
||||
```
|
||||
|
||||
If the domain or host is not provided, Fisherman will use `https://github.com` by default.
|
||||
|
||||
In addition, all of the following `owner/repo` variations are accepted:
|
||||
|
||||
* owner/repo `>` https://github.com/owner/repo<br>
|
||||
* *github*/owner/repo `>` https://github.com/owner/repo<br>
|
||||
* *gh*/owner/repo `>` https://github.com/owner/repo<br>
|
||||
|
||||
Shortcuts to other common Git repository hosting services are also available:
|
||||
|
||||
* *bb*/owner/repo `>` https://bitbucket.org/owner/repo<br>
|
||||
* *gl*/owner/repo `>` https://gitlab.com/owner/repo<br>
|
||||
* *omf*/owner/repo `>` https://github.com/oh-my-fish/repo<br>
|
||||
|
||||
Because of Fisherman's flat tree model, there is no technical distinction between plugins or prompts. Installing a prompt is equivalent to switching themes in other systems. The interface is always *install*, *update* or *uninstall*.
|
||||
|
||||
Throughout this document and other Fisherman manuals you will find the term prompt when referring to the *concept* of a theme, i.e., a plugin that defines a `fish_prompt` / `fish_right_prompt` function/s.
|
||||
|
||||
### INDEX
|
||||
|
||||
You can install, update and uninstall plugins by their name, querying the Fisherman index. The index is a plain text flat database independently managed. You can use a custom index file by setting `$fisher_index` to your own file or URL. Redirection URLs are currently not supported due to security and performance concerns. See `fisher help config`.
|
||||
|
||||
A copy of the index is downloaded each time a search query takes place, `$fisher_update_interval` seconds since the last update. `$fisher_update_interval` is 10 seconds by default if not set. This helps keeping the index up to date and allows you to search the database offline.
|
||||
|
||||
The index itself 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*. Here is a sample record:
|
||||
|
||||
```
|
||||
shark
|
||||
https://github.com/bucaran/shark
|
||||
Fantastic Sparkline Generator
|
||||
chart tool report sparkline graph
|
||||
bucaran
|
||||
```
|
||||
|
||||
To submit a new plugin for registration install the `submit` plugin:
|
||||
|
||||
```
|
||||
fisher install submit
|
||||
```
|
||||
|
||||
For usage see the bundled documentation `fisher help submit`.
|
||||
|
||||
You can also submit a new plugin manually and create a pull request in the index repository (github.com/fisherman/fisher-index):
|
||||
|
||||
```
|
||||
git clone https://github.com/fisherman/fisher-index
|
||||
cd index
|
||||
echo "$name\n$URL\n$info\n$author\n$tags\n\n" >> index
|
||||
git push origin master
|
||||
open http://github.com
|
||||
```
|
||||
|
||||
### CACHE
|
||||
|
||||
Downloaded plugins are stored as Git repositories under `$fisher_cache`. See `fisher help config` to find out about other Fisherman configuration variables.
|
||||
|
||||
When you install or uninstall a plugin, Fisherman downloads the repository to the cache and copies only the relevant files from the cache to the loaded function and / or completion path. In this sense, this location works also like an intermediate `stage`. In addition, manual pages are added to the corresponding man directory and if a Makefile is also detected, the command `make` is run.
|
||||
|
||||
### FISHFILES
|
||||
|
||||
Fishfiles let you share plugin configurations across multiple installations, let plugins declare dependencies and teach Fisherman what plugins are currently enabled / disabled when using `fisher --list`.
|
||||
|
||||
Your fishfile is stored in `$fisher_config/fishfile` by default, but you can customize its location setting `$fisher_file` in your user fish configuration file.
|
||||
|
||||
Here is an example fishfile inside `$fisher_config`:
|
||||
|
||||
```
|
||||
# Ahoy! This is my Fishfile
|
||||
gitio
|
||||
fishtape
|
||||
shark
|
||||
get
|
||||
```
|
||||
|
||||
The fishfile updates as you install / uninstall plugins. See also `fisher help install` or `fisher help uninstall`.
|
||||
|
||||
|
||||
### CONFIGURATION
|
||||
|
||||
Fisherman allows a high level of configuration using `$fisher_*` variables. You can customize the home and configuration directories, cache and fishfile location, index source URL, command aliases, etc. See `fisher help config`.
|
||||
|
||||
You can also extend Fisherman by adding new commands and ship them as plugins. Fisherman automatically adds completions to *commands* based in the function *description* and usage help if provided. See `fisher help help` and `fisher help commands`.
|
||||
|
||||
To add completions to standalone utility plugins, use `complete`(1).
|
||||
|
||||
### CLI
|
||||
|
||||
If you are already familiar with other UNIX tools, you'll find Fisherman commands behave intuitively.
|
||||
|
||||
Most commands read the standard input by default when no options are given and produce easy to parse output, making Fisherman commands ideal for plumbing and building upon each other.
|
||||
|
||||
Fisherman also ships with a CLI options parser and a job spinner you can use to implement your own CLIs. See `getopts`(1) and `spin`(1).
|
||||
|
||||
## COMPATIBILITY
|
||||
|
||||
Fisherman supports Oh My Fish! themes and plugins, but some features are turned off by default for performance reasons.
|
||||
|
||||
Oh My Fish! evaluates every *.fish* file inside the root directory for every plugin installed during shell start. This is necessary in order to load any existing `init` event functions and immediately invoke them using fish `emit`(1).
|
||||
|
||||
Since it is not possible to determine whether a file defines an initialization event without evaluating its contents first, Oh My Fish! sources all `*.fish` files and then emits events for each plugin.
|
||||
|
||||
Not all plugins opt in the initialization mechanism, therefore support for this behavior is turned off by default. If you would like Fisherman to behave like Oh My Fish! at the start of the shell session, install the `legacy` compatibility plugin.
|
||||
|
||||
```
|
||||
fisher install legacy
|
||||
```
|
||||
|
||||
This plugin also adds definitions for some of Oh My Fish! Core Library functions.
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
`fisher`(1), `spin`(1), `getopts`(1)<br>
|
||||
`fisher help`<br>
|
||||
`fisher help config`<br>
|
||||
`fisher help plugins`<br>
|
||||
`fisher help commands`<br>
|
||||
@ -0,0 +1,537 @@
|
||||
.\" 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)
|
||||
@ -0,0 +1,336 @@
|
||||
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)
|
||||
@ -0,0 +1 @@
|
||||
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
|
||||
@ -0,0 +1 @@
|
||||
/Users/bucaran/c/fisherman/fisherman/man/man7/fisher-tutorial.7
|
||||
Loading…
Reference in New Issue