search

danhper / fundle

A minimalist package manager for fish shell
MIT License
375 stars 22 forks source link
fish fish-plugins

readme

fundle Build Status

A minimalist package manager for fish inspired by Vundle.

All plugins are installed/updated using git, so the only requirement is to have git installed and on the path (and well, fish, obviously).

This package manager is compatible with oh-my-fish plugins. If you need the core functions of oh-my-fish, you can use the danhper/oh-my-fish-core plugin.

Installation

You can use the installer:

curl -sfL https://git.io/fundle-install | fish

Or if you don't like to pipe to a shell, just drop fundle.fish in your ~/.config/fish/functions directory and you are done.

mkdir -p ~/.config/fish/functions
wget https://git.io/fundle -O ~/.config/fish/functions/fundle.fish

Automatic install

If you want to automatically install fundle when it is not present, you can add the following at the top of your ~/.config/fish/config.fish.

if not functions -q fundle; eval (curl -sfL https://git.io/fundle-install); end

ArchLinux

fundle is available on the AUR, so you can install it system wide with

yaourt -S fundle-git

Updating

From fundle 0.2.0 and onwards, you can use fundle self-update to update fundle.

Usage

Sample config.fish

Add this to your ~/.config/fish/config.fish or any file that you use to load fundle's plugins (in /etc/fish for example):

fundle plugin 'edc/bass'
fundle plugin 'oh-my-fish/plugin-php'
fundle plugin 'danhper/fish-fastdir'
fundle plugin 'danhper/fish-theme-afowler'

fundle init

This will source the four plugins listed and load all the functions and completions found.

Note that the fundle init is required on each file loading a plugin, so if you load plugins in multiple .fish files, you have to add fundle init to each one of them.

After editing config.fish:

  1. Reload your shell (you can run exec fish for example)
  2. Run fundle install
  3. That's it! The plugins have been installed in ~/.config/fish/fundle

In depth

To add a plugin, you simply need to open ~/.config/fish/config.fish and add:

fundle plugin 'repo_owner/repo_name'

For example:

fundle plugin 'danhper/fish-fastdir'

will install the repository at https://github.com/danhper/fish-fastdir.

To pick a specific version of the plugins, you can append @ followed by a tag from the repo:

fundle plugin 'joseluisq/gitnow@2.7.0'

will install Gitnow release 2.7.0 at https://github.com/joseluisq/gitnow/releases/tag/2.7.0.

If you need to change the repository, you can pass it with --url and it will be passed directly to git clone:

fundle plugin 'danhper/fish-fastdir' --url 'git@github.com:danhper/fish-fastdir.git'

Keep in mind that this option overrides any tag set with '@'.

It also works with other repository hosts:

fundle plugin 'username/reponame' --url 'git@gitlab.com:username/reponame.git'

And it works with https remote as well (in case you have "the authenticity of host github can't be established"):

fundle plugin 'username/reponame' --url 'https://gitlab.com/username/reponame.git'

You can also use a branch, tag or any commit-ish by appending #commit-ish to the URL. For example:

fundle plugin 'danhper/fish-fastdir' --url 'git@github.com:danhper/fish-fastdir.git#my-branch'

will use my-branch. If no commit-ish is passed, it will default to master.

If the fish functions or completions are in a subdirectory of the repository, you can use --path to choose the path to load.

fundle plugin 'tmuxnator/tmuxinator' --path 'completion'

After having made all the calls to fundle plugin, you need to add

fundle init

in your configuration file for the plugins to be loaded.

IMPORTANT: When you add new plugins, you must restart your shell before running fundle install. The simplest way to do this is probably to run exec fish in the running shell.

You can then run

fundle install

for fundle to download them.

You can also use

fundle update

to update the plugins.

Commands

Completions are available in the completions/fundle.fish. Note that you will need to install fish-completion-helpers to use them.

Plugin structure

A plugin basically has the following structure.

.
├── completions
│   └── my_command.fish
├── functions
│   ├── __plugin_namespace_my_function.fish
│   └── my_public_function.fish
├── init.fish
└── README.md

NOTE: if no init.fish file is found, the root folder of the plugin is treated as a functions directory. This is to make the plugins compatible with oh-my-fish plugins themes.

Managing dependencies

fundle can manage dependencies for you very easily. You just have to add

fundle plugin 'my/dependency'

in your plugin init.fish and fundle will automatically fetch and install the missing dependencies when installing the plugin.

I created a minimal example in fish-nvm, which depends on edc/bass.

Profiling

Obviously, adding plugins makes the shell startup slower. It should usually be short enough, but if you feel your shell is becoming to slow, fundle has a very basic profiling mode to help you.

All you need to do is to change

fundle init

to

fundle init --profile

in your config.fish and fundle will print the time it took to load each plugin.

NOTE:

Compatible plugins

Most oh-my-fish plugins should work out of the box or with danhper/oh-my-fish-core installed.

Please feel free to edit the wiki and add your plugins, or plugins you know work with fundle.

Contributing

Contributions are very appreciated. Please open an issue or create a PR if you want to contribute.

If you created a package compatible with fundle, feel free to add it to the Wiki.

Motivations

I know that oh-my-fish has a utility to install packages, but I wanted the simplest tool possible, not a whole framework.

Changelog