mirror of https://github.com/jorgebucaran/fisher synced 2024-07-06 23:11:48 +02:00

=====================

Add user key bindings support.

Recall   $fisher_home/functions  are   always  before   user
functions in  $fish_function_path. This was an  early design
decision  in order  to  prevent users  from redefining  core
functions by  mistake or by  means other than  using plugins
(recommended).  In other  words, you  are free  to create  a
plugin  that modifies  a  Fisherman core  function, but  you
can't redefine  a Fisherman function privately  by saving it
to your user config fish. If  you found a bug in a Fisherman
function,  instead  of  creating  a private  patch  send  it
upstream.  If  you  created  a  function  that  overrides  a
Fisherman  core  feature,  create  a plugin.  This  way  the
community can benefit from your  code whenever you are ready
to publish it.

By  default, Fisherman  provides no  fish_user_key_bindings,
so   if   the   user   has   already   defined   their   own
fish_user_key_bindings that one will not be affected.

Now,  plugins can  define their  own key  bindings inside  a
fish_user_key_bindings.fish or key_bindings.fish at the root
of their repository or inside a functions directory. You can
put your key  bindings inside a function or not.  If you put
it inside a function, the function  name must be the same as
the file without the .fish extension.

$fisher_config/bindings.fish   When   a  plugin   with   key
bindings  is  installed  for  the first  time  or  the  only
one  with bindings  is  uninstalled,  Fisherman will  modify
~/.config/functions/fish_user_key_bindings.fish  (or  create
it for  the first  time) and  add a single  line at  the top
of  the fish_user_key_bindings  function to  source the  new
$fisher_config/bindings.fish. All  the key  bindings defined
by the enabled/installed plugins  are concatenated and saved
to this file.

This mechanism has the following advantages:

Does not slow  down shell start. Does  not require Fisherman
to  provide  his   own  fish_user_key_bindings  by  default.
Honors  any previously  existing user  key bindings.  Allows
plugin  to  define  their   own  key  bindings  and  coexist
with  the  user's key  bindings.  If  the user  updates  his
fish_user_key_bindings, re-running the  function does update
the key bindings. Mega Refactoring

The   entire   source   code   of   Fisherman   received   a
major   revision  and   refactoring.   The  validation   and
install/uninstall mechanisms were thoroughly revised and and
broken down into smaller functions easier to test as well as
several other sub parts of the system.

Rewrite fisher  search and  remove features that  are mostly
already covered by  fisher --list and remove  the ability to
generate information  about plugins  of unknown  origin. The
decision  to remove  this feature  was based  in performance
concerns  and the  result  of thinking  about the  usability
and  whether it  was really  worth the  speed tradeoff.  The
conclusion is I would rather  have better performance and if
I need  to query a  plugins origin  I can always  use fisher
--list or fisher --list=url or fisher --list=author.

Add $fisher_update_interval to determine if the index should
update  or not  when a  search  query is  taking place.  The
default value is  10 seconds. This means the  index will not
be updated  if less than  10 seconds have elapsed  since the
last action that triggered an update in the first place. See

Improve Install/Uninstall/Update status  output. If a plugin
fails  to install  decrease the  total. If  any plugins  are
skipped because  they are already  installed in the  case of
fisher install  or available in  the cache, but  disabled in
the  case of  fisher uninstall  they are  collected into  an
array and displayed in a  new section n plugin/s skipped (a,
b, c) at the bottom of the report.

Improve test coverage.

Tightly coupled  functions were making  testing increasingly
difficult.  Most of  the test  effort was  basically testing
whether git  clone or git  pull. New separation  of concerns
makes tests  run faster and the  difficult install/uninstall
algorithms has better coverage now. Other

Now  __fisher_list  can  list  plugins  from  the  cache,  a
fishfile/bundle  and plugins  that are  installed/enabled or
disabled. This  removes __fisher_file  and combines  it with
__fisher_list. This  also removes fisher -f  and replaces it
with fisher -l <file> or fisher --list=<file>.

Rename __fisher_parse_help to __fisher_complete and have the
function create  the completions automatically.  This allows
you  to complete  your  commands with  parseable usage  help
faster.  The  original  design  was fine,  but  this  change
improves auto-complete performance so it was preferred.

Use __fisher_index_update when building file with Make. This
helps prevent  an error when  using a fish version  < 2.2.0.
See #55 #50 #48.

Add  __fisher_index_update to  update the  index and  remove
previously   undocumented   fisher  update   --index.   This
function  is  designed  to bypass  GitHub's  server  network
cache  passing  an  arbitrary  query  string  to  curl  like
$fisher_index?RANDOM_NUMBER.  This means  index updates  are
immediately available now.

Add fisher --list=url option to  display local plugin url or
path.

Add fisher  --list=bare option  to display local  plugins in
the cache without the * enabled symbol.

Prepend > to  the currently enabled theme  when using fisher
--list[=cache]. Related #49.

Prepend *  to plugin  names to  indicate they  are currently
enabled when using fisher --list[=cache]. See #49.

