So, to answer the most important question, WHY do I want this thing?
Long wall of text ahead, but I promise this covers a lot.
---
If you are only using fish, you are missing out the ability to effectively share plugins, prompts, configs, missing completions, documentation for external utilities, plain old scripts or bundle of scripts.
If you are using Oh My Fish (OMF) / Wahoo or Tacklebox, you may be already doing some of the above, just very poorly.
---
So, I want to create shell scripts, snippets or let's call them utilities that follow the [UNIX guidelines](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_...) for option parsing, fish auto-completion out of the box, with bundled documentation using the traditional `man(1)` pages like a boss, and I want my scripts to come not only in the form of `.fish` files, but I want to ship them bundled with scripts in other languages too sometimes, maybe Awk or Perl, or if you are cool, Python. Then I want to commit that to a GitHub repository, or as a Gist, or to BitBucket, GitLabs or my own server if I want.
---
Fisherman makes this process very easy and it also gives me access to an external ["index"](https://github.com/fisherman/fisher-index) to where I can publish these utilities, let's better call them now plugins so that others can discover my stuff without having to know the URL in advance.
Fisherman is not like, say `brew` where you typically share one or more binaries, that's a true package manager indeed.
---
Fisherman, however, is about sharing snippets, prompts, configurations, initialization scripts, like I said above, that kind of stuff. In the Fisherman jargon, I am rolling all that into a bun and calling it "plugin".
---
To Fisherman they are all the same, they should be, and if that's not the case your "framework", "manager", whatever, is not doing you any service.
---
There are several different setups that Fisherman understands and can process. Why? Because there are already existing snippets and plugins with their own idiosyncrasies. The same ones I mentioned above. Also people creating stuff in fish and releasing it without a particular "framework" in mind.
---
Fisherman recognizes packages from all of those dimensions and lets you install them and use them as you wish. Without strange restrictions that these other "frameworks" often pose on you, like strange name conventions or strict URL forms. It _will even__ try to guess the URL and correct your mistakes sometimes.
---
You can also "install" stuff locally and it will symlink a directory to Fisherman's configuration directory so that you can develop, test and iterate :repeat: fast and without having to do anything but `(1)` creating a directory and `(2)` typing `fisher install .` or `fisher install <my_path>`. You can commit your changes to a Git repo and that will not affect the process. It just works™.
---
But also you get a builtin (obviously it's builtin) cache system to let you install stuff while you are offline (assuming you already downloaded the _stuff_ first) and that segues into Fisherman's simplest, but IMO best feature, the flat tree :evergreen_tree:.
Here is the thing, Fisherman is as fast as no* Fisherman.
The [initialization script](https://github.com/fisherman/fisherman/blob/master/config.fi...) basically declares a few variables and evaluates only config files that you allow Fisherman to evaluate. Period.
---
On the other hand, legacy OMF and modern OMF, Wahoo and Tacklebox mutate a variable to add / remove paths as you install / uninstall plugins. This is slower than loading all your functions into a single directory and telling fish to load only that.
---
But wait, you say, a flat tree means every function will be public and there ought to be name collisions and what not. Well, that's how it has always been. If you were under the impression there was such thing as private function scope, I am sorry, there isn't.
* http://stackoverflow.com/questions/25088699/make-fish-functi...
* https://github.com/fish-shell/fish-shell/issues/1799
---
This is a "deficiency" (or feature maybe?) of the language and there is no way around the implications of this. You create a function and then remove it from the scope, but that does not change the fact _that function_ will replace any other function with the same name.
---
Now, you can always add prefixes to your functions or use underscores at the beginning of the function name like most folks do anyway. So, by using an underscore you express your intention to mark this function as private, but it's just as "public" as any other.
Well, if fish has no private function scope, then it makes sense to use a flat tree for speed.
---
In the case of OMF and admitedly Wahoo too, things are even worse :sweat_smile: because these two boys use fish [_event handlers_](http://fishshell.com/docs/current/commands.html#emit) during their initialization process, and since fish does not* automatically load files with events (there is just no convention for this ATM), they need to source every single `.fish` file inside each plugin's directory and inmediately `emit EVENT_NAME` adding yet another step in the process.
---
Events are great for communicating between different components / areas in a complex application, and I originally thought of using them in Fisherman despite the (arguably small) performance overhead, but desisted when I realized whatever happens inside an event handler, does not leak. They are essentially black holes and useless if you want to parse any output generated inside the handler / function.
---
One of Fisherman features is UNIX stinkiness. I don't think the UNIX philosophy (whatever that was) is a creed unbreakble doctrine, but I like to write my functions and utilities so that they can be plug / plumb into one another easily. That's why everything is a "stream" and all the commands Fisherman ships with read the standard input and do what you would expect if you are already familiar in how UNIX typically works. This is one of the principles I based while writing this, so it's everywhere. It's also [here](https://github.com/bucaran/getopts). That is used in Fisherman to make sophisticated CLI apps. It's written in sed/awk and it's really fast.
---
This is not even close to all Fisherman has to offer. There other cool things like the [search](https://github.com/fisherman/fisherman/wiki#search-point_lef...) command that parses the index file and lets you query plugins like you would expect from any modern tool. In OMF/Wahoo (Tacklebox has nothing) you only get a name.
---
In Fisherman every plugin gets a well deserved `name`, `url`, `description`, any number of `tags` and an `author`'s name. Makes sense.
---
And if you install a plugin from an "unknown" URL (one not in [fisher-index](https://github.com/fisherman/fisher-index/blob/master/INDEX), Fisherman will complete the information the best it can querying the Git repository, exhausting all the possibilities, so there's always data. It even looks at the URL itself and tries to guess stuff.
---
This "index" thing, is just a plain text flat database written in a human readable format. One cool thing is, the index is always kept up to date, unlike in OMF where you need to update in order to learn about the new goods. So, you don't have to update the entire application just to see what new packages are available, you are always querying the latest index.
---
A few other features that to mind is Fishfiles (dependency manifest file) that allows plugins to declare dependencies to other plugins and keep track of what plugins you have installed or not in your system.
---
BTW, OMF uses a more naive, but still similar, `bundle` file. Fisherman recognizes this and works with it too. No questions asked :+1:
---
Finally, the bundled help is phenomenal. Everything ships in glorious `man(1)` pages. You are not alone. Every single feature is thoroughly documented like it should be and now the Wiki is also pretty nice with the screencasts for each command.