Repository: jorgebucaran/fisher
Branch: main
Commit: 791da644d33d
Files: 8
Total size: 22.7 KB

Directory structure:
gitextract_80b_g35x/

├── .github/
│   └── workflows/
│       └── ci.yml
├── LICENSE.md
├── README.md
├── completions/
│   └── fisher.fish
├── functions/
│   └── fisher.fish
└── tests/
    ├── fisher.fish
    └── ponyo/
        ├── conf.d/
        │   └── ponyo.fish
        └── functions/
            └── ponyo.fish

================================================
FILE CONTENTS
================================================

================================================
FILE: .github/workflows/ci.yml
================================================
name: CI

on: push

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Install Fish
        run: |
          sudo apt-add-repository -yn ppa:fish-shell/release-3
          sudo apt-get update
          sudo apt-get install -y fish

      - name: Install Tools
        run: |
          source $GITHUB_WORKSPACE/functions/fisher.fish
          fisher install $GITHUB_WORKSPACE jorgebucaran/fishtape
          fishtape tests/*.fish
        shell: fish {0}


================================================
FILE: LICENSE.md
================================================
Copyright © Jorge Bucaran <<https://jorgebucaran.com>>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


================================================
FILE: README.md
================================================
# Fisher

> A plugin manager for [Fish](https://fishshell.com)—your friendly interactive shell. [Snag fresh plugins!](https://github.com/jorgebucaran/awsm.fish#readme)

Take control of functions, completions, bindings, and snippets from the command line. Unleash your shell's true potential, perfect your prompt, and craft repeatable configurations across different systems effortlessly. Fisher's zero impact on shell startup keeps your shell zippy and responsive. No gimmicks, just smooth sailing!

- Fisher is 100% pure-Fish, making it easy to contribute or modify
- Scorching fast concurrent plugin downloads that'll make you question reality
- Zero configuration needed—we're not kidding!
- Oh My Fish! plugins supported too

> #### ☝️ [Upgrading from Fisher `3.x` or older? Strap in and read this!](https://github.com/jorgebucaran/fisher/issues/652)

## Installation

```console
curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher
```

## Quickstart

Fisher lets you install, update, and remove plugins like a boss. Revel in Fish's [tab completion](https://fishshell.com/docs/current/index.html#completion) and rich syntax highlighting while you're at it.

### Installing plugins

To install plugins, use the `install` command and point it to the GitHub repository.

```console
fisher install jorgebucaran/nvm.fish
```

> Wanna install from GitLab? No problemo—just prepend `gitlab.com/` to the plugin path.

You can also snag a specific version of a plugin by adding an `@` symbol after the plugin name, followed by a tag, branch, or [commit](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefcommit-ishacommit-ishalsocommittish).

```console
fisher install IlanCosman/tide@v6
```

And hey, you can install plugins from a local directory too!

```console
fisher install ~/path/to/plugin
```

> Heads up! Fisher expands plugins into your Fish configuration directory by default, overwriting existing files. If that's not your jam, set `$fisher_path` to your preferred location and put it in your function path ([#640](https://github.com/jorgebucaran/fisher/issues/640)).

### Listing plugins

Use the `list` command to see all your shiny installed plugins.

```console
$ fisher list
jorgebucaran/fisher
ilancosman/tide@v5
jorgebucaran/nvm.fish
/home/jb/path/to/plugin
```

The `list` command also plays nice with regular expressions for filtering the output.

```console
$ fisher list \^/
/home/jb/path/to/plugin
```

### Updating plugins

`update` command to the rescue! It updates one or more plugins to their latest and greatest version.

```console
fisher update jorgebucaran/fisher
```

> Just type `fisher update` to update everything in one fell swoop.

### Removing plugins

Say goodbye to installed plugins with the `remove` command.

```console
fisher remove jorgebucaran/nvm.fish
```

Feeling destructive? Wipe out everything, including Fisher itself.

```console
fisher list | fisher remove
```

## Using your `fish_plugins` file

Whenever you install or remove a plugin from the command line, Fisher jots down all the installed plugins in `$__fish_config_dir/fish_plugins`. Add this file to your dotfiles or version control to easily share your configuration across different systems.

You can also edit this file and run `fisher update` to commit changes like a pro:

```console
$EDITOR $__fish_config_dir/fish_plugins
```

```diff
jorgebucaran/fisher
ilancosman/tide@v5
jorgebucaran/nvm.fish
+ PatrickF1/fzf.fish
- /home/jb/path/to/plugin
```

```console
fisher update
```

This will install **PatrickF1**/**fzf.fish**, remove /**home**/**jb**/**path**/**to**/**plugin**, and update everything else.

## Creating a plugin

Plugins can include any number of files in `functions`, `conf.d`, and `completions` directories. Most plugins are just a single function or a [configuration snippet](https://fishshell.com/docs/current/index.html#configuration). Behold the anatomy of a typical plugin:

<pre>
<b>flipper</b>
├── <b>completions</b>
│   └── flipper.fish
├── <b>conf.d</b>
│   └── flipper.fish
└── <b>functions</b>
    └── flipper.fish
</pre>

Non `.fish` files and directories inside these locations will be copied to `$fisher_path` under `functions`, `conf.d`, or `completions` respectively.

### Event system

Fish [events](https://fishshell.com/docs/current/cmds/emit.html) notify plugins when they're being installed, updated, or removed.

> Keep in mind, `--on-event` functions must be loaded when their event is emitted. So, place your event handlers in the `conf.d` directory.

```fish
# Defined in flipper/conf.d/flipper.fish

function _flipper_install --on-event flipper_install
    # Set universal variables, create bindings, and other initialization logic.
end

function _flipper_update --on-event flipper_update
    # Migrate resources, print warnings, and other update logic.
end

function _flipper_uninstall --on-event flipper_uninstall
    # Erase "private" functions, variables, bindings, and other uninstall logic.
end
```

## Creating a theme

A theme is like any other Fish plugin, but with 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. Check out what a typical theme plugin looks like:

<pre>
<b>gills</b>
├── <b>conf.d</b>
│   └── gills.fish
└── <b>themes</b>
    └── gills.theme
</pre>

### 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 isn't configurable in Fish yet, but there's [a request to add that feature](https://github.com/fish-shell/fish-shell/issues/9456).

Fear not! You can easily solve this by symlinking Fisher's `themes` directory into your Fish config. First, backup any existing themes directory.

```console
mv $__fish_config_dir/themes $__fish_config_dir/themes.bak
```

Next, create a symlink for Fisher's themes directory.

```console
ln -s $fisher_path/themes $__fish_config_dir/themes
```

Want to use theme plugins and maintain your own local themes? You can do that too ([#708](https://github.com/jorgebucaran/fisher/issues/708)).

## Discoverability

While Fisher doesn't rely on a central plugin repository, discovering new plugins doesn't have to feel like navigating uncharted waters. To boost your plugin's visibility and make it easier for users to find, [add relevant topics 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) using [`fish-plugin`](https://github.com/topics/fish-plugin). By doing so, you're not only contributing to the Fisher community but also enabling users to explore new plugins and enhance their Fish shell experience. Don't let plugin discovery be a fishy business, tag your plugins today!

## Acknowledgments

Fisher started its journey in 2016 by [@jorgebucaran](https://github.com/jorgebucaran) as a shell configuration manager for Fish. Along the way, many helped shape it into what it is today. [Oh My Fish](https://github.com/oh-my-fish/oh-my-fish) paved the way as the first popular Fish framework. [@jethrokuan](https://github.com/jethrokuan) provided crucial support during the early years. [@PatrickF1](https://github.com/PatrickF1)'s candid feedback proved invaluable time and again. Bootstrapping Fisher was originally [@IlanCosman](https://github.com/IlanCosman)'s brilliant idea. Thank you to all our contributors! <3

## License

[MIT](LICENSE.md)


================================================
FILE: completions/fisher.fish
================================================
complete --command fisher --exclusive --long help --description "Print help"
complete --command fisher --exclusive --long version --description "Print version"
complete --command fisher --exclusive --condition __fish_use_subcommand --arguments install --description "Install plugins"
complete --command fisher --exclusive --condition __fish_use_subcommand --arguments update --description "Update installed plugins"
complete --command fisher --exclusive --condition __fish_use_subcommand --arguments remove --description "Remove installed plugins"
complete --command fisher --exclusive --condition __fish_use_subcommand --arguments list --description "List installed plugins matching regex"
complete --command fisher --exclusive --condition "__fish_seen_subcommand_from update remove" --arguments "(fisher list)"


================================================
FILE: functions/fisher.fish
================================================
function fisher --argument-names cmd --description "A plugin manager for Fish"
    set --query fisher_path || set --local fisher_path $__fish_config_dir
    set --local fisher_version 4.4.8
    set --local fish_plugins $__fish_config_dir/fish_plugins

    switch "$cmd"
        case -v --version
            echo "fisher, version $fisher_version"
        case "" -h --help
            echo "Usage: fisher install   <plugins...>  Install plugins"
            echo "       fisher remove    <plugins...>  Remove installed plugins" 
            echo "       fisher uninstall <plugins...>  Remove installed plugins (alias)" 
            echo "       fisher update    <plugins...>  Update installed plugins"
            echo "       fisher update                  Update all installed plugins"
            echo "       fisher list    [<regex>]       List installed plugins matching regex"
            echo "Options:"
            echo "       -v, --version  Print version"
            echo "       -h, --help     Print this help message"
            echo "Variables:"
            echo "       \$fisher_path  Plugin installation path. Default: $__fish_config_dir" | string replace --regex -- $HOME \~
        case ls list
            string match --entire --regex -- "$argv[2]" $_fisher_plugins
        case install update remove uninstall
            isatty || read --local --null --array stdin && set --append argv $stdin

            test "$cmd" = uninstall && set cmd remove

            set --local install_plugins
            set --local update_plugins
            set --local remove_plugins
            set --local arg_plugins $argv[2..-1]
            set --local old_plugins $_fisher_plugins
            set --local new_plugins

            test -e $fish_plugins && set --local file_plugins (string match --regex -- '^[^\s]+$' <$fish_plugins | string replace -- \~ ~)

            if ! set --query argv[2]
                if test "$cmd" != update
                    echo "fisher: Not enough arguments for command: \"$cmd\"" >&2 && return 1
                else if ! set --query file_plugins
                    echo "fisher: \"$fish_plugins\" file not found: \"$cmd\"" >&2 && return 1
                end
                set arg_plugins $file_plugins
            else if test "$cmd" = install && ! set --query old_plugins[1] 
                set --append arg_plugins $file_plugins
            end

            for plugin in $arg_plugins
                set plugin (test -e "$plugin" && realpath $plugin || string lower -- $plugin)
                contains -- "$plugin" $new_plugins || set --append new_plugins $plugin
            end

            if set --query argv[2]
                for plugin in $new_plugins
                    if contains -- "$plugin" $old_plugins
                        test "$cmd" = remove &&
                            set --append remove_plugins $plugin ||
                            set --append update_plugins $plugin
                    else if test "$cmd" = install
                        set --append install_plugins $plugin
                    else
                        echo "fisher: Plugin not installed: \"$plugin\"" >&2 && return 1
                    end
                end
            else
                for plugin in $new_plugins
                    contains -- "$plugin" $old_plugins &&
                        set --append update_plugins $plugin ||
                        set --append install_plugins $plugin
                end

                for plugin in $old_plugins
                    contains -- "$plugin" $new_plugins || set --append remove_plugins $plugin
                end
            end

            set --local pid_list
            set --local source_plugins
            set --local fetch_plugins $update_plugins $install_plugins
            set --local fish_path (status fish-path)

            echo (set_color --bold)fisher $cmd version $fisher_version(set_color normal)

            for plugin in $fetch_plugins
                set --local source (command mktemp -d)
                set --append source_plugins $source

                command mkdir -p $source/{completions,conf.d,themes,functions}

                $fish_path --command "
                    if test -e $plugin
                        command cp -Rf $plugin/* $source
                    else
                        set resp (command mktemp)
                        set temp (command mktemp -d)
                        set repo (string split -- \@ $plugin) || set repo[2] HEAD

                        if set path (string replace --regex -- '^(https://)?gitlab.com/' '' \$repo[1])
                            set name (string split -- / \$path)[-1]
                            set url https://gitlab.com/\$path/-/archive/\$repo[2]/\$name-\$repo[2].tar.gz
                        else
                            set url https://api.github.com/repos/\$repo[1]/tarball/\$repo[2]
                        end

                        echo Fetching (set_color --underline)\$url(set_color normal)

                        set http (command curl -q --silent -L -o \$resp -w %{http_code} \$url)

                        if test \"\$http\" = 200 && command tar -xzC \$temp -f \$resp 2>/dev/null
                            command cp -Rf \$temp/*/* $source
                        else if test \"\$http\" = 403
                            echo fisher: GitHub API rate limit exceeded \(HTTP 403\) >&2
                            command rm -rf $source
                        else
                            echo fisher: Invalid plugin name or host unavailable: \\\"$plugin\\\" >&2
                            command rm -rf $source
                        end

                        command rm -rf \$temp
                    end

                    set files $source/* && string match --quiet --regex -- .+\.fish\\\$ \$files
                " &

                set --append pid_list (jobs --last --pid)
            end

            wait $pid_list 2>/dev/null

            for plugin in $fetch_plugins
                if set --local source $source_plugins[(contains --index -- "$plugin" $fetch_plugins)] && test ! -e $source
                    if set --local index (contains --index -- "$plugin" $install_plugins)
                        set --erase install_plugins[$index]
                    else
                        set --erase update_plugins[(contains --index -- "$plugin" $update_plugins)]
                    end
                end
            end

            for plugin in $update_plugins $remove_plugins
                if set --local index (contains --index -- "$plugin" $_fisher_plugins)
                    set --local plugin_files_var _fisher_(string escape --style=var -- $plugin)_files

                    if contains -- "$plugin" $remove_plugins
                        for name in (string replace --filter --regex -- '.+/conf\.d/([^/]+)\.fish$' '$1' $$plugin_files_var)
                            emit {$name}_uninstall
                        end
                        printf "%s\n" Removing\ (set_color red --bold)$plugin(set_color normal) "         "$$plugin_files_var | string replace -- \~ ~
                        set --erase _fisher_plugins[$index]
                    end

                    command rm -rf (string replace -- \~ ~ $$plugin_files_var)

                    functions --erase (string replace --filter --regex -- '.+/functions/([^/]+)\.fish$' '$1' $$plugin_files_var)

                    for name in (string replace --filter --regex -- '.+/completions/([^/]+)\.fish$' '$1' $$plugin_files_var)
                        complete --erase --command $name
                    end

                    set --erase $plugin_files_var
                end
            end

            if set --query update_plugins[1] || set --query install_plugins[1]
                command mkdir -p $fisher_path/{functions,themes,conf.d,completions}
            end

            for plugin in $update_plugins $install_plugins
                set --local source $source_plugins[(contains --index -- "$plugin" $fetch_plugins)]
                set --local files $source/{functions,themes,conf.d,completions}/*

                if set --local index (contains --index -- $plugin $install_plugins)
                    set --local user_files $fisher_path/{functions,themes,conf.d,completions}/*
                    set --local conflict_files

                    for file in (string replace -- $source/ $fisher_path/ $files)
                        contains -- $file $user_files && set --append conflict_files $file
                    end

                    if set --query conflict_files[1] && set --erase install_plugins[$index]
                        echo -s "fisher: Cannot install \"$plugin\": please remove or move conflicting files first:" \n"        "$conflict_files >&2
                        continue
                    end
                end

                for file in (string replace -- $source/ "" $files)
                    command cp -RLf $source/$file $fisher_path/$file
                end

                set --local plugin_files_var _fisher_(string escape --style=var -- $plugin)_files

                set --query files[1] && set --universal $plugin_files_var (string replace -- $source $fisher_path $files | string replace -- ~ \~)

                contains -- $plugin $_fisher_plugins || set --universal --append _fisher_plugins $plugin
                contains -- $plugin $install_plugins && set --local event install || set --local event update

                printf "%s\n" Installing\ (set_color --bold)$plugin(set_color normal) "           "$$plugin_files_var | string replace -- \~ ~

                for file in (string match --regex -- '.+/[^/]+\.fish$' $$plugin_files_var | string replace -- \~ ~)
                    source $file
                    if set --local name (string replace --regex -- '.+conf\.d/([^/]+)\.fish$' '$1' $file)
                        emit {$name}_$event
                    end
                end
            end

            command rm -rf $source_plugins

            if set --query _fisher_plugins[1]
                set --local commit_plugins

                for plugin in $file_plugins
                    contains -- (string lower -- $plugin) (string lower -- $_fisher_plugins) && set --append commit_plugins $plugin
                end

                for plugin in $_fisher_plugins
                    contains -- (string lower -- $plugin) (string lower -- $commit_plugins) || set --append commit_plugins $plugin
                end

                string replace --regex -- $HOME \~ $commit_plugins >$fish_plugins
            else
                set --erase _fisher_plugins
                command rm -f $fish_plugins
            end

            set --local total (count $install_plugins) (count $update_plugins) (count $remove_plugins)

            test "$total" != "0 0 0" && echo (string join ", " (
                test $total[1] = 0 || echo "Installed $total[1]") (
                test $total[2] = 0 || echo "Updated $total[2]") (
                test $total[3] = 0 || echo "Removed $total[3]")
            ) plugin/s
        case \*
            echo "fisher: Unknown command: \"$cmd\"" >&2 && return 1
    end
end

if ! set --query _fisher_upgraded_to_4_4
    set --universal _fisher_upgraded_to_4_4
    if functions --query _fisher_list
        set --query XDG_DATA_HOME[1] || set --local XDG_DATA_HOME ~/.local/share
        command rm -rf $XDG_DATA_HOME/fisher
        functions --erase _fisher_{list,plugin_parse}
        fisher update >/dev/null 2>/dev/null
    else
        for var in (set --names | string match --entire --regex '^_fisher_.+_files$')
            set $var (string replace -- ~ \~ $$var)
        end
        functions --erase _fisher_fish_postexec
    end
end


================================================
FILE: tests/fisher.fish
================================================
set --local BASENAME --regex -- '[^/]+$'

@echo (fisher --version)

@test "fisher install" (
    fisher install tests/ponyo >/dev/null 
) "$ponyo" = "pyon pyon"

@test "fisher list" (
    fisher list | string match $BASENAME | string join " "
) = "fisher fishtape ponyo"

@test "fisher list regex" (
    fisher list ponyo | string match $BASENAME
) = ponyo

@test "pyon pyon" (fish --command ponyo | string join " ") = "pyon pyon ponyo"

@test "fisher update" (
    fisher update tests/ponyo >/dev/null
) "$ponyo" = "pyon pyon pyon"

@test fish_plugins (
    string match --regex -- "[^/]+\$" <$__fish_config_dir/fish_plugins | string join " "
) = "fisher fishtape ponyo"

@test "fisher remove" (
    fisher remove tests/ponyo >/dev/null
) "$ponyo" = ""

@test "has state" -n (
    set --names | string match \*fisher\* | string collect
)


================================================
FILE: tests/ponyo/conf.d/ponyo.fish
================================================
echo pyon pyon

function ponyo_install --on-event ponyo_install
    set --global ponyo pyon pyon
end

function ponyo_update --on-event ponyo_update
    set --global --append ponyo pyon
end

function ponyo_uninstall --on-event ponyo_uninstall
    set --erase ponyo
end

================================================
FILE: tests/ponyo/functions/ponyo.fish
================================================
function ponyo
    echo ponyo
end