fisher/man/man7/fisher-tutorial.7

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "FISHER\-TUTORIAL" "7" "February 2016" "" "fisherman"
.
.SH "NAME"
\fBfisher\-tutorial\fR \- A tutorial introduction to Fisherman
.
.SH "DESCRIPTION"
This document tells you how to start using Fisherman key features\.
.
.SH "INSTALLING PLUGINS"
Install a plugin\.
.
.IP "" 4
.
.nf

fisher install <plugin>
.
.fi
.
.IP "" 0
.
.P
\fIplugin\fR 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\.
.
.SH "UPDATE AND UNINSTALL"
Update a plugin\.
.
.IP "" 4
.
.nf

fisher update <plugin>
.
.fi
.
.IP "" 0
.
.P
Uninstall a plugin\.
.
.IP "" 4
.
.nf

fisher uninstall <plugin>
.
.fi
.
.IP "" 0
.
.SH "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\.
.
.P
List installed plugins\.
.
.IP "" 4
.
.nf

fisher list
  debug
* fishtape
> shellder
* spin
@ wipe
.
.fi
.
.IP "" 0
.
.P
The legend consists of:
.
.P
\fB*\fR Indicate the plugin is currently installed
.
.br
\fB>\fR Indicate the plugin is a prompt
.
.br
\fB@\fR Indicate the plugin is a symbolic link
.
.br
.
.P
Search the index\.
.
.IP "" 4
.
.nf

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
  \.\.\.
.
.fi
.
.IP "" 0
.
.P
Get detailed information about a plugin\.
.
.IP "" 4
.
.nf

fisher search shellder
> shellder by simnalamburt
Powerline prompt optimized for speed
github\.com/simnalamburt/shellder
.
.fi
.
.IP "" 0
.
.P
Search plugins using tags\.
.
.IP "" 4
.
.nf

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
  \.\.\.
.
.fi
.
.IP "" 0
.
.SH "PLUMBING"
Fisherman commands are pipe aware\. Plumb one with another to create complex functionality\.
.
.P
Update all the plugins in the cache\.
.
.IP "" 4
.
.nf

fisher list | fisher update \-
.
.fi
.
.IP "" 0
.
.P
Install all the plugins that are currently disabled\.
.
.IP "" 4
.
.nf

fisher list \-\-disabled | fisher install
.
.fi
.
.IP "" 0
.
.SH "DOTFILES"
When you install a plugin, Fisherman updates a file known as \fIfishfile\fR to track what plugins are currently enabled\.
.
.P
To customize its location:
.
.IP "" 4
.
.nf

set \-g fisher_file ~/\.dotfiles/fishfile
.
.fi
.
.IP "" 0
.
.SH "PLUGINS"
Plugins can be utilities, prompts, commands or snippets\.
.
.SS "UTILITIES"
Utilities are plugins that define one or more functions which are mean to be used in the CLI directly by the user\.
.
.P
This example walks you through creating \fIwtc\fR, a plugin based in \fIgithub/ngerakines/commitment\fR random commit message generator\.
.
.IP "\(bu" 4
Create a directory and initialize a Git repository\.
.
.IP "" 0
.
.IP "" 4
.
.nf

mkdir wtc
cd wtc
git init
git remote add origin https://github\.com/<you>/wtc
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Add the wtc function\.
.
.IP "" 0
.
.IP "" 4
.
.nf

function wtc \-d "Generate a random commit message"
    switch "$argv"
        case \-h \-\-help
            printf "Usage: wtc [\-\-help]\en\en"
            printf "  \-h \-\-help  Show usage help\en"
            return
    end
    curl \-s whatthecommit\.com/index\.txt
end
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Install the plugin\.
.
.IP "" 0
.
.IP "" 4
.
.nf

fisher install \.
wtc
(\e /)
(O\.o)
(> <) Bunny approves these changes\.
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Commit changes and push to your remote origin when you are done\.
.
.IP "" 0
.
.IP "" 4
.
.nf

git add \-\-all
git commit \-m "What the commit?"
git push origin master
.
.fi
.
.IP "" 0
.
.P
To submit wtc to the official index\.
.
.IP "" 4
.
.nf

