--- name: "fish-prompt-tutorial" section: "1" platform: "linux" package: "fish" version: "4.9.3-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fish-prompt-tutorial" --- # fish-prompt-tutorial(1) **Warning:** 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 **help custom-prompt** to view it in a web browser. fish ships a number of prompts that you can view with the fish\_config \<\> command, and many users have shared their prompts online. However, you can also write your own, or adjust an existing prompt. This is a good way to get used to fish's scripting language \<\>. Unlike other shells, fish's prompt is built by running a function - fish\_prompt \<\>. Or, more specifically, three functions: - • fish\_prompt \<\>, which is the main prompt function - • fish\_right\_prompt \<\>, which is shown on the right side of the terminal. - • fish\_mode\_prompt \<\>, which is shown if vi mode \<#vi-mode\> is used. These functions are run, and whatever they print is displayed as the prompt (minus one trailing newline). If the **SHELL\_PROMPT\_PREFIX** \<#envvar-SHELL\_PROMPT\_PREFIX\> or **SHELL\_PROMPT\_SUFFIX** \<#envvar-SHELL\_PROMPT\_SUFFIX\> environment variables are set, they are automatically prepended and appended to the left prompt. Here, we will just be writing a simple fish\_prompt. ## OUR FIRST PROMPT Let's look at a very simple example: ``` function fish_prompt echo $PWD '>' end ``` This prints the current working directory (**PWD** \<#envvar-PWD\>) and a **\>** symbol to show where the prompt ends. The **\>** is quoted \<#quotes\> because otherwise it would signify a redirection \<#redirects\>. Because we've used echo \<\>, it adds spaces between the two so it ends up looking like (assuming **\_** is your cursor): ``` /home/tutorial >_ ``` ## FORMATTING **echo** adds spaces between its arguments. If you don't want those, you can use string join \<\> like this: ``` function fish_prompt string join '' -- $PWD '>' end ``` The **--** indicates to **string** that no options can come after it, in case we extend this with something that can start with a **-**. There are other ways to remove the space, including **echo -s** and printf \<\>. ## ADDING COLOR This prompt is functional, but a bit boring. We could add some color. Fortunately, fish offers the set\_color \<\> command, so you can do: ``` echo (set_color red)foo ``` **set\_color** can also handle RGB colors like **set\_color 23b455**, and other formatting options including bold and italics. So, taking our previous prompt and adding some color: ``` function fish_prompt string join '' -- (set_color green) $PWD (set_color --reset) '>' end ``` "--reset" tells the terminal to go back to its default formatting options. **set\_color** works by producing an escape sequence, which is a special piece of text that terminals interpret as instructions - for example, to change color. So **set\_color red** produces the same effect as: ``` echo \e\[31m ``` Although you can write your own escape sequences by hand, it's much easier to use **set\_color**. ## SHORTENING THE WORKING DIRECTORY This is fine, but our **PWD** \<#envvar-PWD\> can be a bit long, and we are typically only interested in the last few directories. We can shorten this with the prompt\_pwd \<\> helper that will give us a shortened working directory: ``` function fish_prompt string join '' -- (set_color green) (prompt_pwd) (set_color --reset) '>' end ``` **prompt\_pwd** takes options to control how much to shorten. For instance, if we want to display the last two directories, we'd use **prompt\_pwd --full-length-dirs 2**: ``` function fish_prompt string join '' -- (set_color green) (prompt_pwd --full-length-dirs 2) (set_color --reset) '>' end ``` With a current directory of "/home/tutorial/Music/Lena Raine/Oneknowing", this would print ``` ~/M/Lena Raine/Oneknowing>_ ``` ## STATUS One important bit of information that every command returns is the status \<#variables-status\>. 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. It's useful to display this in your prompt, but showing it when it's 0 seems kind of wasteful. First of all, since every command (except for set \<\>) changes the status, you need to store it for later use as the first thing in your prompt. Use a local variable \<#variables-scope\> so it will be confined to your prompt function: ``` set -l last_status $status ``` And after that, you can set a string if it is not zero: ``` # Prompt status only if it's not 0 set -l stat if test $last_status -ne 0 set stat (set_color red)"[$last_status]"(set_color --reset) end ``` And to print it, we add it to our **string join**: ``` string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $stat '>' ``` If **$last\_status** was 0, **$stat** is empty, and so it will simply disappear. So our entire prompt is now: ``` function fish_prompt set -l last_status $status # Prompt status only if it's not 0 set -l stat if test $last_status -ne 0 set stat (set_color red)"[$last_status]"(set_color --reset) end string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $stat '>' end ``` And it looks like: ``` ~/M/L/Oneknowing>false ~/M/L/Oneknowing[1]>_ ``` after we run **false** (which returns 1). ## TRANSIENT PROMPT To enable transient prompt functionality, set the **fish\_transient\_prompt** \<#envvar-fish\_transient\_prompt\> variable to 1: ``` set -g fish_transient_prompt 1 ``` With this set, fish re-runs prompt functions with a **--final-rendering** argument before running a commandline. So you can use it to declutter your old prompts. For example if you want to see only the current directory name when you scroll up: ``` function fish_prompt set -l last_status $status set -l stat set -l pwd # Check if it's a transient or final prompt if contains -- --final-rendering $argv set pwd (path basename $PWD) else set pwd (prompt_pwd) # Prompt status only if it's not 0 if test $last_status -ne 0 set stat (set_color red)"[$last_status]"(set_color --reset) end end string join '' -- (set_color green) $pwd (set_color --reset) $stat '>' end ``` Now running two commands in the same directory could result in this screen: ``` Oneknowing>false ~/M/L/Oneknowing[1]>_ ``` ## SAVE THE PROMPT Once you are happy with your prompt, you can save it with **funcsave fish\_prompt** (see funcsave - save the definition of a function to the user's autoload directory \<\>) or write it to ~/.config/fish/functions/fish\_prompt.fish yourself. If you want to edit it again, open that file or use **funced fish\_prompt** (see funced - edit a function interactively \<\>). ## WHERE TO GO FROM HERE? We have now built a simple but working and usable prompt, but of course more can be done. - • - **fish offers more helper functions:** - • **prompt\_login** to describe the user/hostname/container or **prompt\_hostname** to describe just the host - • **fish\_is\_root\_user** to help with changing the symbol for root. - • **fish\_vcs\_prompt** to show version control information (or **fish\_git\_prompt** / **fish\_hg\_prompt** / **fish\_svn\_prompt** to limit it to specific systems) - • You can add a right prompt by changing fish\_right\_prompt \<\> or a vi mode prompt by changing fish\_mode\_prompt \<\>. - • - **Some prompts have interesting or advanced features** - • Add the time when the prompt was printed - • Show various integrations like python's venv - • Color the parts differently. You can look at fish's sample prompts for inspiration. Open up fish\_config \<\>, find one you like and pick it. For example: ``` fish_config prompt show # <- shows all the sample prompts fish_config prompt choose disco # <- this picks the "disco" prompt for this session funced fish_prompt # <- opens fish_prompt in your editor, and reloads it once the editor exits ``` ## Author fish-shell developers ## Copyright fish-shell developers