Archives/fisher
2
0
Fork 0
mirror of https://github.com/jorgebucaran/fisher synced 2024-11-15 12:13:28 +00:00
Code Issues Projects Releases Wiki Activity

Revamp docs

Browse Source
This commit is contained in:
Jorge Bucaran 2020-08-08 01:38:34 +09:00
parent b9c5b48513
commit 297c6b77c7
No known key found for this signature in database
GPG Key ID: E54BA3C0E646DB30
1 changed files with 71 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
README.md
View File

@ -1,114 +1,73 @@
# Fisher # Fisher
Fisher is a package manager for the <a href="https://fishshell.com" title="friendly interactive shell">fish shell</a>. It defines a common interface for package authors to build and distribute shell scripts in a portable way. You can use it to extend your shell capabilities, change the look of your prompt and create repeatable configurations across different systems effortlessly. > A plugin manager for [fish](https://fishshell.com)—the friendly interactive shell.
Here's why you'll love Fisher: Manage functions, completions, bindings, and snippets from the command line. Extend your shell capabilities, change the look of your prompt and create repeatable configurations across different systems effortlessly.
- No configuration needed. - Oh My Fish! plugin support.
- Oh My Fish! package support. - Build and distribute shell scripts in a portable way.
- [XDG directory specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) friendly. - Insanely fast concurrent plugin downloads with built-in cache fallback.
- Blazing fast concurrent package downloads. - Zero configuration out of the box. Need to tweak a thing? You can do that too.
- Cached downloads—if you've installed a package before, you can install it again offline!
- Add, update and remove functions, completions, key bindings, and [configuration snippets](#configuration-snippets) from a variety of sources using the command line, editing your [fishfile](#using-the-fishfile) or both!
Looking for packages? Browse [git.io/awesome-fish](https://git.io/awesome-fish) or [search on GitHub](https://github.com/topics/fish-packages). Fishing for plugins? Browse [git.io/awesome.fish](https://git.io/awesome.fish) or [search](https://github.com/topics/fish-packages) [on](https://github.com/topics/fish-plugins) [GitHub](https://github.com/topics/fish-plugin).
## Installation ## Installation
Just download [`fisher.fish`](fisher.fish) to your functions directory (or any directory in your function path). Just drop [`fisher.fish`](fisher.fish) on any directory in your function path and you are done.
```console ```console
curl https://git.io/fisher --create-dirs -sLo ~/.config/fish/functions/fisher.fish curl https://git.io/fisher --create-dirs -sLo ~/.config/fish/functions/fisher.fish
``` ```
Your shell can take a few seconds before loading `fisher.fish`. If the `fisher` command is not immediately available, launch a new session or [replace](https://fishshell.com/docs/current/commands.html#exec) the running shell with a new one. ## Quickstart
### System Requirements You've found an interesting utility you'd like to try out. Or maybe you've [created a new plugin](#creating-your-own-plugin). How do you install it? How to update or remove it?
- [fish](https://github.com/fish-shell/fish-shell) 2.2+ You can use Fisher to add, update, and remove plugins interactively, taking advantage of fish [tab completion](https://fishshell.com/docs/current/index.html#completion) and syntax highlighting. Or [edit your fishfile](#using-the-fishfile) and commit your changes. Do you prefer a CLI-centered approach, text-based approach, or a mix of both?
- [curl](https://github.com/curl/curl) [7.10.3](https://curl.haxx.se/changes.html#7_10_3)+
- [git](https://github.com/git/git) 1.7.12+
> Stuck in fish 2.0 and can't upgrade your shell? Check our [legacy fish support guide](https://github.com/jorgebucaran/fisher/issues/510) and good luck! ### Adding plugins
### Changing the installation path Add plugins using the `add` command followed by the path to the repository on GitHub.
Fisher expands packages into your fish configuration directory, causing existing files to be overwritten! If you have custom files and want to keep them separate, add the following code to your fish configuration file.
> **Note:** Your fish configuration file is usually in `~/.config/fish/config.fish`.
```fish
set -g fisher_path /path/to/another/location
set fish_function_path $fish_function_path[1] $fisher_path/functions $fish_function_path[2..-1]
set fish_complete_path $fish_complete_path[1] $fisher_path/completions $fish_complete_path[2..-1]
for file in $fisher_path/conf.d/*.fish
builtin source $file 2> /dev/null
end
```
### Bootstrap installation
To automate the installation process in a new system, installing packages in your [fishfile](#using-the-fishfile), add the following code to your fish configuration file.
```fish
if not functions -q fisher
set -q XDG_CONFIG_HOME; or set XDG_CONFIG_HOME ~/.config
curl https://git.io/fisher --create-dirs -sLo $XDG_CONFIG_HOME/fish/functions/fisher.fish
fish -c fisher
end
```
## Getting started
You've found an interesting utility you'd like to try out. Or maybe you've [created a new package](#creating-your-own-package). How do you install it? How to update or remove it?
You can use Fisher to add, update, and remove packages interactively, taking advantage of fish [tab completion](https://fishshell.com/docs/current/index.html#completion) and syntax highlighting. Or [edit your fishfile](#using-the-fishfile) and commit your changes. Do you prefer a CLI-centered approach, text-based approach, or a mix of both?
### Adding packages
Add packages using the `add` command followed by the path to the repository on GitHub.
```console ```console
fisher add jethrokuan/z rafaelrinaldi/pure fisher add jethrokuan/z rafaelrinaldi/pure
``` ```
To add a package from a different location, use the address of the server and the path to the repository. HTTPS is always assumed, so you don't need to write the protocol. To add a plugin from a different location, use the address of the server and the path to the repository. HTTPS is always assumed, so you don't need to specify the protocol.
```console ```console
fisher add gitlab.com/jorgebucaran/kraken fisher add gitlab.com/big/fish
``` ```
To add a package from a private repository set the `fisher_user_api_token` variable to your username followed by a colon and your authorization token or password. To add a plugin from a private repository set the `fisher_user_api_token` variable to your username followed by a colon and your authorization token or password.
```fish ```fish
set -g fisher_user_api_token jorgebucaran:ce04da9bd93ddb5e729cfff4a58c226322c8d142 set -g fisher_user_api_token jorgebucaran:ce04da9bd93ddb5e729cfff4a58c226322c8d142
``` ```
For a specific version of a package add an `@` symbol after the package name followed by the tag, branch or [commit-ish](https://git-scm.com/docs/gitglossary#gitglossary-aiddefcommit-ishacommit-ishalsocommittish). Only one package version can be installed at any given time. For a specific version of a plugin add an `@` symbol after the plugin name followed by the tag, branch or [commit-ish](https://git-scm.com/docs/gitglossary#gitglossary-aiddefcommit-ishacommit-ishalsocommittish). Only one plugin version can be installed at any given time.
```console ```console
fisher add edc/bass@20f73ef jethrokuan/z@pre27 fisher add edc/bass@20f73ef jethrokuan/z@pre27
``` ```
You can add packages from a local directory too. Local packages are installed as [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) so changes in the original files will be reflected in future shell sessions without having to re-run `fisher`. You can add plugins from a local directory too. Local plugins will be installed as [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) so changes in the original files will be reflected in new shell sessions without having to re-run `fisher`.
```console ```console
fisher add ~/path/to/local/pkg fisher add ~/path/to/local/plugin
``` ```
### Listing packages ### Listing plugins
List all the packages that are currently installed using the `ls` command. This doesn't show package dependencies. List all the plugins that are currently installed using the `ls` command. This doesn't show plugin dependencies.
```console ```console
fisher ls fisher ls
jethrokuan/z jethrokuan/z
rafaelrinaldi/pure rafaelrinaldi/pure
gitlab.com/jorgebucaran/kraken gitlab.com/big/fish
edc/bass edc/bass
~/path/to/myfish/pkg ~/path/to/myfish/plugin
``` ```
You can use a regular expression after `ls` to refine the output. You can use a regular expression after `ls` to refine the output.
@ -117,9 +76,9 @@ You can use a regular expression after `ls` to refine the output.
fisher ls "^gitlab|fish-.*" fisher ls "^gitlab|fish-.*"
``` ```
### Removing packages ### Removing plugins
Remove packages using the `rm` command. If a package has dependencies, they too will be removed. If any dependencies are still shared by other packages, they will remain installed. Remove plugins using the `rm` command. If a plugin has dependencies, they too will be removed. If any dependencies are still shared by other plugins, they will remain installed.
```console ```console
fisher rm rafaelrinaldi/pure fisher rm rafaelrinaldi/pure
@ -131,11 +90,11 @@ You can remove everything that is currently installed in one sweep using the fol
fisher ls | fisher rm fisher ls | fisher rm
``` ```
### Updating packages ### Updating plugins
Run `fisher` to update everything that is currently installed. There is no dedicated update command. Using the command line to add and remove packages is a quick way to modify and commit changes to your fishfile in a single step. Run `fisher` to update everything currently installed. There is no dedicated update command. Using the command line to add and remove plugins is the easiest way to modify and commit changes to your fishfile.
Looking for a way to update fisher itself? Use the `self-update` command. Looking for a way to self update Fisher? Use the `self-update` command.
```console ```console
fisher self-update fisher self-update
@ -143,23 +102,44 @@ fisher self-update
### Other commands ### Other commands
Use the `--help` command to display usage help on the command line. Display usage help on the command line.
```console ```console
fisher --help fisher --help
``` ```
Last but not least, use the `--version` command to display the current version of Fisher. Display the current version of Fisher.
```console ```console
fisher --version fisher --version
``` ```
Remove installed plugins, cache, your fishfile, and Fisher.
```console
fisher self-uninstall
```
## Changing the installation path
Fisher expands plugins into your fish configuration directory by default, overwriting existing files. To change this behavior, set `$fisher_path` to your preferred location and put it in your function path.
```fish
set -g fisher_path /path/to/another/location
set -p fish_function_path fish_function_path[1] $fisher_path/functions
set -p fish_complete_path fish_complete_path[1] $fisher_path/completions
for file in $fisher_path/conf.d/*.fish
builtin source $file 2>/dev/null
end
```
## Using the fishfile ## Using the fishfile
Whenever you add or remove a package from the command-line, Fisher writes the exact list of installed packages to `~/.config/fish/fishfile`. This is your fishfile. Add this file to your dotfiles or version control in order to reproduce your configuration on a different system. Whenever you add or remove a plugin from the command-line, Fisher writes the exact list of installed plugins to `~/.config/fish/fishfile`. This is your fishfile. Add this file to your dotfiles or version control in order to reproduce your configuration on a different system.
You can also edit this file and run `fisher` to commit your changes. Only the packages listed in this file will be installed (or remained installed) after `fisher` returns. If a package is already installed, it will be updated. Everything after a `#` symbol will be ignored. You can also edit this file and run `fisher` to commit your changes. Only the plugins listed in this file will be installed (or remained installed) after `fisher` returns. If a plugin is already installed, it will be updated. Everything after a `#` symbol will be ignored.
```fish ```fish
vi ~/.config/fish/fishfile vi ~/.config/fish/fishfile
@ -171,7 +151,7 @@ vi ~/.config/fish/fishfile
gitlab.com/jorgebucaran/kraken gitlab.com/jorgebucaran/kraken
edc/bass edc/bass
+ FabioAntunes/fish-nvm + FabioAntunes/fish-nvm
~/path/to/myfish/pkg ~/path/to/myfish/plugin
``` ```
```console ```console
@ -180,13 +160,11 @@ fisher
That will remove **rafaelrinaldi/pure** and **jethrokuan/z**, add **FabioAntunes/fish-nvm** and update the rest. That will remove **rafaelrinaldi/pure** and **jethrokuan/z**, add **FabioAntunes/fish-nvm** and update the rest.
## Digging deeper ## What is a plugin?
### What is a package? plugins help you organize shell scripts into reusable, independent components that can be shared through a git URL or the path to a local directory. Even if your plugin is not meant to be shared with others, you can benefit from composition and the ability to depend on other plugins.
Packages help you organize shell scripts into reusable, independent components that can be shared through a git URL or the path to a local directory. Even if your package is not meant to be shared with others, you can benefit from composition and the ability to depend on other packages. The structure of a plugin can be adopted from the fictional project described below. These are the files that Fisher looks for when installing or uninstalling a plugin. The name of the root directory can be anything you like.
The structure of a package can be adopted from the fictional project described below. These are the files that Fisher looks for when installing or uninstalling a package. The name of the root directory can be anything you like.
```console ```console
fish-kraken fish-kraken
@ -199,20 +177,20 @@ fish-kraken
└── kraken.fish └── kraken.fish
``` ```
If your project depends on other packages, it should list them as dependencies in a fishfile. There is no need for a fishfile otherwise. The rules concerning the usage of the fishfile are the same rules we've already covered in [using the fishfile](#using-the-fishfile). If your project depends on other plugins, it should list them as dependencies in a fishfile. There is no need for a fishfile otherwise. The rules concerning the usage of the fishfile are the same rules we've already covered in [using the fishfile](#using-the-fishfile).
While some packages contain every kind of file, some packages include only functions or configuration snippets. You are not limited to a single file per directory either. There can be as many files as you need or just one as in the following example. While some plugins contain every kind of file, some plugins include only functions or configuration snippets. You are not limited to a single file per directory either. There can be as many files as you need or just one as in the following example.
``` ```
fish-kraken fish-kraken
└── kraken.fish └── kraken.fish
``` ```
The lack of private scope in fish causes all package functions to share the same namespace. A good rule of thumb is to prefix functions intended for private use with the name of your package to prevent conflicts. The lack of private scope in fish causes all plugin functions to share the same namespace. A good rule of thumb is to prefix functions intended for private use with the name of your plugin to prevent conflicts.
### Creating your own package ## Creating your own plugin
The best way to show you how to create your own package is by building one together. Our first example will be a function that prints the raw non-rendered markdown source of a README file from GitHub to standard output. Its inputs will be the name of the owner, repository, and branch. If no branch is specified, we'll use the master branch. The best way to show you how to create your own plugin is by building one together. Our first example will be a function that prints the raw non-rendered markdown source of a README file from GitHub to standard output. Its inputs will be the name of the owner, repository, and branch. If no branch is specified, we'll use the master branch.
Create the following directory structure and function file. Make sure the function name matches the file name; otherwise fish won't be able to autoload it the first time you try to use it. Create the following directory structure and function file. Make sure the function name matches the file name; otherwise fish won't be able to autoload it the first time you try to use it.
@ -236,9 +214,9 @@ You can install it with the `add` command followed by the path to the directory.
fisher add /absolute/path/to/fish-readme fisher add /absolute/path/to/fish-readme
``` ```
To publish the package upload it to GitHub, GitLab, BitBucket, or anywhere you like. Keep in mind that Fisher is not a package registry. Its function is to fetch fish scripts and put them in place so that your shell can find them. To publish the plugin upload it to GitHub, GitLab, BitBucket, or anywhere you like. Keep in mind that Fisher is not a plugin registry. Its function is to fetch fish scripts and put them in place so that your shell can find them.
Now let's install the package from the net. Open your [fishfile](#using-the-fishfile) and replace the local version of the package you added with the URL of the repository. Save your changes and run `fisher`. Now let's install the plugin from the net. Open your [fishfile](#using-the-fishfile) and replace the local version of the plugin you added with the URL of the repository. Save your changes and run `fisher`.
```diff ```diff
- /absolute/path/to/fish-readme - /absolute/path/to/fish-readme
@ -249,15 +227,17 @@ Now let's install the package from the net. Open your [fishfile](#using-the-fish
fisher fisher
``` ```
You can leave off the `github.com` part of the URL when adding or removing packages hosted on GitHub. If your package is hosted anywhere else, the address of the server is required. You can leave off the `github.com` part of the URL when adding or removing plugins hosted on GitHub. If your plugin is hosted anywhere else, the address of the server is required.
### Configuration snippets ## Plugin Events
Configuration snippets consist of all the fish files inside your `~/.config/fish/conf.d` directory. They run on [shell startup](http://fishshell.com/docs/current/index.html#initialization) and generally used to set environment variables, add new key bindings, etc. > [Coming in Fisher 4](https://github.com/jorgebucaran/fisher/issues/582): `install` and `update`.
Unlike functions or completions which can be erased programmatically, we can't undo a fish file that has been sourced without creating a new shell session. For this reason, packages that use configuration snippets provide custom uninstall logic through an uninstall [event handler](https://fishshell.com/docs/current/#event). ### `uninstall`
Let's walk through an example that uses this feature to add a new key binding for the Control-G sequence. Let's say we want to use it to open the fishfile in the `vi` editor quickly. When you install the package, `fishfile_quick_edit_key_bindings.fish` will be sourced, adding the specified key binding and loading the event handler function. When you uninstall it, Fisher will emit an uninstall event. Plugins may provide custom uninstall logic through an uninstall [event handler](https://fishshell.com/docs/current/#event).
Let's walk through an example that uses this feature to add a new key binding for the Control-G sequence. Let's say we want to use it to open the fishfile in the `vi` editor quickly. When you install the plugin, `fishfile_quick_edit_key_bindings.fish` will be sourced, adding the specified key binding and loading the event handler function. When you uninstall it, Fisher will emit an uninstall event where you can erase the bindings!
``` ```
fish-fishfile-quick-edit fish-fishfile-quick-edit
@ -275,14 +255,6 @@ function $name --on-event $name
end end
``` ```
## Uninstalling
This command also uninstalls all your packages and removes your fishfile.
```console
fisher self-uninstall
```
## License ## License
[MIT](LICENSE.md) [MIT](LICENSE.md)