fisher install submit
fisher submit
.
.fi
.
.IP "" 0
.
.P
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\.
.
.IP "" 4
.
.nf

fisher install wtc
.
.fi
.
.IP "" 0
.
.P
See \fBfisher help submit\fR for more submit options\.
.
.P
Create a completions directory and add a completions file\.
.
.IP "" 4
.
.nf

mkdir completions
cat > completions/wtc\.fish
complete \-\-command wtc \-\-short h \-\-long help \-\-description "Show usage help"
^
.
.fi
.
.IP "" 0
.
.P
Alternatively, use \fB__fisher_complete\fR to create completions from wtc usage output\.
.
.IP "" 4
.
.nf

wtc \-\-help | __fisher_complete wtc
.
.fi
.
.IP "" 0
.
.P
Create a man/man1 directory and add a man(1) page for wtc\.
.
.P
There are utilities that can help you generate man pages from various text formats\. For example, pandoc(1) and ronn(1)\.
.
.P
To create a man page manually\.
.
.IP "" 4
.
.nf

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

 \.TH man 1 "Today" "1\.0" "wtc man page"
 \.SH NAME
 wtc \e\- 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
.
.fi
.
.IP "" 0
.
.P
A plugin can list dependencies to other plugins using a \fIfishfile\fR\.
.
.P
Create a new file in the root of your project and add the name or URL of your desired dependencies\.
.
.IP "" 4
.
.nf

cat > fishfile
my_plugin
https://github\.com/owner/another_plugin
^D
.
.fi
.
.IP "" 0
.
.SS "PROMPTS"
Prompts, also known as themes, are plugins that modify the appearance of the shell prompt\.
.
.P
Create a \fBfish_prompt\fR function\.
.
.IP "" 4
.
.nf

function fish_prompt
    printf "%s (%s) >> " (prompt_pwd) Fisherman
end
~ (Fisherman) >> type here
.
.fi
.
.IP "" 0
.
.P
To add a right prompt, create a \fBfish_right_prompt\fR function\.
.
.IP "" 4
.
.nf

function fish_right_prompt
    printf "%s" (date +%H:%M:%S)
end
.
.fi
.
.IP "" 0
.
.P
Save the functions to a directory and install the prompt as a plugin\.
.
.IP "" 4
.
.nf

mkdir my_prompt
cd my_prompt
functions fish_prompt > fish_prompt\.fish
functions fish_right_prompt > fish_right_prompt\.fish
fisher install \.
.
.fi
.
.IP "" 0
.
.SS "COMMANDS"
Commands are plugins that extend the Fisherman CLI adding new \fBfisher <commands>\fR\.
.
.P
Create a function \fBfisher_<command>\fR
.
.IP "" 4
.
.nf

function fisher_time \-d "Say hello"
    printf "It\'s %s\en" (date +%H:%M)
end
.
.fi
.
.IP "" 0
.
.P
Test it works
.
.IP "" 4
.
.nf

fisher time
It\'s 6:30
.
.fi
.
.IP "" 0
.
.P
Make it a plugin
.
.IP "" 4
.
.nf

fisher install fisher_time
.
.fi
.
.IP "" 0
.
.P
This creates a new directory fisher_time in the current working directory and installs the plugin\.
.
.P
The following example implements a command to format plugin information into columns\.
.
.IP "" 4
.
.nf

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

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

fisher install fisher_info
.
.fi
.
.IP "" 0
.
.SS "SNIPPETS"
Snippets are plugins that run code at the start of the shell\. Snippets must be placed inside a sub directory named conf\.d\.
.
.P
The following example implements the fish_postexec hook to display the runtime of the last command in milliseconds\.
.
.IP "" 4
.
.nf

mkdir \-p runtime/conf\.d
cd runtime
cat > conf\.d/fish_postexec\.fish
function fish_postexec \-\-on\-event fish_postexec
    printf "%sms\en" $CMD_DURATION > /dev/stderr
end
^D
fisher install \./postexec
.
.fi
.
.IP "" 0
.
.SH "SEE ALSO"
fisher(1)