projects/fisher
1
0
Fork 0
mirror of https://github.com/jorgebucaran/fisher synced 2024-06-28 23:01:50 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update README.

Browse source
This commit is contained in:
Jorge Bucaran 2016-03-14 04:20:40 +09:00
parent ff24ee8e9a
commit 918f7bccd0
No known key found for this signature in database
GPG key ID: E54BA3C0E646DB30
21 changed files with 456 additions and 867 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
CHANGELOG.md
View file

@ -1,5 +1,15 @@
# Change Log # Change Log
## [1.4.0][v140] - 2016-03-14
* :zap: Fisherman updates plugins in parallel now. Performance will vary, but chances are you will perceive 3 to 10 times faster updates.
![para](https://cloud.githubusercontent.com/assets/8317250/13730493/5b704bec-e994-11e5-81b9-d3af2c0f9821.gif)
* Deprecate fisher list file in favor of fisher list - < file
* Revise documentation.
## [1.3.1][v131] - 2016-03-12 ## [1.3.1][v131] - 2016-03-12
* Fix bug in fisher_config_color_reset not declaring path variable. * Fix bug in fisher_config_color_reset not declaring path variable.

203
README.md
View file

@ -22,7 +22,7 @@ curl -sL get.fisherman.sh | fish
[![play]][play-link] [![play]][play-link]
<sub>If you don't have Fish, you need to install it too. Install instructions can be found <a href="https://github.com/fisherman/fisherman/wiki/Installing-Fish">here</a>.</sub> <sub>Install instructions for fish can be found <a href="https://github.com/fisherman/fisherman/wiki/Installing-Fish">here</a>.</sub>
## Install ## Install
@ -41,37 +41,43 @@ The Fisherman CLI consists of: *install*, *update*, *uninstall*, *list*, *search
* Install plugins. * Install plugins.
``` ```
fisher install fishtape shark get fisher i fishtape shark get bobthefish
```
* Install Oh My Fish! plugins.
```fish
fisher i omf/plugin-{percol,jump,fasd}
``` ```
* Install a plugin from a local directory. * Install a plugin from a local directory.
```fish ```fish
fisher install ./path/to/plugin fisher i ./path/to/plugin
``` ```
* Install a plugin from a URL. * Install a plugin from various URLs.
```fish ```fish
fisher install owner/repo fisher i https://github.com/some/plugin another/plugin bb:one/more
``` ```
* Install a plugin from a Gist URL. * Install a plugin from a Gist.
```fish ```fish
fisher install gist.github.com/owner/1f40e1c6e0551b2666b2 fisher i gist.github.com/owner/1f40e1c6e0551b2666b2
``` ```
* Update Fisherman. * Update everything.
``` ```
fisher update fisher u
``` ```
* Update plugins. * Update plugins.
``` ```
fisher update shark get fisher u shark get
``` ```
* Uninstall plugins. * Uninstall plugins.
@ -80,16 +86,10 @@ fisher update shark get
fisher uninstall fishtape debug fisher uninstall fishtape debug
``` ```
* Uninstall plugins and remove them from the cache. * Get help.
```fish ```fish
fisher uninstall fishtape debug -f fisher h
```
* Show the documentation.
```fish
fisher help
``` ```
## List and search ## List and search
@ -123,31 +123,37 @@ fisher search
... ...
``` ```
Get detailed information about a plugin. Query the index using regular expressions.
``` ```
fisher search shellder fisher search --name~/git-is/
> shellder by simnalamburt git-is-dirty Test if there are changes not staged for commit
Powerline prompt optimized for speed git-is-empty Test if a repository is empty
github.com/simnalamburt/shellder git-is-repo Test if the current directory is a Git repo
git-is-staged Test if there are changes staged for commit
git-is-stashed Test if there are changes in the stash
git-is-touched Test if there are changes in the working tree
``` ```
Search plugins using tags. Search using tags.
``` ```
fisher search --tag={git,test} fisher search --tag={git,test}
... ...
* fishtape TAP producing test runner * fishtape TAP producing test runner
git-branch-name Get the name of the current Git branch 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-dirty Test if there are changes not staged for commit
git-is-empty Test if a repository is empty
git-is-repo Test if the current directory is a Git repo
git-is-staged Test if there are changes staged for commit
git-is-stashed Test if there are changes in the stash git-is-stashed Test if there are changes in the stash
git-is-touched Test if there are changes in the working tree
... ...
``` ```
The legend consists of: The legend consists of:
* `*` The plugin is currently enabled * `*` The plugin is enabled
* `>` The plugin is a prompt * `>` The plugin is a prompt
* `@` The plugin is a symbolic link * `@` The plugin is a symbolic link
@ -156,19 +162,19 @@ The legend consists of:
Fisherman commands are pipe aware. Plumb one with another to create complex functionality. Fisherman commands are pipe aware. Plumb one with another to create complex functionality.
* Update all the plugins in the cache. Update plugins installed as symbolic links.
```fish ```fish
fisher list | fisher update - fisher list --link | fisher update -
``` ```
* Enable all the plugins that are currently disabled. Enable all the plugins currently disabled.
```fish ```fish
fisher list --disabled | fisher install fisher list --disabled | fisher install
``` ```
* Uninstall all the plugins and remove them from the cache. Uninstall all the plugins and remove them from the cache.
```fish ```fish
fisher list | fisher uninstall --force fisher list | fisher uninstall --force
@ -176,7 +182,7 @@ fisher list | fisher uninstall --force
## Dotfiles ## Dotfiles
When you install a plugin, Fisherman updates a file known as the *fishfile* to track what plugins are currently enabled. When you install a plugin, Fisherman updates the *fishfile* to track what plugins are currently enabled.
* Customize the location of the fishfile. * Customize the location of the fishfile.
@ -211,7 +217,7 @@ $fisher_config
The index is a plain text database that lists Fisherman official plugins. The index is a plain text database that lists Fisherman official plugins.
The index is a list of records, each consisting of the following fields: *name*, *url*, *info*, one or more *tags* and *author*. The index lists records, each consisting the fields: *name*, *url*, *info*, one or more *tags* and *author*.
``` ```
z z
@ -225,10 +231,10 @@ If you have a plugin you would like to submit to the index, use the submit plugi
``` ```
fisher install submit fisher install submit
fisher submit my_plugin fisher submit my_plugin description tags url
``` ```
Otherwise, submit the plugin manually by creating a pull request in the [index](https://github.com/fisherman/fisher-index) repository. Or, submit the plugin manually by creating a pull request in the [index](https://github.com/fisherman/fisher-index) repository.
``` ```
git clone https://github.com/fisherman/fisher-index git clone https://github.com/fisherman/fisher-index
@ -239,19 +245,19 @@ git push origin master
## Variables ## Variables
* *$fisher_home*<br> * $fisher_home:
The home directory. If you installed Fisherman using the recommended method curl -sL install.fisherman.sh | fish, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default. The home directory. If you installed Fisherman using the recommended method, the location ought to be *XDG_DATA_HOME/fisherman*.
* *$fisher_config*<br> * $fisher_config:
The configuration directory. This is default location of the *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. The default location is *XDG_CONFIG_HOME/fisherman*. The configuration directory. This is default location of your *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. *XDG_CONFIG_HOME/fisherman* by default.
* *$fisher_file*<br> * $fisher_file:
See FISHFILE above. See [fishfile](#fishfile) above.
* *$fisher_cache*<br> * $fisher_cache:
The cache directory. Plugins are downloaded to this location. The cache directory. Plugins are downloaded to this location.
* *$fisher_alias* *command*=*alias* ...<br> * $fisher_alias *command*=*alias* ...:
Use this variable to create aliases of Fisherman commands. Use this variable to create aliases of Fisherman commands.
## Plugins ## Plugins
@ -263,26 +269,18 @@ fisher install new
fisher new plugin < meta.yml fisher new plugin < meta.yml
``` ```
See the documentation of new for details. See the documentation for [new] for details.
### Utilities ### Utilities
Utilities are plugins that define one or more functions. Utilities are plugins that define one or more functions.
This example walks you through creating *wtc*, a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator. Below is a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator.
* Create a directory and initialize a Git repository.
```fish ```fish
mkdir wtc mkdir wtc
cd 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" function wtc -d "Generate a random commit message"
switch "$argv" switch "$argv"
case -h --help case -h --help
@ -293,26 +291,16 @@ function wtc -d "Generate a random commit message"
curl -s whatthecommit.com/index.txt curl -s whatthecommit.com/index.txt
end end
functions wtc > wtc.fish functions wtc > wtc.fish
```
* Install the plugin.
```fish
fisher install . fisher install .
```
```
wtc wtc
(\ /) (\ /)
(O.o) (O.o)
(> <) Bunny approves these changes. (> <) 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 ### Submit
To submit wtc to the official index. To submit wtc to the official index.
@ -327,66 +315,20 @@ This will create a PR in the Fisherman index repository. Once the PR is approved
fisher install wtc fisher install wtc
``` ```
### Completions
Create a completions directory and add a completions file.
```fish
mkdir completions
$EDITOR completions/wtc.fish
```
```fish
complete --command wtc --short h --long help --description "Show usage help"
```
Or use `__fisher_complete` to create completions from wtc usage output.
```
wtc --help | __fisher_complete wtc
```
### Docs
Create a man/man1 directory and add a man(1) page for wtc.
There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).
To create a man page manually.
```
mkdir -p man/man1
$EDITOR 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
```
### Dependencies ### Dependencies
A plugin can list dependencies to other plugins using a *fishfile*. 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 dependencies. Create a *fishfile* in the root of your project and add the name or URL of your dependencies.
```fish ```
cat > fishfile
my_plugin my_plugin
https://github.com/owner/another_plugin https://github.com/owner/another_plugin
^D
``` ```
### Prompts ### Prompts
Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors. Prompts, or themes, are plugins that modify the appearance of the shell prompt and colors.
Create a `fish_prompt` function. Create a `fish_prompt` function.
@ -394,6 +336,8 @@ Create a `fish_prompt` function.
function fish_prompt function fish_prompt
printf "%s (%s) >> " (prompt_pwd) Fisherman printf "%s (%s) >> " (prompt_pwd) Fisherman
end end
```
```
~ (Fisherman) >> type here ~ (Fisherman) >> type here
``` ```
@ -410,8 +354,10 @@ Save the functions to a directory and install the prompt as a plugin.
```fish ```fish
mkdir my_prompt mkdir my_prompt
cd my_prompt cd my_prompt
functions fish_prompt > fish_prompt.fish functions fish_prompt > fish_prompt.fish
functions fish_right_prompt > fish_right_prompt.fish functions fish_right_prompt > fish_right_prompt.fish
fisher install . fisher install .
``` ```
@ -423,7 +369,9 @@ function set_color_custom
set -U fish_color_command yellow set -U fish_color_command yellow
set -U fish_color_param white set -U fish_color_param white
end end
functions set_color_custom > set_color_custom.fish functions set_color_custom > set_color_custom.fish
fisher update . fisher update .
``` ```
@ -448,37 +396,15 @@ It's 6:30
Make it a plugin Make it a plugin
```fish ```fish
fisher install fisher_time 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
Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d. 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. The following example implements a fish_postexec hook to display the duration of the last command in milliseconds.
```fish ```fish
mkdir -p runtime/conf.d mkdir -p runtime/conf.d
@ -486,7 +412,7 @@ cd runtime
$EDITOR conf.d/fish_postexec.fish $EDITOR conf.d/fish_postexec.fish
``` ```
``` ```fish
function fish_postexec --on-event fish_postexec function fish_postexec --on-event fish_postexec
printf "%sms\n" $CMD_DURATION > /dev/stderr printf "%sms\n" $CMD_DURATION > /dev/stderr
end end
@ -512,3 +438,4 @@ fisher install ./postexec
[other]: https://github.com/fisherman/fisherman/wiki/Installing-Fisherman#notes [other]: https://github.com/fisherman/fisherman/wiki/Installing-Fisherman#notes
[Fisherman]: http://fisherman.sh [Fisherman]: http://fisherman.sh
[new]: https://github.com/fishery/new

16
functions/__fisher_gist_to_name.fish
View file

@ -1,15 +1,15 @@
function __fisher_gist_to_name -a url function -S __fisher_gist_to_name -a url
set -l id (printf "%s\n" "$url" | sed 's|.*/||') set -l gist_id (printf "%s\n" "$url" | sed 's|.*/||')
set -l name ( set -l name (
spin "curl -Ss https://api.github.com/gists/$id" -f " @\r" | awk ' spin "curl -Ss https://api.github.com/gists/$gist_id" -f " $color@$color_normal\r" | awk '
/"files": / { files++ } /"files": / { files++ }
/"[^ ]+.fish": / && files { /"[^ ]+.fish": / && files {
gsub("^ *\"|\.fish.*", "") gsub("^ *\"|\.fish.*", "")
print print
} }
' '
) )

3
functions/__fisher_list.fish Normal file
View file

@ -0,0 +1,3 @@
function __fisher_list
__fisher_file | __fisher_name
end

23
functions/__fisher_path_update.fish
View file

@ -1,27 +1,12 @@
function __fisher_path_update -a path function __fisher_path_update -a path
pushd $path pushd $path
set -l branch
if not set branch (sed "s|.*/||" < .git/HEAD)
return 1
end
git stash --quiet ^ /dev/null
git checkout master --quiet ^ /dev/null
if not git pull --quiet --rebase origin master if not git pull --quiet --rebase origin master
git rebase --abort > /dev/null git rebase --abort
git fetch --quiet origin master git fetch --quiet origin master
git reset --quiet --hard FETCH_HEAD git reset --quiet --hard FETCH_HEAD
git clean --quiet -d --force git clean --quiet -d --force
end ^ /dev/null end ^ /dev/null
if test ! -z "$branch"
git checkout "$branch" --quiet ^ /dev/null
end
git stash apply --quiet ^ /dev/null
popd popd
end end

19
functions/fisher_install.fish
View file

@ -3,6 +3,8 @@ function fisher_install -d "Install plugins"
set -l option set -l option
set -l stdout /dev/stdout set -l stdout /dev/stdout
set -l stderr /dev/stderr set -l stderr /dev/stderr
set -l color (set_color $fish_color_match)
set -l color_normal (set_color normal)
getopts $argv | while read -l 1 2 getopts $argv | while read -l 1 2
switch "$1" switch "$1"
@ -16,15 +18,20 @@ function fisher_install -d "Install plugins"
set plugins $plugins $2 set plugins $plugins $2
end end
case C no-color
set color
set color_normal
case q quiet case q quiet
set stdout /dev/null set stdout /dev/null
set stderr /dev/null set stderr /dev/null
case h case h
printf "Usage: fisher install [<plugins>] [--force] [--quiet] [--help]\n\n" printf "Usage: fisher install [<plugins>] [--force] [--quiet] [--help]\n\n"
printf " -f --force Reinstall given plugin/s\n" printf " -f --force Reinstall given plugin/s\n"
printf " -q --quiet Enable quiet mode\n" printf " -q --quiet Enable quiet mode\n"
printf " -h --help Show usage help\n" printf " -C --no-color Turn off color display\n"
printf " -h --help Show usage help\n"
return return
case \* case \*
@ -64,7 +71,7 @@ function fisher_install -d "Install plugins"
case https://gist.github.com\* case https://gist.github.com\*
debug "Gist %s" $item debug "Gist %s" $item
if set -l name (__fisher_gist_to_name $item) if set -l name (__fisher_gist_to_name $item )
printf "%s\t%s\n" $item $name printf "%s\t%s\n" $item $name
else else
printf "fisher: Repository '%s' not found.\n" $item > $stderr printf "fisher: Repository '%s' not found.\n" $item > $stderr
@ -103,7 +110,7 @@ function fisher_install -d "Install plugins"
end end
end | while read -l url name end | while read -l url name
if contains -- $name (fisher_list $fisher_file) if contains -- $name (fisher_list --enabled)
if test -z "$option" if test -z "$option"
set skipped $skipped $name set skipped $skipped $name
continue continue
@ -133,7 +140,7 @@ function fisher_install -d "Install plugins"
else else
debug "Clone %s" $url debug "Clone %s" $url
if not spin "__fisher_url_clone $url $path" --error=$stderr -f " @\r" if not spin "__fisher_url_clone $url $path" --error=$stderr -f " $color@\r$color_normal"
continue continue
end end
end end

24
functions/fisher_list.fish
View file

@ -1,10 +1,12 @@
function fisher_list -a key -d "List installed plugins" function fisher_list -a key -d "List installed plugins"
switch "$key" set -l enabled
case -b --bare
__fisher_cache_list
if test -s "$fisher_file"
set enabled (__fisher_list < $fisher_file)
end
switch "$key"
case "" case ""
set -l enabled (fisher_list $fisher_file)
set -l cache (__fisher_cache_list) set -l cache (__fisher_cache_list)
if test -z "$cache" if test -z "$cache"
@ -38,11 +40,9 @@ function fisher_list -a key -d "List installed plugins"
find $fisher_cache/* -maxdepth 0 -type l ^ /dev/null | sed 's|.*/||' find $fisher_cache/* -maxdepth 0 -type l ^ /dev/null | sed 's|.*/||'
case --enabled case --enabled
fisher_list $fisher_file printf "%s\n" $enabled
case --disabled case --disabled
set -l enabled (fisher_list $fisher_file)
for name in (__fisher_cache_list) for name in (__fisher_cache_list)
if not contains -- $name $enabled if not contains -- $name $enabled
printf "%s\n" $name printf "%s\n" $name
@ -50,20 +50,14 @@ function fisher_list -a key -d "List installed plugins"
end end
case - case -
__fisher_file | __fisher_name __fisher_list
case -h case -h
printf "Usage: fisher list [<file>] [--enabled] [--disabled] [--bare] [--link] \n\n" printf "Usage: fisher list [--enabled] [--disabled] [--link]\n\n"
printf " -b --bare List plugin without decorators\n"
printf " -l --link List plugins that are symbolic links\n" printf " -l --link List plugins that are symbolic links\n"
printf " --enabled List plugins that are enabled\n" printf " --enabled List plugins that are enabled\n"
printf " --disabled List plugins that are disabled\n" printf " --disabled List plugins that are disabled\n"
printf " -h --help Show usage help\n" printf " -h --help Show usage help\n"
return return
case \*
if test -s "$key"
fisher_list - < $key
end
end end
end end

6
functions/fisher_search.fish
View file

@ -6,6 +6,8 @@ function fisher_search -d "Search plugin index"
set -l format set -l format
set -l option set -l option
set -l stdout /dev/stdout set -l stdout /dev/stdout
set -l color (set_color $fish_color_match)
set -l color_normal (set_color normal)
getopts $argv | while read -l 1 2 3 getopts $argv | while read -l 1 2 3
switch "$1" switch "$1"
@ -60,6 +62,8 @@ function fisher_search -d "Search plugin index"
set join "||" set join "||"
case C no-color case C no-color
set color
set color_normal
set option no-color set option no-color
case query case query
@ -101,7 +105,7 @@ function fisher_search -d "Search plugin index"
if test $fisher_last_update -gt $fisher_update_interval -o ! -f $index if test $fisher_last_update -gt $fisher_update_interval -o ! -f $index
debug "Update index start" debug "Update index start"
if spin "__fisher_index_update" --error=/dev/null -f " @\r" > /dev/null if spin "__fisher_index_update" --error=/dev/null -f " $color@$color_normal\r" > /dev/null
debug "Update index ok" debug "Update index ok"
__fisher_complete_reset __fisher_complete_reset
else else

2
functions/fisher_uninstall.fish
View file

@ -68,7 +68,7 @@ function fisher_uninstall -d "Uninstall plugins"
debug "Uninstall %s" "$name" debug "Uninstall %s" "$name"
if not contains -- $name (fisher_list $fisher_file) if not contains -- $name (fisher_list --enabled)
if test -z "$option" if test -z "$option"
set skipped $skipped $name set skipped $skipped $name
continue continue

210
functions/fisher_update.fish
View file

@ -1,28 +1,22 @@
function fisher_update -d "Update plugins" function fisher_update -d "Update plugins"
set -l plugins set -l items
set -l option self
set -l stdout /dev/stdout set -l stdout /dev/stdout
set -l stderr /dev/stderr set -l stderr /dev/stderr
set -l indicator "▸"
set -l color (set_color $fish_color_match)
set -l color_normal (set_color normal)
getopts $argv | while read -l 1 2 getopts $argv | while read -l 1 2
switch "$1" switch "$1"
case _ case _
set option set items $items $2
if test "$2" != -
set plugins $plugins $2
end
case a all
set option all
case q quiet case q quiet
set stdout /dev/null set stdout /dev/null
set stderr /dev/null set stderr /dev/null
case h case h
printf "Usage: fisher update [<plugins>] [--all] [--quiet] [--help]\n\n" printf "Usage: fisher update [<plugins>] [--quiet] [--help]\n\n"
printf " -a --all Update everything\n"
printf " -q --quiet Enable quiet mode\n" printf " -q --quiet Enable quiet mode\n"
printf " -h --help Show usage help\n" printf " -h --help Show usage help\n"
return return
@ -34,108 +28,110 @@ function fisher_update -d "Update plugins"
end end
end end
set -l indicator "▸" if set -l index (contains -i -- - $items)
set -e items[$index]
set -l IFS \t
switch "$option" __fisher_file | while read -l item
case all set items $items $item
fisher_update (fisher_list --enabled) end
fisher_update
case self else if test -z "$items"
set -l time (date +%s) set -l time (date +%s)
printf "$indicator Updating Fisherman\n" > $stderr printf "$indicator Updating Fisherman\n" > $stderr
debug "Update %s" $fisher_cache/.index
debug "Update %s" $fisher_home
debug "Update %s" $fisher_index if not spin "__fisher_index_update 0" --error=$stderr -f " $color@$color_normal\r"
debug "Update %s" $fisher_home debug "Update Index fail"
end
if not spin "__fisher_index_update 0" --error=$stderr -f " @\r" if not spin "__fisher_path_update $fisher_home" --error=$stderr -f " $color@$color_normal\r"
debug "Update Index fail" debug "Update Fisherman fail"
end
if not spin "__fisher_path_update $fisher_home" --error=$stderr -f " @\r" printf "fisher: I couldn't update Fisherman.\n\n" > $stderr
debug "Update Fisherman fail" return 1
end
debug "Update Fisherman ok"
printf "fisher: Sorry, but I couldn't update Fisherman.\n\n" > $stderr printf "Aye! Fisherman %s updated (%0.fs)\n" (
return 1 cat $fisher_home/VERSION) (math (date +%s) - $time) > $stderr
end
debug "Update Fisherman ok" set items (fisher_list --enabled)
printf "Aye! Fisherman up to date with version %s (%0.fs)\n" (
cat $fisher_home/VERSION) (math (date +%s) - $time) > $stderr
case \*
set -l time (date +%s)
set -l count 0
set -l index 1
set -l total (count $plugins)
set -l skipped
set -l IFS \t
if set -q plugins[1]
printf "%s\n" $plugins
else
__fisher_file
end | while read -l item path
debug "Validate %s" $item
if not set item (__fisher_plugin_validate $item)
debug "Validate fail %s" $item
printf "fisher: '%s' is not a valid name, path or URL.\n" $item > $stderr
continue
end
debug "Validate ok %s" $item
if not set path (__fisher_path_from_plugin $item)
printf "fisher: '%s' not found.\n" $item > $stderr
continue
end
set -l name (printf "%s\n" $path | __fisher_name)
printf "$indicator Updating " > $stderr
switch $total
case 0 1
printf "%s\n" $name > $stderr
case \*
printf "(%s of %s) %s\n" $index $total $name > $stderr
set index (math $index + 1)
end
if test ! -L $path
debug "Update start %s" "$name"
if not spin "__fisher_path_update $path" --error=$stderr -f " @\r"
debug "Update fail %s" "$path"
continue
end
end
debug "Update ok %s" "$name"
if __fisher_plugin_can_enable "$name" "$path"
debug "Enable %s" "$name"
fisher_install --quiet --force -- $name
end
set count (math $count + 1)
end
set time (math (date +%s) - $time)
if test $count -le 0
printf "No plugins were updated.\n" > $stdout
return 1
end
printf "%d plugin/s updated in %0.fs\n" $count $time > $stdout
end end
for item in $items
debug "Validate %s" $item
if not set item (__fisher_plugin_validate $item)
debug "Validate fail %s" $item
printf "fisher: '%s' is not a valid name, path or URL.\n" $item > $stderr
continue
end
set -l path (__fisher_path_from_plugin $item)
if test -z "$path"
printf "fisher: Plugin '%s' is not installed.\n" $item > $stderr
continue
end
debug "Validate ok %s" $item
set plugins $plugins $path
end
set -l time (date +%s)
set -l total (count $plugins)
set -U fisher_updated_plugins
printf "Updating plugins...\n" $name > $stderr
for path in $plugins
set -l name (printf "%s\n" $path | __fisher_name)
if test ! -L $path
debug "Update start %s" "$name"
fish -ic "
spin '
if __fisher_path_update $path
set fisher_updated_plugins \$fisher_updated_plugins $name
printf \"%s\n\" \"$indicator $name\"
end
' -f \" $color@$color_normal\r\"
" &
end
end
while jobs | grep . -q
end
for plugin in $fisher_updated_plugins
set -l path (__fisher_path_from_plugin)
if __fisher_plugin_can_enable "$plugin" "$path"
debug "Enable %s" "$plugin"
__fisher_plugin_enable "$plugin" "$path"
end
end
set time (math (date +%s) - $time)
if test -z "$fisher_updated_plugins"
printf "No plugins were updated.\n" > $stdout
set -e fisher_updated_plugins
return 1
end
printf "%d plugin/s updated in %0.fs\n" (count $fisher_updated_plugins) $time > $stdout
set -e fisher_updated_plugins
debug "Reset completions and key bindings start"
__fisher_complete_reset
__fisher_key_bindings_reset
debug "Reset completions and key bindings ok"
end end

2
functions/spin.fish
View file

@ -1,3 +1,3 @@
function spin -d "Run fisher install spin to update this function." -a commands function spin -a commands
fish -c "$commands" ^ /dev/null fish -c "$commands" ^ /dev/null
end end

409
man/man1/fisher.1
View file

@ -54,86 +54,117 @@ Show version information\. Fisherman follows Semantic Versioning and uses Git an
Show usage help\. Show usage help\.
. .
.SH "EXAMPLES" .SH "EXAMPLES"
.
.IP "\(bu" 4
Install plugins\. Install plugins\.
. .
.IP "" 0
.
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher install fishtape shark get fisher i fishtape shark get bobthefish
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Install Oh My Fish! plugins\.
.
.IP "" 0
.
.IP "" 4
.
.nf
fisher i omf/plugin\-{percol,jump,fasd}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install a plugin from a local directory\. Install a plugin from a local directory\.
. .
.IP "" 4
.
.nf
fisher install \./path/to/plugin
.
.fi
.
.IP "" 0 .IP "" 0
. .
.P
Install a plugin from a URL\.
.
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher install owner/repo fisher i \./path/to/plugin
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Install a plugin from a Gist URL\. Install a plugin from various URLs\.
.
.IP "" 0
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher install gist\.github\.com/owner/1f40e1c6e0551b2666b2 fisher i https://github\.com/some/plugin another/plugin bb:one/more
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Update Fisherman\. Install a plugin from a Gist\.
.
.IP "" 0
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher update fisher i gist\.github\.com/owner/1f40e1c6e0551b2666b2
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Update everything\.
.
.IP "" 0
.
.IP "" 4
.
.nf
fisher u
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Update plugins\. Update plugins\.
. .
.IP "" 0
.
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher update shark get fisher u shark get
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Uninstall plugins\. Uninstall plugins\.
. .
.IP "" 0
.
.IP "" 4 .IP "" 4
. .
.nf .nf
@ -144,27 +175,16 @@ fisher uninstall fishtape debug
. .
.IP "" 0 .IP "" 0
. .
.P .IP "\(bu" 4
Uninstall plugins and remove them from the cache\. Get help\.
.
.IP "" 4
.
.nf
fisher uninstall fishtape debug \-f
.
.fi
. .
.IP "" 0 .IP "" 0
. .
.P
Show all the documentation\.
.
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher help \-\-all fisher h
. .
.fi .fi
. .
@ -215,23 +235,26 @@ fisher search
.IP "" 0 .IP "" 0
. .
.P .P
Get detailed information about a plugin\. Query the index using regular expressions\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher search shellder fisher search \-\-name~/git\-is/
> shellder by simnalamburt git\-is\-dirty Test if there are changes not staged for commit
Powerline prompt optimized for speed git\-is\-empty Test if a repository is empty
github\.com/simnalamburt/shellder git\-is\-repo Test if the current directory is a Git repo
git\-is\-staged Test if there are changes staged for commit
git\-is\-stashed Test if there are changes in the stash
git\-is\-touched Test if there are changes in the working tree
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
Search plugins using tags\. Search using tags\.
. .
.IP "" 4 .IP "" 4
. .
@ -239,11 +262,14 @@ Search plugins using tags\.
fisher search \-\-tag={git,test} fisher search \-\-tag={git,test}
\.\.\. \.\.\.
* fishtape TAP producing test runner * fishtape TAP producing test runner
git\-branch\-name Get the name of the current Git branch 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\-dirty Test if there are changes not staged for commit
git\-is\-empty Test if a repository is empty
git\-is\-repo Test if the current directory is a Git repo
git\-is\-staged Test if there are changes staged for commit
git\-is\-stashed Test if there are changes in the stash git\-is\-stashed Test if there are changes in the stash
git\-is\-touched Test if there are changes in the working tree
\.\.\. \.\.\.
. .
.fi .fi
@ -253,35 +279,35 @@ fisher search \-\-tag={git,test}
.P .P
The legend consists of: The legend consists of:
. .
.P .IP "\(bu" 4
\fB*\fR The plugin is currently enabled \fB*\fR The plugin is enabled
. .
.br .IP "\(bu" 4
\fB>\fR The plugin is a prompt \fB>\fR The plugin is a prompt
. .
.br .IP "\(bu" 4
\fB@\fR The plugin is a symbolic link \fB@\fR The plugin is a symbolic link
. .
.br .IP "" 0
. .
.SH "PLUMBING" .SH "PLUMBING"
Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\. Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\.
. .
.P .P
Update all the plugins in the cache\. Update plugins installed as symbolic links\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher list | fisher update \- fisher list \-\-link | fisher update \-
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
Enable all the plugins that are currently disabled\. Enable all the plugins currently disabled\.
. .
.IP "" 4 .IP "" 4
. .
@ -307,10 +333,12 @@ fisher list | fisher uninstall \-\-force
.IP "" 0 .IP "" 0
. .
.SH "DOTFILES" .SH "DOTFILES"
When you install a plugin, Fisherman updates a file known as \fIfishfile\fR to track what plugins are currently enabled\. When you install a plugin, Fisherman updates the \fIfishfile\fR to track what plugins are currently enabled\.
. .
.P .IP "\(bu" 4
To customize its location: Customize the location of the fishfile\.
.
.IP "" 0
. .
.IP "" 4 .IP "" 4
. .
@ -355,10 +383,7 @@ $fisher_config
The index is a plain text database that lists Fisherman official plugins\. The index is a plain text database that lists Fisherman official plugins\.
. .
.P .P
The index is a list of records, each consisting of the following fields: \fIname\fR, \fIurl\fR, \fIinfo\fR, one or more \fItags\fR and \fIauthor\fR\. The index lists records, each consisting the fields: \fIname\fR, \fIurl\fR, \fIinfo\fR, one or more \fItags\fR and \fIauthor\fR\.
.
.P
Fields are separated by a new line \fB\en\fR\. Tags are separated by one \fIspace\fR\.
. .
.IP "" 4 .IP "" 4
. .
@ -375,65 +400,31 @@ jethrokuan
.IP "" 0 .IP "" 0
. .
.P .P
If you have a plugin to submit to the index, use the \fIsubmit\fR plugin\. If you have a plugin you would like to submit to the index, use the submit plugin\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher install submit fisher install submit
fisher submit my_plugin fisher submit my_plugin description tags url
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
Otherwise, submit the plugin manually by creating a pull request in the index repository \fIhttps://github\.com/fisherman/fisher\-index\fR\. Or, submit the plugin manually by creating a pull request in the index \fIhttps://github\.com/fisherman/fisher\-index\fR repository\.
.
.IP "" 4
.
.nf
git clone https://github\.com/fisherman/fisher\-index
cd index
echo "$name\en$url\en$info\en$tags\en$author\en\en" >> index
git push origin master
.
.fi
.
.IP "" 0
.
.SH "FISHFILE"
Fisherman keeps track of a special file known as \fIfishfile\fR to know what plugins are currently enabled\.
.
.IP "" 4
.
.nf
# My Fishfile
gitio
fishtape
shark
get
shellder
.
.fi
.
.IP "" 0
.
.P
This file is automatically updated as you install and uninstall plugins\.
. .
.SH "VARIABLES" .SH "VARIABLES"
. .
.TP .TP
$fisher_home \fB$fisher_home\fR
The home directory\. If you installed Fisherman using the recommended method \fBcurl \-sL install\.fisherman\.sh | fish\fR, the location ought to be \fIXDG_DATA_HOME/fisherman\fR\. If you clone Fisherman and run make yourself, the current working directory is used by default\. The home directory\. If you installed Fisherman using the recommended method, the location ought to be \fIXDG_DATA_HOME/fisherman\fR\.
. .
.TP .TP
$fisher_config $fisher_config
The configuration directory\. This is default location of the \fIfishfile\fR, \fIkey_bindings\.fish\fR, \fIcache\fR, \fIfunctions\fR, \fIcompletions\fR and \fIconf\.d\fR directories\. The default location is \fIXDG_CONFIG_HOME/fisherman\fR\. The configuration directory\. This is default location of your \fIfishfile\fR, \fIkey_bindings\.fish\fR, \fIcache\fR, \fIfunctions\fR, \fIcompletions\fR and \fIconf\.d\fR directories\. \fIXDG_CONFIG_HOME/fisherman\fR by default\.
. .
.TP .TP
$fisher_file $fisher_file
@ -468,10 +459,7 @@ See the documentation of new for details\.
Utilities are plugins that define one or more functions\. Utilities are plugins that define one or more functions\.
. .
.P .P
This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\. Below is a plugin based in ngerakines/commitment \fIhttps://github/ngerakines/commitment\fR random commit message generator\.
.
.P
Create a directory and initialize a Git repository\.
. .
.IP "" 4 .IP "" 4
. .
@ -479,19 +467,6 @@ Create a directory and initialize a Git repository\.
mkdir wtc mkdir wtc
cd wtc cd wtc
git init
git remote add origin https://github\.com/<you>/wtc
.
.fi
.
.IP "" 0
.
.P
Add the wtc function\.
.
.IP "" 4
.
.nf
function wtc \-d "Generate a random commit message" function wtc \-d "Generate a random commit message"
switch "$argv" switch "$argv"
@ -503,19 +478,17 @@ function wtc \-d "Generate a random commit message"
curl \-s whatthecommit\.com/index\.txt curl \-s whatthecommit\.com/index\.txt
end end
functions wtc > wtc\.fish functions wtc > wtc\.fish
fisher install \.
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P
Install the plugin\.
.
.IP "" 4 .IP "" 4
. .
.nf .nf
fisher install \.
wtc wtc
(\e /) (\e /)
(O\.o) (O\.o)
@ -526,21 +499,6 @@ wtc
.IP "" 0 .IP "" 0
. .
.P .P
Commit changes and push to your remote origin when you are done\.
.
.IP "" 4
.
.nf
git add \-\-all
git commit \-m "What the commit?"
git push origin master
.
.fi
.
.IP "" 0
.
.P
To submit wtc to the official index\. To submit wtc to the official index\.
. .
.IP "" 4 .IP "" 4
@ -567,101 +525,24 @@ fisher install wtc
.IP "" 0 .IP "" 0
. .
.P .P
Create a completions directory and add a completions file\.
.
.IP "" 4
.
.nf
mkdir completions
$EDITOR completions/wtc\.fish
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf
complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help"
.
.fi
.
.IP "" 0
.
.P
Or 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
$EDITOR man/man1/wtc\.1
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf
\.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
.
.fi
.
.IP "" 0
.
.P
A plugin can list dependencies to other plugins using a \fIfishfile\fR\. A plugin can list dependencies to other plugins using a \fIfishfile\fR\.
. .
.P .P
Create a new file in the root of your project and add the name or URL of your dependencies\. Create a \fIfishfile\fR in the root of your project and add the name or URL of your dependencies\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
cat > fishfile
my_plugin my_plugin
https://github\.com/owner/another_plugin https://github\.com/owner/another_plugin
^D
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "PROMPTS" .SS "PROMPTS"
Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors\. Prompts, or themes, are plugins that modify the appearance of the shell prompt and colors\.
. .
.P .P
Create a \fBfish_prompt\fR function\. Create a \fBfish_prompt\fR function\.
@ -703,8 +584,10 @@ Save the functions to a directory and install the prompt as a plugin\.
mkdir my_prompt mkdir my_prompt
cd my_prompt cd my_prompt
functions fish_prompt > fish_prompt\.fish functions fish_prompt > fish_prompt\.fish
functions fish_right_prompt > fish_right_prompt\.fish functions fish_right_prompt > fish_right_prompt\.fish
fisher install \. fisher install \.
. .
.fi .fi
@ -719,30 +602,32 @@ Customize the colors fish uses for syntax highlighting\.
.nf .nf
function set_color_custom function set_color_custom
set \-U fish_color_normal #\.\.\. # set \-U fish_color_normal
set \-U fish_color_command #\.\.\. # set \-U fish_color_command
set \-U fish_color_param #\.\.\. # set \-U fish_color_param
set \-U fish_color_redirection #\.\.\. # set \-U fish_color_redirection
set \-U fish_color_comment #\.\.\. # set \-U fish_color_comment
set \-U fish_color_error #\.\.\. # set \-U fish_color_error
set \-U fish_color_escape #\.\.\. # set \-U fish_color_escape
set \-U fish_color_operator #\.\.\. # set \-U fish_color_operator
set \-U fish_color_end #\.\.\. # set \-U fish_color_end
set \-U fish_color_quote #\.\.\. # set \-U fish_color_quote
set \-U fish_color_autosuggestion #\.\.\. # set \-U fish_color_autosuggestion
set \-U fish_color_valid_path #\.\.\. # set \-U fish_color_valid_path
set \-U fish_color_cwd #\.\.\. # set \-U fish_color_cwd
set \-U fish_color_cwd_root #\.\.\. # set \-U fish_color_cwd_root
set \-U fish_color_match #\.\.\. # set \-U fish_color_match
set \-U fish_color_search_match #\.\.\. # set \-U fish_color_search_match
set \-U fish_color_selection #\.\.\. # set \-U fish_color_selection
set \-U fish_pager_color_prefix #\.\.\. # set \-U fish_pager_color_prefix
set \-U fish_pager_color_completion #\.\.\. # set \-U fish_pager_color_completion
set \-U fish_pager_color_description #\.\.\. # set \-U fish_pager_color_description
set \-U fish_pager_color_progress #\.\.\. # set \-U fish_pager_color_progress
set \-U fish_color_history_current #\.\.\. # set \-U fish_color_history_current
end end
functions set_color_custom > set_color_custom\.fish functions set_color_custom > set_color_custom\.fish
fisher update \. fisher update \.
. .
.fi .fi
@ -794,40 +679,11 @@ fisher install fisher_time
. .
.IP "" 0 .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" .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\. Snippets are plugins that run code at the start of the shell\. Snippets must be placed inside a sub directory named conf\.d\.
. .
.P .P
The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds\. The following example implements a fish_postexec hook to display the duration of the last command in milliseconds\.
. .
.IP "" 4 .IP "" 4
. .
@ -835,11 +691,20 @@ The following example implements the fish_postexec hook to display the runtime o
mkdir \-p runtime/conf\.d mkdir \-p runtime/conf\.d
cd runtime cd runtime
cat > conf\.d/fish_postexec\.fish $EDITOR conf\.d/fish_postexec\.fish
.
.fi
.
.IP "" 0
.
.IP "" 4
.
.nf
function fish_postexec \-\-on\-event fish_postexec function fish_postexec \-\-on\-event fish_postexec
printf "%sms\en" $CMD_DURATION > /dev/stderr printf "%sms\en" $CMD_DURATION > /dev/stderr
end end
^D
fisher install \./postexec fisher install \./postexec
. .
.fi .fi
@ -851,9 +716,3 @@ Fisherman was created by Jorge Bucaran :: @bucaran :: \fIj@bucaran\.me\fR\.
. .
.P .P
See THANKS\.md file for a complete list of contributors\. See THANKS\.md file for a complete list of contributors\.
.
.SH "SEE ALSO"
fisher help tutorial
.
.br

286
man/man1/fisher.md
View file

@ -35,58 +35,58 @@ fisher help <command>
## EXAMPLES ## EXAMPLES
Install plugins. * Install plugins.
```
fisher i fishtape shark get bobthefish
```
* Install Oh My Fish! plugins.
```fish ```fish
fisher install fishtape shark get fisher i omf/plugin-{percol,jump,fasd}
``` ```
Install a plugin from a local directory. * Install a plugin from a local directory.
```fish ```fish
fisher install ./path/to/plugin fisher i ./path/to/plugin
``` ```
Install a plugin from a URL. * Install a plugin from various URLs.
```fish ```fish
fisher install owner/repo fisher i https://github.com/some/plugin another/plugin bb:one/more
``` ```
Install a plugin from a Gist URL. * Install a plugin from a Gist.
```fish ```fish
fisher install gist.github.com/owner/1f40e1c6e0551b2666b2 fisher i gist.github.com/owner/1f40e1c6e0551b2666b2
``` ```
Update Fisherman. * Update everything.
```fish
fisher update
```
Update plugins.
``` ```
fisher update shark get fisher u
``` ```
Uninstall plugins. * Update plugins.
```
fisher u shark get
```
* Uninstall plugins.
``` ```
fisher uninstall fishtape debug fisher uninstall fishtape debug
``` ```
Uninstall plugins and remove them from the cache. * Get help.
```
fisher uninstall fishtape debug -f
```
Show all the documentation.
```fish ```fish
fisher help --all fisher h
``` ```
## LIST AND SEARCH ## LIST AND SEARCH
@ -120,45 +120,51 @@ fisher search
... ...
``` ```
Get detailed information about a plugin. Query the index using regular expressions.
``` ```
fisher search shellder fisher search --name~/git-is/
> shellder by simnalamburt git-is-dirty Test if there are changes not staged for commit
Powerline prompt optimized for speed git-is-empty Test if a repository is empty
github.com/simnalamburt/shellder git-is-repo Test if the current directory is a Git repo
git-is-staged Test if there are changes staged for commit
git-is-stashed Test if there are changes in the stash
git-is-touched Test if there are changes in the working tree
``` ```
Search plugins using tags. Search using tags.
``` ```
fisher search --tag={git,test} fisher search --tag={git,test}
... ...
* fishtape TAP producing test runner * fishtape TAP producing test runner
git-branch-name Get the name of the current Git branch 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-dirty Test if there are changes not staged for commit
git-is-empty Test if a repository is empty
git-is-repo Test if the current directory is a Git repo
git-is-staged Test if there are changes staged for commit
git-is-stashed Test if there are changes in the stash git-is-stashed Test if there are changes in the stash
git-is-touched Test if there are changes in the working tree
... ...
``` ```
The legend consists of: The legend consists of:
`*` The plugin is currently enabled<br> * `*` The plugin is enabled
`>` The plugin is a prompt<br> * `>` The plugin is a prompt
`@` The plugin is a symbolic link<br> * `@` The plugin is a symbolic link
## PLUMBING ## PLUMBING
Fisherman commands are pipe aware. Plumb one with another to create complex functionality. Fisherman commands are pipe aware. Plumb one with another to create complex functionality.
Update all the plugins in the cache. Update plugins installed as symbolic links.
```fish ```fish
fisher list | fisher update - fisher list --link | fisher update -
``` ```
Enable all the plugins that are currently disabled. Enable all the plugins currently disabled.
```fish ```fish
fisher list --disabled | fisher install fisher list --disabled | fisher install
@ -172,9 +178,9 @@ fisher list | fisher uninstall --force
## DOTFILES ## DOTFILES
When you install a plugin, Fisherman updates a file known as *fishfile* to track what plugins are currently enabled. When you install a plugin, Fisherman updates the *fishfile* to track what plugins are currently enabled.
To customize its location: * Customize the location of the fishfile.
```fish ```fish
set -g fisher_file ~/.dotfiles/fishfile set -g fisher_file ~/.dotfiles/fishfile
@ -207,9 +213,7 @@ $fisher_config
The index is a plain text database that lists Fisherman official plugins. The index is a plain text database that lists Fisherman official plugins.
The index is a list of records, each consisting of the following fields: *name*, *url*, *info*, one or more *tags* and *author*. The index lists records, each consisting the fields: *name*, *url*, *info*, one or more *tags* and *author*.
Fields are separated by a new line `\n`. Tags are separated by one *space*.
``` ```
z z
@ -219,44 +223,22 @@ z search cd jump
jethrokuan jethrokuan
``` ```
If you have a plugin to submit to the index, use the *submit* plugin. If you have a plugin you would like to submit to the index, use the submit plugin.
``` ```
fisher install submit fisher install submit
fisher submit my_plugin fisher submit my_plugin description tags url
``` ```
Otherwise, submit the plugin manually by creating a pull request in the index repository *https://github.com/fisherman/fisher-index*. Or, submit the plugin manually by creating a pull request in the [index](https://github.com/fisherman/fisher-index) repository.
```
git clone https://github.com/fisherman/fisher-index
cd index
echo "$name\n$url\n$info\n$tags\n$author\n\n" >> index
git push origin master
```
## FISHFILE
Fisherman keeps track of a special file known as *fishfile* to know what plugins are currently enabled.
```
# My Fishfile
gitio
fishtape
shark
get
shellder
```
This file is automatically updated as you install and uninstall plugins.
## VARIABLES ## VARIABLES
* $fisher_home: * $fisher_home:
The home directory. If you installed Fisherman using the recommended method `curl -sL install.fisherman.sh | fish`, the location ought to be *XDG_DATA_HOME/fisherman*. If you clone Fisherman and run make yourself, the current working directory is used by default. The home directory. If you installed Fisherman using the recommended method, the location ought to be *XDG_DATA_HOME/fisherman*.
* $fisher_config: * $fisher_config:
The configuration directory. This is default location of the *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. The default location is *XDG_CONFIG_HOME/fisherman*. The configuration directory. This is default location of your *fishfile*, *key_bindings.fish*, *cache*, *functions*, *completions* and *conf.d* directories. *XDG_CONFIG_HOME/fisherman* by default.
* $fisher_file: * $fisher_file:
See FISHFILE above. See FISHFILE above.
@ -283,20 +265,12 @@ See the documentation of new for details.
Utilities are plugins that define one or more functions. Utilities are plugins that define one or more functions.
This example walks you through creating *wtc*, a plugin based in *github/ngerakines/commitment* random commit message generator. Below is a plugin based in [ngerakines/commitment](https://github/ngerakines/commitment) random commit message generator.
Create a directory and initialize a Git repository.
```fish ```fish
mkdir wtc mkdir wtc
cd 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" function wtc -d "Generate a random commit message"
switch "$argv" switch "$argv"
case -h --help case -h --help
@ -307,26 +281,16 @@ function wtc -d "Generate a random commit message"
curl -s whatthecommit.com/index.txt curl -s whatthecommit.com/index.txt
end end
functions wtc > wtc.fish functions wtc > wtc.fish
```
Install the plugin.
```fish
fisher install . fisher install .
```
```
wtc wtc
(\ /) (\ /)
(O.o) (O.o)
(> <) Bunny approves these changes. (> <) 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 #### SUBMIT
To submit wtc to the official index. To submit wtc to the official index.
@ -341,66 +305,20 @@ This will create a PR in the Fisherman index repository. Once the PR is approved
fisher install wtc fisher install wtc
``` ```
#### COMPLETIONS
Create a completions directory and add a completions file.
```fish
mkdir completions
$EDITOR completions/wtc.fish
```
```fish
complete --command wtc --short h --long help --description "Show usage help"
```
Or use `__fisher_complete` to create completions from wtc usage output.
```
wtc --help | __fisher_complete wtc
```
#### DOCS
Create a man/man1 directory and add a man(1) page for wtc.
There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).
To create a man page manually.
```
mkdir -p man/man1
$EDITOR 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
```
#### DEPENDENCIES #### DEPENDENCIES
A plugin can list dependencies to other plugins using a *fishfile*. 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 dependencies. Create a *fishfile* in the root of your project and add the name or URL of your dependencies.
```fish ```
cat > fishfile
my_plugin my_plugin
https://github.com/owner/another_plugin https://github.com/owner/another_plugin
^D
``` ```
### PROMPTS ### PROMPTS
Prompts, also known as themes, are plugins that modify the appearance of the shell prompt and modify fish syntax colors. Prompts, or themes, are plugins that modify the appearance of the shell prompt and colors.
Create a `fish_prompt` function. Create a `fish_prompt` function.
@ -408,9 +326,10 @@ Create a `fish_prompt` function.
function fish_prompt function fish_prompt
printf "%s (%s) >> " (prompt_pwd) Fisherman printf "%s (%s) >> " (prompt_pwd) Fisherman
end end
```
```
~ (Fisherman) >> type here ~ (Fisherman) >> type here
``` ```
To add a right prompt, create a `fish_right_prompt` function. To add a right prompt, create a `fish_right_prompt` function.
```fish ```fish
@ -424,8 +343,10 @@ Save the functions to a directory and install the prompt as a plugin.
```fish ```fish
mkdir my_prompt mkdir my_prompt
cd my_prompt cd my_prompt
functions fish_prompt > fish_prompt.fish functions fish_prompt > fish_prompt.fish
functions fish_right_prompt > fish_right_prompt.fish functions fish_right_prompt > fish_right_prompt.fish
fisher install . fisher install .
``` ```
@ -433,30 +354,32 @@ Customize the colors fish uses for syntax highlighting.
```fish ```fish
function set_color_custom function set_color_custom
set -U fish_color_normal #... # set -U fish_color_normal
set -U fish_color_command #... # set -U fish_color_command
set -U fish_color_param #... # set -U fish_color_param
set -U fish_color_redirection #... # set -U fish_color_redirection
set -U fish_color_comment #... # set -U fish_color_comment
set -U fish_color_error #... # set -U fish_color_error
set -U fish_color_escape #... # set -U fish_color_escape
set -U fish_color_operator #... # set -U fish_color_operator
set -U fish_color_end #... # set -U fish_color_end
set -U fish_color_quote #... # set -U fish_color_quote
set -U fish_color_autosuggestion #... # set -U fish_color_autosuggestion
set -U fish_color_valid_path #... # set -U fish_color_valid_path
set -U fish_color_cwd #... # set -U fish_color_cwd
set -U fish_color_cwd_root #... # set -U fish_color_cwd_root
set -U fish_color_match #... # set -U fish_color_match
set -U fish_color_search_match #... # set -U fish_color_search_match
set -U fish_color_selection #... # set -U fish_color_selection
set -U fish_pager_color_prefix #... # set -U fish_pager_color_prefix
set -U fish_pager_color_completion #... # set -U fish_pager_color_completion
set -U fish_pager_color_description #... # set -U fish_pager_color_description
set -U fish_pager_color_progress #... # set -U fish_pager_color_progress
set -U fish_color_history_current #... # set -U fish_color_history_current
end end
functions set_color_custom > set_color_custom.fish functions set_color_custom > set_color_custom.fish
fisher update . fisher update .
``` ```
@ -481,46 +404,27 @@ It's 6:30
Make it a plugin Make it a plugin
```fish ```fish
fisher install fisher_time 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
Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d. 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. The following example implements a fish_postexec hook to display the duration of the last command in milliseconds.
```fish ```fish
mkdir -p runtime/conf.d mkdir -p runtime/conf.d
cd runtime cd runtime
cat > conf.d/fish_postexec.fish $EDITOR conf.d/fish_postexec.fish
```
```fish
function fish_postexec --on-event fish_postexec function fish_postexec --on-event fish_postexec
printf "%sms\n" $CMD_DURATION > /dev/stderr printf "%sms\n" $CMD_DURATION > /dev/stderr
end end
^D
fisher install ./postexec fisher install ./postexec
``` ```
@ -529,7 +433,3 @@ fisher install ./postexec
Fisherman was created by Jorge Bucaran :: @bucaran :: *j@bucaran.me*. Fisherman was created by Jorge Bucaran :: @bucaran :: *j@bucaran.me*.
See THANKS.md file for a complete list of contributors. See THANKS.md file for a complete list of contributors.
## SEE ALSO
fisher help tutorial<br>

31
test/fixtures/help/usage.txt vendored
View file

@ -1,31 +0,0 @@
Usage: fisher update [<plugins>] [--all] [--quiet] [--help]
-a --all Update everything
-q --quiet Enable quiet mode
-h --help Show usage help
Usage: fisher uninstall [<plugins>] [--force] [--quiet] [--help]
-f --force Delete copy from the cache
-q --quiet Enable quiet mode
-h --help Show usage help
Usage: fisher search [<plugins>] [--long] [--full] [--no-color]
[--quiet] [--help]
--long Display results in long format
--full Display results in full format
-C --no-color Turn off color display
-q --quiet Enable quiet mode
-h --help Show usage help
Usage: fisher list [<file>] [--enabled] [--disabled] [--bare] [--link]
-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
Usage: fisher install [<plugins>] [--force] [--quiet] [--help]
-f --force Reinstall given plugin/s
-q --quiet Enable quiet mode
-h --help Show usage help
Usage: fisher help [<keyword>]

6
test/help.fish
View file

@ -26,9 +26,3 @@ for i in $sections
(fisher help foo | xargs) = foo (fisher help foo | xargs) = foo
end end
end end
test "$TESTNAME - Display usage help for every command"
(cat $DIRNAME/fixtures/help/usage.txt) = (
__fisher_help_commands | cut -f1 -d \; | fisher help --usage
)
end

6
test/install.fish
View file

@ -5,9 +5,9 @@ function -S setup
source $DIRNAME/helpers/config-mock.fish $path/config source $DIRNAME/helpers/config-mock.fish $path/config
fisher install foo bar --quiet fisher install foo bar --quiet --no-color
fisher install https://github.com/foobar --quiet fisher install https://github.com/foobar --quiet --no-color
fisher install $DIRNAME/fixtures/plugins/baz --quiet fisher install $DIRNAME/fixtures/plugins/baz --quiet --no-color
end end
function -S teardown function -S teardown

2
test/list-fishfile.fish
View file

@ -4,6 +4,6 @@ set -l plugins foo bar baz quux hoge foobar fred thud chomp gisty mof
test "$TESTNAME - Parse fishfile and retrieve plugin names with fisher list fishfile" test "$TESTNAME - Parse fishfile and retrieve plugin names with fisher list fishfile"
$plugins = ( $plugins = (
fisher list $manifest/fishfile fisher list - < $manifest/fishfile
) )
end end

31
test/list.fish
View file

@ -35,7 +35,7 @@ test "$TESTNAME - Append * to active plugins"
end end
test "$TESTNAME - Add one space indentation to disabled plugins to align with > and *" test "$TESTNAME - Add one space indentation to disabled plugins to align with > and *"
(fisher list | sed '/^[\*>].*/d') = " norf" (fisher list | sed '/^[\*>].*/d') = " norf"
end end
test "$TESTNAME - Do not add indentation when no plugins are enabled" test "$TESTNAME - Do not add indentation when no plugins are enabled"
@ -46,25 +46,6 @@ test "$TESTNAME - Do not add indentation when no plugins are enabled"
) )
end end
test "$TESTNAME - Wrap fisher list=bare with __fisher_cache_list"
(fisher list --bare) = (__fisher_cache_list)
end
# test "$TESTNAME - Get URL from path (__fisher_url_from_path) with fisher list=url"
# (fisher list --url) = (
# for plugin in foo bar baz theme norf
# switch "$plugin"
# case theme
# echo $path/theme
# case norf
# echo $plugin@https://gist.github.com/$plugin
# case \*
# echo https://github.com/$plugin/$plugin
# end
# end
# )
# end
test "$TESTNAME - Show active / enabled plugins/prompts with fisher list=enabled" test "$TESTNAME - Show active / enabled plugins/prompts with fisher list=enabled"
foo bar baz theme = (fisher list --enabled) foo bar baz theme = (fisher list --enabled)
end end
@ -73,14 +54,6 @@ test "$TESTNAME - Show disabled/inactive plugins/prompts with fisher list=disabl
(fisher list --disabled) = norf (fisher list --disabled) = norf
end end
# test "$TESTNAME - Shadow fisher list=theme to fisher list=prompt"
# (fisher list=theme) = (fisher list=prompt)
# end
#
# test "$TESTNAME - Return the contents of \$fisher_prompt fisher list=theme|prompt"
# (fisher list=prompt) = theme
# end
test "$TESTNAME - Parse a fishfile and display plugins with fisher list=<file>" test "$TESTNAME - Parse a fishfile and display plugins with fisher list=<file>"
foo bar baz theme = (fisher list $fisher_file) foo bar baz theme = (fisher list - < $fisher_file)
end end

