.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "FISH-PROMPT-TUTORIAL" "1" "Feb 28, 2025" "4.0" "fish-shell"
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This document uses formatting to show what a prompt would look like. If you are viewing this in the man page,
you probably want to switch to looking at the html version instead. Run \fBhelp custom\-prompt\fP to view it in a web browser.
.UNINDENT
.UNINDENT
.sp
Fish ships a number of prompts that you can view with the \fI\%fish_config\fP command, and many users have shared their prompts online.
.sp
However, you can also write your own, or adjust an existing prompt. This is a good way to get used to fish\(aqs \fI\%scripting language\fP\&.
.sp
Unlike other shells, fish\(aqs prompt is built by running a function \- \fI\%fish_prompt\fP\&. Or, more specifically, three functions:
.INDENT 0.0
.IP \(bu 2
\fI\%fish_prompt\fP, which is the main prompt function
.IP \(bu 2
\fI\%fish_right_prompt\fP, which is shown on the right side of the terminal.
.IP \(bu 2
\fI\%fish_mode_prompt\fP, which is shown if \fI\%vi mode\fP is used.
.UNINDENT
.sp
These functions are run, and whatever they print is displayed as the prompt (minus one trailing newline).
.sp
Here, we will just be writing a simple fish_prompt.
.SH OUR FIRST PROMPT
.sp
Let\(aqs look at a very simple example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    echo $PWD \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
This prints the current working directory (\fI\%PWD\fP) and a \fB>\fP symbol to show where the prompt ends. The \fB>\fP is \fI\%quoted\fP because otherwise it would signify a \fI\%redirection\fP\&.
.sp
Because we\(aqve used \fI\%echo\fP, it adds spaces between the two so it ends up looking like (assuming \fB_\fP is your cursor):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/home/tutorial >_
.EE
.UNINDENT
.UNINDENT
.SH FORMATTING
.sp
\fBecho\fP adds spaces between its arguments. If you don\(aqt want those, you can use \fI\%string join\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- $PWD \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
The \fB\-\-\fP indicates to \fBstring\fP that no options can come after it, in case we extend this with something that can start with a \fB\-\fP\&.
.sp
There are other ways to remove the space, including \fBecho \-s\fP and \fI\%printf\fP\&.
.SH ADDING COLOR
.sp
This prompt is functional, but a bit boring. We could add some color.
.sp
Fortunately, fish offers the \fI\%set_color\fP command, so you can do:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo (set_color red)foo
.EE
.UNINDENT
.UNINDENT
.sp
\fBset_color\fP can also handle RGB colors like \fBset_color 23b455\fP, and other formatting options including bold and italics.
.sp
So, taking our previous prompt and adding some color:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) $PWD (set_color normal) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
A \(dqnormal\(dq color tells the terminal to go back to its normal formatting options.
.sp
\fBset_color\fP works by producing an escape sequence, which is a special piece of text that terminals
interpret as instructions \- for example, to change color. So \fBset_color red\fP produces the same
effect as:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo \ee\e[31m
.EE
.UNINDENT
.UNINDENT
.sp
Although you can write your own escape sequences by hand, it\(aqs much easier to use \fBset_color\fP\&.
.SH SHORTENING THE WORKING DIRECTORY
.sp
This is fine, but our \fI\%PWD\fP can be a bit long, and we are typically only interested in the last few directories. We can shorten this with the \fI\%prompt_pwd\fP helper that will give us a shortened working directory:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color normal) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
\fBprompt_pwd\fP takes options to control how much to shorten. For instance, if we want to display the last two directories, we\(aqd use \fBprompt_pwd \-\-full\-length\-dirs 2\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    string join \(aq\(aq \-\- (set_color green) (prompt_pwd \-\-full\-length\-dirs 2) (set_color normal) \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
With a current directory of \(dq/home/tutorial/Music/Lena Raine/Oneknowing\(dq, this would print
.INDENT 0.0
.INDENT 3.5
.sp
.EX
~/M/Lena Raine/Oneknowing>_
.EE
.UNINDENT
.UNINDENT
.SH STATUS
.sp
One important bit of information that every command returns is the \fI\%status\fP\&. This is a whole number from 0 to 255, and usually it is used as an error code \- 0 if the command returned successfully, or a number from 1 to 255 if not.
.sp
It\(aqs useful to display this in your prompt, but showing it when it\(aqs 0 seems kind of wasteful.
.sp
First of all, since every command (except for \fI\%set\fP) changes the status, you need to store it for later use as the first thing in your prompt. Use a \fI\%local variable\fP so it will be confined to your prompt function:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
set \-l last_status $status
.EE
.UNINDENT
.UNINDENT
.sp
And after that, you can set a string if it is not zero:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Prompt status only if it\(aqs not 0
set \-l stat
if test $last_status \-ne 0
    set stat (set_color red)\(dq[$last_status]\(dq(set_color normal)
end
.EE
.UNINDENT
.UNINDENT
.sp
And to print it, we add it to our \fBstring join\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color normal) $stat \(aq>\(aq
.EE
.UNINDENT
.UNINDENT
.sp
If \fB$last_status\fP was 0, \fB$stat\fP is empty, and so it will simply disappear.
.sp
So our entire prompt is now:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
function fish_prompt
    set \-l last_status $status
    # Prompt status only if it\(aqs not 0
    set \-l stat
    if test $last_status \-ne 0
        set stat (set_color red)\(dq[$last_status]\(dq(set_color normal)
    end

    string join \(aq\(aq \-\- (set_color green) (prompt_pwd) (set_color normal) $stat \(aq>\(aq
end
.EE
.UNINDENT
.UNINDENT
.sp
And it looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
~/M/L/Oneknowing[1]>_
.EE
.UNINDENT
.UNINDENT
.sp
after we run \fBfalse\fP (which returns 1).
.SH SAVE THE PROMPT
.sp
Once you are happy with your prompt, you can save it with \fBfuncsave fish_prompt\fP (see \fI\%funcsave \- save the definition of a function to the user\(aqs autoload directory\fP) or write it to ~/.config/fish/functions/fish_prompt.fish yourself.
.sp
If you want to edit it again, open that file or use \fBfunced fish_prompt\fP (see \fI\%funced \- edit a function interactively\fP).
.SH WHERE TO GO FROM HERE?
.sp
We have now built a simple but working and usable prompt, but of course more can be done.
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B Fish offers more helper functions:
.INDENT 7.0
.IP \(bu 2
\fBprompt_login\fP to describe the user/hostname/container or \fBprompt_hostname\fP to describe just the host
.IP \(bu 2
\fBfish_is_root_user\fP to help with changing the symbol for root.
.IP \(bu 2
\fBfish_vcs_prompt\fP to show version control information (or \fBfish_git_prompt\fP / \fBfish_hg_prompt\fP / \fBfish_svn_prompt\fP to limit it to specific systems)
.UNINDENT
.UNINDENT
.IP \(bu 2
You can add a right prompt by changing \fI\%fish_right_prompt\fP or a vi mode prompt by changing \fI\%fish_mode_prompt\fP\&.
.IP \(bu 2
.INDENT 2.0
.TP
.B Some prompts have interesting or advanced features
.INDENT 7.0
.IP \(bu 2
Add the time when the prompt was printed
.IP \(bu 2
Show various integrations like python\(aqs venv
.IP \(bu 2
Color the parts differently.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
You can look at fish\(aqs sample prompts for inspiration. Open up \fI\%fish_config\fP, find one you like and pick it. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
fish_config prompt show # <\- shows all the sample prompts
fish_config prompt choose disco # <\- this picks the \(dqdisco\(dq prompt for this session
funced fish_prompt # <\- opens fish_prompt in your editor, and reloads it once the editor exits
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
fish-shell developers
.SH COPYRIGHT
2024, fish-shell developers
.\" Generated by docutils manpage writer.
.