Where can I find a complete reference for the $PS1 variable?

The default PS1 variable on my machine (Kubuntu 13.10) is this:

\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\u@\h:\w\$

I'm looking for a reference for how the $PS1 variable works that, at a minimum, allows me to understand the above PS1 variable.

References

So far, there hasn't been a single reference for everything that can go in a Bash prompt - but as it's a feature that has evolved over decades and probably varies from distro to distro, maybe that's too much to ask. I've tried to summarise what I found most useful here.

This how-to is the most complete, but is very long and rambling. Some of the more useful sections:

• Section 2.4 and 2.5 explain the basics of setting PS1, including the (printable) escape characters.
• Section 3.4 explains why \[ and \] are necessary.
• Section 6 explains all the main (non-printable) escape sequences you might want to use, including setting the colour of the prompt and the title of an xterm window.

This guide explains how ${} works in Bash in general, and this Ask Ubuntu question explains a bit more about how that works with debian_chroot.

Between those, I think every character in the default Ubuntu PS1 variable is explained.

Explanation of the Ubuntu prompt

There are three parts to the prompt:

• \[\e]0;\u@\h: \w\a\] sets the title bar of an xterm window:

  • \[ starts a section of non-printable characters
  • \e]0; is the escape sequence for 'set xterm title' (I believe numbers other than 0 will set other xterm properties, though I haven't tested this)
  • \u@\h: \w the title to use (see below for \u, \h and \w)
  • \a marks the end of the title
  • \] marks the end of non-printable characters

• ${debian_chroot:+($debian_chroot)} expands to the value of $debian_chroot in parentheses if $debian_chroot is set. See this question for more information about $debian_chroot.

• \u@\h:\w\$ is the prompt itself:

  • \u expands to the current username
  • \h expands to the current hostname
  • \w expands to the current working directory
  • \$ expands to # for root and $ for all other users

According with Bash Reference Manual, PS1 is:

The primary prompt string. The default value is \s-\v\$. See Controlling a Prompt, for the complete list of escape sequences that are expanded before PS1 is displayed.

Some others good references can be:

• PS1 prompt explained for Linux/Unix

• What does "${debian_chroot:+($debian_chroot)}" do in my terminal prompt?

• Bash Shell PS1: 10 Examples to Make Your Linux Prompt like Angelina Jolie

ss64.com seems to have the best reference I've found.

It explains the following variables:

\d   The date, in "Weekday Month Date" format (e.g., "Tue May 26"). 

\h   The hostname, up to the first . (e.g. deckard) 
\H   The hostname. (e.g. deckard.SS64.com)

\j   The number of jobs currently managed by the shell. 

\l   The basename of the shell's terminal device name. 

\s   The name of the shell, the basename of $0 (the portion following 
    the final slash). 

\t   The time, in 24-hour HH:MM:SS format. 
\T   The time, in 12-hour HH:MM:SS format. 
\@   The time, in 12-hour am/pm format. 

\u   The username of the current user. 

\v   The version of Bash (e.g., 2.00) 

\V   The release of Bash, version + patchlevel (e.g., 2.00.0) 

\w   The current working directory. 
\W   The basename of $PWD. 

\!   The history number of this command. 
\#   The command number of this command. 

\$   If you are not root, inserts a "$"; if you are root, you get a "#"  (root uid = 0) 

\nnn   The character whose ASCII code is the octal value nnn. 

\n   A newline. 
\r   A carriage return. 
\e   An escape character. 
\a   A bell character.
\\   A backslash. 

\[   Begin a sequence of non-printing characters. (like color escape sequences). This
     allows bash to calculate word wrapping correctly.

\]   End a sequence of non-printing characters.

The \[ ... \] defines a series of non-printing characters. They are required to keep track of the cursor position correctly.

The \e in your prompt starts an escape sequence. More on those here (note "Esc" on that page is the \e sequence).

• Note: I've never really liked escape sequences. Use tput to get the escape code for you.

${debian_chroot:+($debian_chroot)} is parameter expansion. See here

• It writes ($debian_chroot) if $debian_chroot is set otherwise nothing.