fisher/man/man7/fisher-tutorial.md

fisher-tutorial(7) -- A tutorial introduction to Fisherman

DESCRIPTION

This document tells you how to start using Fisherman key features.

INSTALLING PLUGINS

Install a plugin.

fisher install <plugin>

plugin can be name registered in the Fisherman index, a URL to a Git repository or a path in the local system. Plugins are collected in a special location inside the Fisherman's configuration directory known as the cache.

UPDATE AND UNINSTALL

Update a plugin.

fisher update <plugin>

Uninstall a plugin.

fisher uninstall <plugin>

LIST AND SEARCH

The list command displays all the plugins you have installed. The search command queries the index to show what's available to install.

List installed plugins.

fisher list
  debug
* fishtape
> shellder
* spin
@ wipe

The legend consists of:

* Indicate the plugin is currently installed
> Indicate the plugin is a prompt
@ Indicate the plugin is a symbolic link

Search the index.

fisher search
  ...
* debug        Conditional debug logger
  errno        POSIX error code/string translator
* fishtape     TAP producing test runner
  flash        Flash-inspired, thunder prompt
  fzf          Efficient keybindings for fzf
  get          Press any key to continue
  ...
> shellder     Powerline prompt optimized for speed
  ...

Get detailed information about a plugin.

fisher search shellder
> shellder by simnalamburt
Powerline prompt optimized for speed
github.com/simnalamburt/shellder

Search plugins using tags.

fisher search --tag={git,test}
  ...
* fishtape           TAP producing test runner
  git-branch-name    Get the name of the current Git branch
  git-is-repo        Test if the current directory is a Git repo
  git-is-dirty       Test if there are changes not staged for commit
  git-is-stashed     Test if there are changes in the stash
  ...

PLUMBING

Fisherman commands are pipe aware. Plumb one with another to create complex functionality.

Update all the plugins in the cache.

fisher list | fisher update -

Install all the plugins that are currently disabled.

fisher list --disabled | fisher install

DOTFILES

When you install a plugin, Fisherman updates a file known as fishfile to track what plugins are currently enabled.

To customize its location:

set -g fisher_file ~/.dotfiles/fishfile

PLUGINS

Plugins can be utilities, prompts, commands or snippets.

UTILITIES

Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user.

This example walks you through creating wtc, a plugin based in github/ngerakines/commitment random commit message generator.

• Create a directory and initialize a Git repository.

mkdir wtc
cd wtc
git init
git remote add origin https://github.com/<you>/wtc

• Add the wtc function.

function wtc -d "Generate a random commit message"
    switch "$argv"
        case -h --help
            printf "Usage: wtc [--help]\n\n"
            printf "  -h --help  Show usage help\n"
            return
    end
    curl -s whatthecommit.com/index.txt
end

• Install the plugin.

fisher install .
wtc
(\ /)
(O.o)
(> <) Bunny approves these changes.

• Commit changes and push to your remote origin when you are done.

git add --all
git commit -m "What the commit?"
git push origin master

SUBMIT

To submit wtc to the official index.

fisher install submit
fisher submit

This will create a PR in the Fisherman index repository. Once the PR is approved, Fisherman users will be able to install wtc if they have the latest index.

fisher install wtc

See fisher help submit for more submit options.

COMPLETIONS

Create a completions directory and add a completions file.

mkdir completions
cat > completions/wtc.fish
complete --command wtc --short h --long help --description "Show usage help"
^

Alternatively, use __fisher_complete to create completions from wtc usage output.

wtc --help | __fisher_complete wtc

MAN

Create a man/man1 directory and add a man(1) page for wtc.

There are utilities that can help you generate man pages from various text formats. For example, pandoc(1) and ronn(1).

To create a man page manually.

mkdir -p man/man1
cat > man/man1/wtc.1

 .TH man 1 "Today" "1.0" "wtc man page"
 .SH NAME
 wtc \- Generate a random commit message
 .SH SYNOPSIS
 wtc [--help]
 .SH OPTIONS
 -h, --help: Display help information.
 .SH SEE ALSO
 https://github.com/ngerakines/commitment
^C

DEPENDENCIES

A plugin can list dependencies to other plugins using a fishfile.

Create a new file in the root of your project and add the name or URL of your desired dependencies.

cat > fishfile
my_plugin
https://github.com/owner/another_plugin
^D

PROMPTS

Prompts, also known as themes, are plugins that modify the appearance of the shell prompt.

Create a fish_prompt function.

function fish_prompt
    printf "%s (%s) >> " (prompt_pwd) Fisherman
end
~ (Fisherman) >> type here

To add a right prompt, create a fish_right_prompt function.

function fish_right_prompt
    printf "%s" (date +%H:%M:%S)
end

Save the functions to a directory and install the prompt as a plugin.

mkdir my_prompt
cd my_prompt
functions fish_prompt > fish_prompt.fish
functions fish_right_prompt > fish_right_prompt.fish
fisher install .

COMMANDS

Commands are plugins that extend the Fisherman CLI adding new fisher <commands>.

Create a function fisher_<command>

function fisher_time -d "Say hello"
    printf "It's %s\n" (date +%H:%M)
end

Test it works

fisher time
It's 6:30

Make it a plugin

fisher install fisher_time

This creates a new directory fisher_time in the current working directory and installs the plugin.

The following example implements a command to format plugin information into columns.

function fisher_info -d "Display information about plugins"
    switch "$argv"
        case -h --help
            printf "Usage: fisher info <name or URL> [...]\n\n"
            printf "    -h --help  Show usage help\n"
            return
    end

    for item in $argv
        fisher search $item --name --info
    end | sed -E 's/;/: /' | column
end

fisher install fisher_info

SNIPPETS

Snippets are plugins that run code at the start of the shell. Snippets must be placed inside a sub directory named conf.d.

The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds.

mkdir -p runtime/conf.d
cd runtime
cat > conf.d/fish_postexec.fish
function fish_postexec --on-event fish_postexec
    printf "%sms\n" $CMD_DURATION > /dev/stderr
end
^D
fisher install ./postexec

SEE ALSO

fisher(1)