dwlf/wahoo

:sushi: Once Upon a Fish

Yet Another Fish Framework

About | Install | Getting Started | Advanced | Screencasts | Contributing

About

⚠️ Please upgrade to Fin. So long, and thanks for all the fish!

Wahoo is an all-purpose framework for the fishshell. It looks after your configuration, themes and packages. It is lightning fast and easy to use.

Thanks to everyone who participated in this project ❤️

@gretel @hauleth @joefiorini @bpinto @scorphus @cap10morgan @daveyarwood

Install

No fish? sudo and let me do that for you.

curl -L git.io/wa | sh
wa help

🔰 Getting Started

wa update

Update framework and installed packages.

wa get <package> ...

Install one or more themes or packages. To list available packages type wa use.

You can fetch packages by URL as well via wa get URL

wa list

List installed packages.

To list packages available for download use wa get.

wa use <theme>

Apply a theme. To list available themes type wa use.

wa remove <name>

Remove a theme or package.

Packages subscribed to uninstall_<pkg> events are notified before the package is removed to allow custom cleanup of resources. See Uninstall.

wa new pkg | theme <name>

Scaffold out a new package or theme.

This creates a new directory under $WAHOO_CUSTOM/{pkg or themes}/ with a starting template.

wa submit pkg/<name> [<url>]

Add a new package. To add a theme use wa submit themes/<name> <url>.

Make sure to send us a PR to update the registry.

wa query <variable name>

Use wa query to inspect all session variables. Useful to pretty dump path variables like $fish_function_path, $fish_complete_path, $PATH, etc.

wa destroy

Uninstall Wahoo. See uninstall for more information.

Advanced

Hoot! Ho, brave sir or madam, on your quest to wake the dreamer! Read on if you wish to learn more about Wahoo.

• Bootstrap
• Startup
• Core Library
• Packages
  • Creating
  • Submitting
  • Initialization
  • Uninstall
  • Ignoring

Bootstrap

Wahoo's bootstrap script will install git and fish if not available, switch your default shell and modify $HOME/.config/fish/config.fish to source Wahoo's init.fish script.

Startup

This script runs each time a new session begins, autoloading packages, themes and your custom path (dotfiles) in that order.

The custom path ($HOME/.dotfiles by default) is defined by $WAHOO_CUSTOM in $HOME/.config/fish/config.fish. Modify this to load your own dotfiles if you have any.

Core Library

The core library is a minimum set of basic utility functions that extend your shell.

• See the documentation.

Packages

Creating

A package name may only contain lowercase letters and hyphens to separate words.

To scaffold out a new package:

$ wa new pkg my_package

my_package/
  README.md
  my_package.fish
  completions/my_package.fish

Use wa new theme my_theme for themes.

Please provide auto completion for your utilities if applicable and describe how your package works in the README.md.

my_package.fish defines a single function:

function my_package -d "My package"

end

Bear in mind that fish lacks a private scope so consider the following options to avoid polluting the global namespace:

• Prefix functions: my_package_my_func.
• Using blocks.

Submitting

Wahoo keeps a registry of packages under $WAHOO_PATH/db/.

To create a new entry run:

wa submit pkg/my_package .../my_package.git

Similarly for themes use:

wa submit theme/my_theme .../my_theme.git

This will add a new entry to your local copy of the registry. Please send us a PR to update the global registry.

Initialization

If you want to be notified when your package is loads, declare the following function in your my_package.fish:

function init -a path --on-event init_mypkg

end

Use this event to modify the environment, load resources, autoload functions, etc. If your package does not export any functions, you can still use this event to add functionality to your package.

Uninstall

Wahoo emits uninstall_<pkg> events before a package is removed via wahoo remove <pkg>. Subscribers can use the event to clean up custom resources, etc.

function uninstall --on-event uninstall_pkg

end

Ignoring

Remove any packages you wish to turn off using wa remove <package name>. Alternatively, you can set a global env variable $WAHOO_IGNORE in your ~/.config/fish/config.fish with the packages you wish to ignore. For example:

set -g WAHOO_IGNORE skip this that ...

License

MIT © Authors 🤘