2016-02-02 04:39:16 +09:00

5.6 KiB

Raw Blame History

fisher-faq(7) -- Frequently Asked Questions

SYNOPSIS

This document attempts to answer some of Fisherman most frequently asked questions. Feel free to create a new issue in the Fisherman issue tracker if your question is not answered here.

What is Fisherman?

Fisherman is a plugin manager for fish that lets you share and reuse code, prompts and configurations easily.

What do I need to know to use Fisherman?

Nothing. You can continue using your shell as usual. When you are ready to learn more just type fisher help or fisher help tour.

How do I access the documentation?

Fisherman documentation is based in UNIX man(1) pages. For basic usage and command enter fisher help. For help about a specific command, enter fisher help <command>. The following guides are also available:

fisher help faq: Fisherman FAQ
fisher help tour: Fisherman Tour
fisher help config: Fisherman Configuration
fisher help plugins: Creating Fisherman Plugins
fisher help commands: Creating Fisherman Commands
fisher help fishfile: Fishfile Format

What are Fisherman plugins?

Plugins are written in fish and extend the shell core functionality, run initialization code, add completions or documentations to other commands, etc. See fisher help plugins.

Plugins may list any number of dependencies to other plugins using a fishfile.

What is a Fishfile?

A plain text file that lists what plugins you have installed or a plugin's dependencies to other plugins.

Fishfiles let you share plugin configurations across multiple installations, allow plugins to declare dependencies, and prevent information loss in case of system failure. See also fisher help fishfile.

What kind of Fisherman plugins are there?

There is no technical distinction between plugins, themes, commands, etc., but there is a conceptual difference.

Standalone Utilities: Plugins that define one or more functions, meant to be used at the command line.
Prompts / Themes: Plugins that modify the appearance of the fish prompt by defining a fish_prompt and / or fish_right_prompt functions.
Extension Commands: Plugins that extend Fisherman default commands. An extension plugin must define one or more functions like fisher_<my_command>. For specific information about commands, see fisher help commands and then return to this guide.
Configuration Plugins: Plugins that include one or more my_plugin.config.fish files. Files that follow this convention are evaluated at the start of the session.

See fisher help plugins and fisher help commands.

Does Fisherman support Oh My Fish plugins and themes?

Yes. To install either a plugin or theme use their URL:

fisher install omf/plugin-{rbenv,tab} omf/theme-scorphish

You can use the same mechanism to install any valid plugin from any given URL. See also Compatibility in fisher help tour.

What does Fisherman do exactly every time I create a new shell session?

Essentially, add Fisherman functions and completions to the $fish_{function,complete}_path and evaluate files that follow the convention *.config.fish.

set fish_function_path {$fisher_config,$fisher_home}/functions $fish_function_path
set fish_complete_path {$fisher_config,$fisher_home}/completions $fish_complete_path

for file in $fisher_config/conf.d/*.config.fish
    source $file
end

See $fisher_home/config.fish for the full code.

How is Fisherman faster than Oh My Fish and other systems?

Fisherman ameliorates the slow shell start problem using a flat dependency tree instead of loading a directory hierarchy per plugin. This also means that Fisherman performance does not decline depending on the number of plugins installed. See also Flat Tree in fisher help tour.

Why don't you contribute your improvements back to Oh My Fish?

I have contributed back to Oh My Fish extensively. See also Oh My Fish history for August 27, 2015 when another project, Wahoo, was entirely merged with Oh My Fish.

In addition, Fisherman was built from the ground up using a completely different design, implementation and set of principles.

Some features include: UNIX familiarity, minimalistic design, flat tree structure, unified plugin architecture, external self-managed database, cache system, dependency manifest file and compatibility with Oh My Fish, etc. See fisher help tour.

How can I upgrade from an existing Oh My Fish or Wahoo installation?

Install Fisherman.

git clone https://github.com/fisherman/fisherman
cd fisherman
make

You can now safely remove Oh My Fish $OMF_PATH and $OMF_CONFIG.

Backup dotfiles and other sensitive data first.

rm -rf {$OMF_PATH,$OMF_CONFIG}

I changed my prompt with `fish_config` and now I can't use any Fisherman theme, what do I do?

fish_config persists the prompt to XDG_CONFIG_HOME/fish/functions/fish_prompt.fish. That file takes precedence over Fisherman prompts that installs to $fisher_config/functions. To use Fisherman prompts remove the fish_promt.fish inside XDG_CONFIG_HOME/fish/functions.

Assuming XDG_CONFIG_HOME is ~/.config in your system:

rm ~/.config/fish/functions/fish_prompt.fish

How do I use fish as my default shell?

Add Fish to /etc/shells:

echo "/usr/local/bin/fish" | sudo tee -a /etc/shells

Make Fish your default shell:

chsh -s /usr/local/bin/fish

To switch back to another shell.

chsh -s /bin/another/shell

Why is this FAQ similar to the Oh My Fish FAQ?

Because it was written by the same author of Fisherman and Wahoo and some of the questions and answers simply overlap.

5.6 KiB Raw Blame History