- create fishfile if one doesn't already exist
- only read from stdin when using `add` or `rm` commands
- show help if unknown command is entered
- show error message when fishfile is empty and no packages
were added, removed or updated
SUMMARY
This PR rewrites fisher from the ground up and adds new
documentation. It introduces some breaking changes as described
in the next section. For a historical background of this work
see the original V3 proposal #307 and the more recent discussion
about the future of the project #443.
After much debate and careful consideration I decided it is in
the best interest of the project to keep the CLI-based approach
to dependency management as a facade to the fishfile-based
approach originally proposed.
The new `add` commands (previously `install`) and good ol' `rm`
interactively update your fishfile and commit all your changes
in one sweep. To the end user, it's as if you were adding or
removing packages like you already do now. Internally, these
commands affect how the fishfile is parsed and result in adding
new or replacing/removing existing entries followed by a regular
`fisher` run.
INSTALLING
- `install` has been renamed to `add`
- Installing from a gist is no longer supported (but it will be
back in a future release—removed only to simplify the rewrite)
- To install a package from a tag or branch use an at symbol
`@`—the colon `:` is deprecated
LISTING
- `ls` and `rm` are still available with a few minor differences
- `ls` followed by a package name does not list specific package
information (may be added back in a future release)
- `ls` output format no longer displays a legend to indicate
whether a package is a theme or a local package; now it's a flat
dump of every installed package specifier
- For local packages the full path is shown instead
- I want to add a `--tree` option in to display packages in a
tree-like format in the future
- `ls-remote` has been removed as there is no longer a preferred
organization to look for packages— there is no plan to add it
back
UPDATING
- A new `self-update` command has been introduced to update
fisher itself
- fisher will be only updated when a new version is actually
available
- `update` has been removed
- Everything is installed from scratch everytime you add or
remove something, so there is no need to update specific
packages—you're always up-to-date
- To lock on a specific package version install from a
tag/branch, e.g., `mypkg/foobar@1.3.2`
UNINSTALLING
- `self-uninstall` works as usual
HELP & VERSION
- `help` only displays fisher usage help
- help is dumped to stdout instead of creating a man page on the
fly and piping it to your pager `version` works as usual
ENVIRONMENT
- `$fish_path` been renamed to `$fisher_path` to make it clear
that this is a fisher specific extension, not your shell's
ECOSYSTEM
- Oh My Fish! packages are still supported, albeit less
attention is paid to them
- Some packages that use Oh My Fish! specific environment
variables or events might not work
- Most of Oh My Fish! extensions are no longer necessary since
fish 2.3, therefore it should be a simple matter to upgrade them
to modern fish
DEPENDENCIES
- fisher can now run on fish 2.0
- It's a good idea to upgrade to at least fish 2.3 to use the
string builtin and configuration snippets, but there's no reason
for fisher to force you to use any fish version
- `curl` is required for fetching packages
- I am considering adding a fallback to `wget` if `curl` is not
available on your system
- `git` is optional
- V3 fetches packages directly from github, gitlab and
bitbucket, if you are using them
- git is only used (implementation still wip) if you want to
install a package from an unknown git host like your own git
server
The awk json parsing routine was setting a variable of "description"
instead of "info". This was causing a problem where the cached index -
and subsequently ls-remote commands - to show the "%info" format item as
the URL again.
* Ensure fisherman's completions are placed in the correct fisherman directory when running self update.
* Update documentation to include the extra steps required when setting fish_path.
* -U instead of -g in README.
Fisherman was always writing its completion file to $fish_config/completions.
This was incorrect behavior if $fish_path was set to a directory other than
$fish_config (its default).
Note that when using $fish_path to manage functions, completions and snippets,
you opt out fish default locations which are handled for you by the shell and
consequently are responsible for appending your custom $fish_path/functions
and $fish_path/completions directories to $fish_function_path and $fish_complete_path respectively, as well as sourcing snippets (.fish files under $fish_path/conf.d) on shell
startup.
- `__fisher_log` doesn't work on <2.2.0 anymore so use `echo` instead
- `command -s` option not available on macOS, so use `type` instead
- `type -q` not available on fish <2.2.0,use `type brew >/dev/null 2>&1`
- `brew up` not needed anymore, it auto updates now
- `brew --HEAD` not needed, latest version is enough
* Add support to fish-theme-* and fish-plugin-* repo names,
otherwise fisherman would end up trying to install the
unknown dependencies.
* Remove support for using `:' as a git tag delimiter when
installing plugins as that was causing full URLs to be
parsed incorrectly.
Use fisher [install] PLUGIN:BRANCH_NAME to install from any
given branch. The default branch is master. You can use `@'
instead of `:' to specify the branch name.
If you install a plugin from BRANCH and later remove it,
the repository in ~/.cache/fisherman/PLUGIN will remain
checked out on BRANCH. To force install from another
branch specify a different branch, e.g. `:master'.
fisher PLUGIN:BRANCH
fisher rm PLUGIN
fisher PLUGIN # install PLUGIN from BRANCH
# or
fisher PLUGIN:master # install PLUGIN from master
Updating a plugin always fetches the latest HEAD from
the currently checked out branch.
To install `parent` with `child`, the user only needs to
enter `fisher parent`, but given the following scenario:
fisher parent child
and before this commit, fisherman would fail to increase the
ref count of children because the function that calculates
missing dependencies would see that `child` is already in
the argv list.
The above, even if rare, is a valid use case, and `child`
should end up with a ref count of 2 instead of 1.
This probably means the user does not have python installed on their
system and we will be download the index every time the user runs
ls-remote.
A more sensitive, python-less solution to check file age since the last
time the file was modified should be more desirable.
delimited, awk-friendy format and put it in .cache/.index.
During the process, sort the data also. This way, don't need
to repeat the same process every time we run ls-remote.
Add completions for ls-remote with plugin name and info.
when updating the index for ls-remote.
Allow ls-remote to accept a key and always print record if it
matches the plugin's name. Works with the format string too.
Close#234, #236, #238
Running fisher ls-remote will query the GitHub API for all the
repos in the fisherman org and retrieve the JSON file which is
saved to .cache/fisherman/.index.json.
This file is updated every half and hour whenever you run the
command again. This number is subject to change in the future
as we learn how people are actually using this option.
The ls-remote option can take --format=<fmt string> option used
to customize the list output.
By default, it shows only names and breaks it into columns as
wide as your terminal window.
<fmt string> can contain \t tabs or \n line breaks and one or
more of the following variables with information about plugins.
* %name
* %info
* %url
* %stars
ln -F is relevant only when the target is a directory, in which
case `ln` will delete the directory so that the link can occur.
In fisherman, we use links in only two places:
1. Linking files into .config/fish/{functions,completions}, and
2. Linking local plugins into the .config/fisherman
If my calculations are correct, we don't need -F in either case.
Both {functions/completions} never contain directories, so (1)
is probably safe. The fisherman config only contains directories
to installed plugins, so not using -F actually prevents the user
from overwriting a plugin currently installed with a local plugin.
The previous implementation was creating a nested copy of
the target directory (updated plugin) inside the cached
copy.
After some research, I believe there are two things we
can do here:
1. Remove the target and create a new copy or
2. Use the following syntax
cp -rf src_dir/. target_dir
which seems to do what we want, overwrite target with
source entirely.
A lot has changed, in fact, fisherman as you knew it, is
no longer with us. Let me explain. The new fisherman, is
in fact a rewired clone of ``fin´´, a short-lived 2 week
experiment that started because it was easier to rewrite
everything than moving fisherman forward.
Let me explain. I was longing for a lightweight, simpler
fisherman with minimal maintanance cost. This fin lad is
one of the most pragmatic pieces of code I've ever written,
but attempting to maintain two drastically different plugin
managers was not a sane decision. fin's goal was to get out
of my way and let me be productive with fish and it did.
Now fin is fisherman and fisherman is fin. The most notable
change is that fisherman no longer depends on an index, so
like fin, it's neutral and agnostic to what plugins you use.
No index means fisherman completions are no longer as clever
as to show you description of plugins, but you will still get
enough information to know whether the plugin is a theme or not.
I hope you always check the plugin's README / online docs before
installing anything anyway.
With the index gone, we had no use for ``search``, so this command
is also gone.
If you were using search often or depended on the removed features
above, I am afraid they are gone *gone*, but trust me it's all for
the very best.
Now, with this out of the way, it's all unicorns and dartfish. Almost.
To upgrade to fisherman 2.0.0 you need to REMOVE your current version
of fisherman:
1. ```rm -rf "$fisher_home" "$fisher_config"```
2. Open your config.fish and remove the fisherman initialization code.
3. ```exec fish < /dev/tty``` to reload the session.
4. Run `curl -Lo ~/.config/fish/functions/fisher.fish --create-dirs git.io/fisherman`
That's it. Probably.
The new fisherman brings a lot more stability and maturity to the
project and we need this change in order to move forward. I will
be actively fixing any bugs that may have sneaked in during the
```fin->fisherman``` rewiring, but please do ping me:
@bucaran on GitHub or directly to my email j@bucaran.me
if you find anything out of place. Feel free and invited to go
wild with issues in order to get this into shape ASAP.
Cheers!