diff --git a/README.md b/README.md index c955d87..ba43b11 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,28 @@ A plugin can be any number of files in a `functions`, `conf.d`, and `completions Non `.fish` files as well as directories inside those locations will be copied to `$fisher_path` under `functions`, `conf.d`, or `completions` respectively. +### Event system + +Plugins are notified as they are being installed, updated, or removed via Fish [events](https://fishshell.com/docs/current/cmds/emit.html). + +> `--on-event` functions must already be loaded when their event is emitted. Thus, you should put your event handlers in the `conf.d` directory. + +```fish +# Defined in ponyo/conf.d/ponyo.fish + +function _ponyo_install --on-event ponyo_install + # Set universal variables, create bindings, and other initialization logic. +end + +function _ponyo_update --on-event ponyo_update + # Migrate resources, print warnings, and other update logic. +end + +function _ponyo_uninstall --on-event ponyo_uninstall + # Erase "private" functions, variables, bindings, and other uninstall logic. +end +``` + ## Creating a theme A theme is just like a regular Fish plugin, except it has a `.theme` file in the `themes` directory. Themes were introduced in [Fish 3.4](https://github.com/fish-shell/fish-shell/releases/tag/3.4.0) and work with the `fish_config` builtin. A theme can also have files in `functions`, `conf.d`, or `completions` if necessary. This is what a typical theme plugin might look like. @@ -140,7 +162,7 @@ A theme is just like a regular Fish plugin, except it has a `.theme` file in the └── sosuke.theme -## Using `$fisher_path` with themes +### Using `$fisher_path` with themes If you customize `$fisher_path` to use a directory other than `$__fish_config_dir`, your themes won't be available via `fish_config`. That's because Fish expects your themes to be in `$__fish_config_dir/themes`, not `$fisher_path/themes`. This is not yet configurable in Fish, but there is [a request to add that feature](https://github.com/fish-shell/fish-shell/issues/9456). @@ -158,29 +180,7 @@ ln -s $fisher_path/themes $__fish_config_dir/themes If you want to use theme plugins and also maintain your own local themes, you can read more about how to do that here: [#708](https://github.com/jorgebucaran/fisher/issues/708). -### Event system - -Plugins are notified as they are being installed, updated, or removed via Fish [events](https://fishshell.com/docs/current/cmds/emit.html). - -> `--on-event` functions must already be loaded when their event is emitted. Thus, you should put your event handlers in the `conf.d` directory. - -```fish -# Defined in ponyo/conf.d/ponyo.fish - -function _ponyo_install --on-event ponyo_install - # Set universal variables, create bindings, and other initialization logic. -end - -function _ponyo_update --on-event ponyo_update - # Migrate resources, print warnings, and other update logic. -end - -function _ponyo_uninstall --on-event ponyo_uninstall - # Erase "private" functions, variables, bindings, and other uninstall logic. -end -``` - -### Discoverability +## Discoverability Fisher doesn't make use of a central repository of plugins. However, that doesn't mean discovering new plugins should be hard. A great way to help people quickly find your project on GitHub is [by adding a topic to your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics#adding-topics-to-your-repository). We recommend using [`fish-plugin`](https://github.com/topics/fish-plugin) for this purpose.