3
test/path-update.fish
View file

@ -1,3 +0,0 @@
test "$TESTNAME - Update Git repo at path"
-z ""
end

2
test/uninstall.fish
View file

@ -5,7 +5,7 @@ function -S setup
source $DIRNAME/helpers/config-mock.fish $path/config source $DIRNAME/helpers/config-mock.fish $path/config
fisher install foo bar foobar --quiet fisher install foo bar foobar --quiet --no-color
fisher uninstall foo --quiet fisher uninstall foo --quiet
fisher uninstall foobar --quiet --force fisher uninstall foobar --quiet --force
end end

29
test/update.fish
View file

@ -1,29 +0,0 @@
set -l path $DIRNAME/.t-$TESTNAME-(random)
function -S setup
mkdir -p $path/config/cache
source $DIRNAME/helpers/config-mock.fish $path/config
function __fisher_path_update
echo "$argv[1]"
end
fisher install foo --quiet
fisher update foo > $path/foo --quiet
fisher update --quiet > $path/self
end
function -S teardown
rm -rf $path
source $DIRNAME/helpers/config-mock-teardown.fish
end
test "$TESTNAME - Update plugin path"
(cat $path/foo) = "$path/config/cache/foo"
end
test "$TESTNAME - Update Index and \$fisher_home"
(cat $path/self) = $fisher_home
end