Ahoy! Fisherman gets a super patch v0.3.1

This patch contains several amends for 0.3.0 and
other minor documentation corrections.  Major
documentation revision and rewrite.

fisher help shows fisher(1) by default now.

Fix a critical bug that was causing fisher uninstall
--force to remove not the symbolic link, but the
actual files. Closes #24

Rename orphan tag to custom for plugins installed
using a custom URL.

warning Remove fisher --link flag and create symbolic
links by default for local paths. The user does not
have to worry about symbolic links or whether the
copy is as symbolic link or not anymore. If the user
tries to install a local path, then the best thing
to do is to create a symbolic link. This also
eliminates the need to call update.

warning Remove fisher --cache and fisher --validate.
Now, that these options are separated into their own
function and they are intentionally private, there
is no need for them.

CHANGELOG.md

@@ -1,11 +1,28 @@
 # Change Log
 
+* [0.3.1](#031)
 * [0.3.0](#030)
 * [0.2.0](#020)
 * [0.1.0](#010)
 
 
-## [0.3.0][v030] - 2016-01-05
+## [0.3.0][v030] - 2016-01-08
+
+> This patch contains several amends for 0.3.0 and other minor documentation corrections.
+
+* Major documentation revision and rewrite.
+
+* `fisher help` shows `fisher(1)` by default now.
+
+* Fix a critical bug that was causing `fisher uninstall --force` to remove _not_ the symbolic link, but the actual files. Closes #24
+
+* Rename `orphan` tag to `custom` for plugins installed using a custom URL.
+
+* :warning: Remove `fisher --link` flag and create symbolic links by default for local paths. The user does not have to worry about symbolic links or whether the copy is as symbolic link or not anymore. If the user tries to install a local path, then the best thing to do is to create a symbolic link. This also eliminates the need to call update.
+
+* :warning: Remove `fisher --cache` and `fisher --validate`. Now, that these options are separated into their own function and they are intentionally private, there is no need for them.
+
+## [0.3.0][v030] - 2016-01-08
 
 > This release contains several breaking changes a few major improvements. The good news is that the API is starting to look more stable and very unlikely to change drastically again in the future.
 
@@ -65,7 +82,7 @@
 
 * Remove `fisher --cache=base` and make it return the base names of all directories in the path by default. To get the full path use printf `printf "$fisher_cache/%s" (fisher --list)`
 
-* Rename undocumented `fisher --translate` flag (again) to `fisher --cache`. This function reads the standard input for a name, URL or local path and calculates the plugin's path relative to the cache. For a name this is simple `$fisher_cache/<name>` for an URL, retrieve the remote URL of every repository until there is a match with the given URL and return the path in the cache of that repository. Finally, if the input is a
+* Rename undocumented `fisher --translate` flag (again) to `fisher --cache`. This function reads the standard input for a name, URL or local path and calculates the plugin's path relative to the cache. For a name this is simple `$fisher_cache/<name>` for an URL, retrieve the remote URL of every repository until there is a match with the given URL and return the path in the cache of that repository. Finally, if the input is a local path of the form `file:///` it will pass it as is.
 
 * Revert #3. The reason `getopts.fish` was in its own file originally is because @bucaran wanted a standalone, dependency free cli parser solution, arguably slightly faster than having Awk read `getopts.awk` for each use. The performance improvement is negligible at best, but `getopts` is also used by every single command and future commands and plugins are very likely to use it as well, so we might as well use the slightly faster version.
 
@@ -80,7 +97,7 @@
 
 * ~~Add `fisher --cache[=base]` option to retrieve contents in `$fisher_cache`, eliminating flaky usage of `find(1)`~~. Closes #11.
 
-* Fisherman now generates information about plugins installed via custom URLs. For the description, a shortened version of the URL is used. For the URL the full URL is used. For tags, the URL is fuzzily checked and tags such as _theme_, _plugin_, _config_ and _omf_ are added. The tag _orphan_ is added by default as well. Finally, the author is generated by retrieving the e-mail or username of the author of the first commit in the plugin's repository. Closes #9 and #14.
+* Fisherman now generates information about plugins installed via custom URLs. For the description, a shortened version of the URL is used. For the URL the full URL is used. For tags, the URL is fuzzily checked and tags such as _theme_, _plugin_, _config_ and _omf_ are added. The tag ~~_orphan_~~ **custom** is added by default as well. Finally, the author is generated by retrieving the e-mail or username of the author of the first commit in the plugin's repository. Closes #9 and #14.
 
 * ~~Change `--path-in-cache` to `--translate.` This function translates an name or supported URL/URL variation into a path inside `$fisher_cache`. This allows you to treat plugins installed via custom URLs almost like regular plugins if they are installed. Closes #8.~~
 

CODE_OF_CONDUCT.md

@@ -35,7 +35,7 @@ This Code of Conduct applies both within project spaces and in public spaces
 when an individual is representing the project or its community.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting a project maintainer at [Fisherman][email]. All
+reported by contacting a project maintainer at [hi@fisherman.sh](mailto:hi@fisherman.sh). All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. Maintainers are
 obligated to maintain confidentiality with regard to the reporter of an
@@ -50,6 +50,5 @@ version 1.3.0, available at
 
 <!-- Links -->
 
-[email]:    mailto:j@bucaran.me
 [version]:  http://contributor-covenant.org/version/1/3/0/
 [homepage]: http://contributor-covenant.org

CONTRIBUTING.md

@@ -1,12 +1,8 @@
 # Contributing to Fisherman
 
-You can start contributing right away:
+[![Wharf][wharf-badge]][wharf-link]
 
-* [Join][join] the community.
-* [Spread][tweet] the voice.
-* Report [bugs][bugs].
-
-If you are looking for other ways to help, peruse [open issues][issues]. If you are already working on something, feel free to send us a PR.
+If you are looking for ways to help, peruse the [open issues][issues]. If you are already working on something, feel free to send us a PR.
 
 ## Guidelines
 
@@ -19,23 +15,31 @@ If you are looking for other ways to help, peruse [open issues][issues]. If you
 * Follow the [seven rules][seven-rules] of a great git commit message.
 
 
-## Addons
+## Plugins
 
 Third-party plugins are essential for keeping this project exciting. To learn how to create your own plugins and other extensions see `fisher help plugins`.
 
 To browse the available content use `fisher search` or see the [Fisherman Index][fisher-index].
 
+:anchor:
+
+
 <!-- Links -->
 
-[org]:          https://github.com/fisherman
-[join]:         https://gitter.im/fisherman/wharf
-[bugs]:         https://github.com/fisherman/fisherman/issues
-[issues]:       https://github.com/fisherman/fisherman/issues?q=is%3Aopen+is%3Aissue
-[fishtape]:     https://github.com/fisherman/fishtape
-[fish-docs]:    http://fishshell.com/docs/current/index.html  
-[seven-rules]:  http://chris.beams.io/posts/git-commit/#seven-rules
+[org]: https://github.com/fisherman
+
+[bugs]: https://github.com/fisherman/fisherman/issues
+
+[issues]: https://github.com/fisherman/fisherman/issues?q=is%3Aopen+is%3Aissue
+
+[fishtape]: https://github.com/fisherman/fishtape
+
+[fish-docs]: http://fishshell.com/docs/current/index.html  
+
+[seven-rules]: http://chris.beams.io/posts/git-commit/#seven-rules
+
 [fisher-index]: https://github.com/fisherman/fisher-index
 
-[tweet]: https://twitter.com/intent/tweet?url=https%3A%2F%2Fgit.io%2Ffisher&via=jbucaran&text=Check+out+%23Fisherman+for+the+%23fishshell
+[wharf-link]: https://fisherman-wharf.herokuapp.com/
 
-:anchor:
+[wharf-badge]: https://img.shields.io/badge/wharf-join%20the%20chat-00cc99.svg?style=flat-square

Makefile

@@ -28,8 +28,8 @@ all: $(FISH_CONFIG) $(FISHER_CACHE) $(AUTHORS) $(DOCS)
 		echo "Downloading the index for the first time...";\
 		fish -c "fisher_update --index";\
 	fi
-	@$(call MSG,"Reset your shell and type 'fisher <command>' to use Fisherman.")
-	@fish -c "fisher -h" | sed -n '5,$$p'
+	@$(call MSG,"Reset your shell and type 'fisher <command>' to use Fisherman")
+	@fish -c "fisher help -a" | sed -n '3,$$p'
 
 test:
 	@fish -c "fishtape test/*.fish"
@@ -76,5 +76,4 @@ $(AUTHORS): $(FISHER_HOME)
 		sed -E 's/([^<>]+)<([^<>]*)>/* \1 \&lt;[\2](mailto:\2)\&gt;/' >> $@
 
 %.1 %.5 %.7: %.md
-	@echo "Creating the documentation..."
-	-@ronn --manual=fisherman --roff $? 1>&2 2> /dev/null 
+	-@ronn --manual=fisherman --roff $? 1>&2 2> /dev/null

README.md

@@ -25,7 +25,6 @@ Features include a flat tree structure, external self-managed database, cache sy
 git clone https://github.com/fisherman/fisherman
 cd fisherman
 make
-fisher help
 ```
 
 ## Contributing

completions/fisher.fish

@@ -1,31 +1,29 @@
-complete -xc fisher -d "Fisherman"
+complete -xc fisher -d "Ahoy! Fisherman"
+
 complete -c fisher -n "__fish_seen_subcommand_from search" -a "\t"
-complete -c fisher -n "__fish_use_subcommand" -s v -l version -d "Show version information"
-complete -c fisher -n "__fish_use_subcommand" -s h -l help -d "Display help"
-complete -c fisher -n "__fish_use_subcommand" -s f -l file -d "Read fishfile"
-complete -c fisher -n "__fish_use_subcommand" -s a -l alias -d "Define one or more comma-separated command aliases"
 complete -c fisher -n "__fish_use_subcommand" -s l -l list -d "List plugins in the cache"
+complete -c fisher -n "__fish_use_subcommand" -s f -l file -d "Read a fishfile"
+complete -c fisher -n "__fish_use_subcommand" -s h -l help -d "Display help"
+complete -c fisher -n "__fish_use_subcommand" -s a -l alias -d "Define command aliases"
+complete -c fisher -n "__fish_use_subcommand" -s v -l version -d "Show version information"
 
 set -l IFS ";"
-
 for option in commands guides
-    fisher_help --$option=bare | sed -E 's/^ *([^ ]+) *(.*)/\1;\2/' | while read -l func info
+    fisher_help --$option=bare | sed -E 's/^ *([^ ]+) *(.*)/\1;\2/' | while read -l cmd info
 
-        complete -c fisher -n "__fish_seen_subcommand_from help" -a $func -d "$info"
+        complete -c fisher -n "__fish_seen_subcommand_from help" -a $cmd -d "$info"
 
         if test $option = guides
             continue
         end
 
-        complete -c fisher -n "__fish_use_subcommand" -a $func -d "$info"
+        complete -c fisher -n "__fish_use_subcommand" -a $cmd -d "$info"
 
-        fisher_help --usage=$func | __fisher_complete OFS=';' | while read -l 1 2 3
-            complete -c fisher -n "__fish_seen_subcommand_from $func" -s "$3" -l "$2" -d "$1"
+        fisher_help --usage=$cmd | __fisher_complete OFS=';' | while read -l 1 2 3
+            complete -c fisher -n "__fish_seen_subcommand_from $cmd" -s "$3" -l "$2" -d "$1"
         end
     end
 end
 
-if test -e $fisher_cache/.index
-    __fisher_complete_cache update uninstall
-    __fisher_complete_remote install
-end
+__fisher_complete_cache update uninstall
+__fisher_complete_remote install

completions/wait.fish

@@ -5,6 +5,6 @@ complete -xc wait -d "Run commands and wait with a spin"
 complete -xc wait -n "not __fish_seen_subcommand_from --spin" -a "\t"
 
 set -l IFS \t
-wait --help | __fisher_complete | while read -l 1 2 3
+wait -h | __fisher_complete | while read -l 1 2 3
     complete -c wait -s "$3" -l "$2" -d "$1"
 end

config.fish

@@ -11,3 +11,7 @@ set fish_complete_path {$fisher_config,$fisher_home}/completions $fish_complete_
 for file in $fisher_config/conf.d/*.config.fish
     source $file
 end
+
+function d
+    printf "((%s))\n" $argv >&2
+end

functions/__fisher_alias.fish

@@ -1,4 +1,4 @@
-function __fisher_alias -a value -d "Define one or more comma-separated command aliases."
+function __fisher_alias -a value -d "Define command aliases"
     switch "$value"
         case ""
             if test -z "$fisher_alias"

functions/__fisher_cache.fish

@@ -1,8 +1,18 @@
-function __fisher_cache -d "Calculate path of a name, url or path relative to the cache"
+function __fisher_cache -a error -d "Get plugin in cache from a name, url or path"
+    if test -z "$error"
+        set error /dev/stderr
+    end
+
     while read --prompt="" -l item
         switch "$item"
             case file:///\*
-                printf "%s\n" $item
+                for file in $fisher_cache/*
+                    switch "$item"
+                        case file://(readlink $file)
+                            printf "%s\n" $file
+                            break
+                    end
+                end
 
             case \*/\*
                 for file in $fisher_cache/*
@@ -14,7 +24,18 @@ function __fisher_cache -d "Calculate path of a name, url or path relative to th
                 end
 
             case \*
-                printf "%s\n" $fisher_cache/$item
+                set item $fisher_cache/$item
+                if test -d "$item"
+                    printf "%s\n" $item
+                end
+
+        end | read -l path
+
+        if test -z "$path"
+            printf "fisher: Avast! '%s' is not in the cache\n" $item > $error
+            continue
         end
+
+        printf "%s\n" $path
     end
 end

functions/__fisher_complete.fish

@@ -1,5 +1,5 @@
 # Usage
-#     __fisher_complete [awk_var=value] [--help]
+#     __fisher_complete [<awk var>=value] [--help]
 #
 # Example
 #     set -l IFS \t

functions/__fisher_file.fish

@@ -1,8 +1,8 @@
-function __fisher_file -a file -d "Read a fishfile and display its contents"
+function __fisher_file -a file -d "Read a fishfiles"
     switch "$file"
         case ""
             set file $fisher_config/fishfile
-            
+
         case "-"
             set file /dev/stdin
     end
@@ -15,5 +15,5 @@ function __fisher_file -a file -d "Read a fishfile and display its contents"
 
             if (!duplicates[$1]++) printf("%s\n", $1)
         }
-    ' $file
+    ' $argv
 end

functions/__fisher_name.fish

@@ -1,3 +1,3 @@
-function __fisher_name -d "Generate a pretty name from a plugin path or URL"
+function __fisher_name -d "Create pretty name from a plugin path or URL"
     sed -E 's|.*/(.*)|\1|; s/^(plugin|theme|pkg|omf|fish|fisher)-//'
 end

functions/__fisher_validate.fish

@@ -8,12 +8,12 @@ function __fisher_validate -d "Validate a name, url or path"
     while read -lp "" item
         switch "$item"
             case \*..\* /. /
-                continue
+                return 1
         end
 
         if test -e "$item"
-            if test $item = $HOME
-                continue
+            if test $item = $HOME -o $HOME = $PWD
+                return 1
             end
 
             if test -f "$item"

functions/fisher.fish

@@ -27,9 +27,6 @@ function fisher -d "Fish Shell Plugin Manager"
             case l list
                 set option list
 
-            case c cache
-                set option cache
-
             case f file
                 set option file
                 set value $2
@@ -77,24 +74,15 @@ function fisher -d "Fish Shell Plugin Manager"
                 return 1
             end
 
-        case validate
-            __fisher_validate | grep $quiet
-
         case list
             __fisher_list
 
-        case cache
-            __fisher_cache
-
         case file
             __fisher_file "$value"
 
         case alias
             __fisher_alias $alias
 
-        case name
-            __fisher_name
-
         case version
             sed 's/^/fisher version /;q' $fisher_home/VERSION
 
@@ -103,9 +91,7 @@ function fisher -d "Fish Shell Plugin Manager"
                 set value commands
             end
 
-            printf "usage: fisher [--version] [--help] [--list] [--quiet]\n"
-            printf "              [-a <command>=alias[,...]] [-f <path>]\n"
-            printf "              <command> [<options>]\n\n"
+            printf "usage: fisher <command> [<options>] [--version] [--help]\n\n"
 
             switch commands
                 case $value