1. Introduction and Administrivia

1.1 Requirements

You will need Bash. The default version for most distributions is either 1.14.7, or 2.0.x. 1.14.7 was the standard for years, but is slowly being replaced. I've been using Bash 2.0.x for quite a while now, but almost all code presented here should work under 1.14.7. If I'm aware of a problem, I'll mention it. You can check your Bash version by typing echo $BASH_VERSION at the prompt. On my machine, it responds with 2.03.6(1)-release.

Shell programming experience would be good, but isn't essential: the more you know, the more complex the prompts you'll be able to create. I assume a basic knowledge of shell programming and Unix utilities as I go through this tutorial. However, my own shell programming skills are limited, so I give a lot of examples and explanation that may appear unnecessary to an experienced shell programmer.

1.2 How To Use This Document

I include a lot of examples and explanatory text. Different parts will be of varying usefulness to different people. This has grown long enough that reading it straight through would be difficult - just read the sections you need, backtrack as necessary.

1.3 Translations

Japanese: http://www.jf.linux.or.jp/JF/JF-ftp/other-formats/Bash-Prompt/Bash-Prompt-HOWTO.html, provided by Akira Endo, [email protected].

German: translation is in progress by Thomas Keil, [email protected].

Italian: by Daniel Dui, [email protected], available at http://www.crs4.it/~dui/linux.html.

Portugese: translation is in progress by Mário Gamito, [email protected].

Spanish: translation by Iosu Santurtún [email protected] at http://mipagina.euskaltel.es/iosus/linux/Bash-Prompt-HOWTO.html.

Dutch: translation is in progress by Ellen Bokhorst [email protected], and it will be available at http://www.nl.linux.org/doc/HOWTO.

Chinese: translation in progress by Allen Huang [email protected]. I will include a URL when I have it.

Many thanks to all of them! URLs will be included as they're available.

If you are working on a translation, please notify me - especially if it's available at a linkable URL. Thanks.

1.4 Problems

This is a list of problems I've noticed while programming prompts. Don't start reading here, and don't let this list discourage you - these are mostly quite minor details. Just check back if you run into anything odd.

• Many Bash features (such as math within $(()) among others) are compile time options. If you're using a binary distribution such as comes with a standard Linux distribution, all such features should be compiled in. But if you're working on someone else's system, this is worth keeping in mind if something you expected to work doesn't. Some notes about this in Learning the Bash Shell, p.260-262.
• The terminal screen manager "screen" doesn't always get along with ANSI colours. I'm not a screen expert, unfortunately. My current version of screen (3.7.6-1, an RPM package) seems to work well in all cases, but I've seen occasions where screen reduced all prompt colours to the standard foreground colour in X terminals. This doesn't appear to be a problem on the console.
• Xdefaults files can override colours. Look in ~/.Xdefaults for lines referring to XTerm*background and XTerm*foreground (or possibly XTerm*Background and XTerm*Foreground).
• One of the prompts mentioned in this document uses the output of "jobs" - as discussed at that time, "jobs" output to a pipe is broken in Bash 2.02.
• ANSI cursor movement escape sequences aren't all implemented in all X terminals. That's discussed in its own section.
• Some nice looking pseudo-graphics can be created by using a VGA font rather than standard Linux fonts. Unfortunately, these effects look awful if you don't use a VGA font, and there's no way to detect within a term what kind of font it's using.
• Bash 2.0+ is out, and it incorporates some new features, and changes some behaviour. Things that work under 1.14.7 don't necessarily work the same under 2.0+, or vice versa.

1.5 Send Me Comments and Suggestions

This is a learning experience for me. I've come to know a fair bit about what can be done to create interesting and useful Bash Prompts, but I need your input to correct and improve this document. I've tried to check suggestions I make against different versions of Bash (2.0x and 1.14.7), but let me know of any incompatibilities you find.

The latest version of this document should always be available at http://www.interlog.com/~giles/bashprompt/. Please check this out, and feel free to e-mail me at [email protected] with suggestions.

I use the Linux Documentation Project HOWTOs almost exclusively in the HTML format, so when I convert this from SGML (its native format), HTML is the only format I check thoroughly. If there are problems with other formats, I may not know about them, and I'd appreciate a note about them.

1.6 Credits

In producing this document, I have borrowed heavily from the work of the Bashprompt project at http://bash.current.nu/. Other sources used include the xterm Title mini-HOWTO by Ric Lister, available at http://sunsite.unc.edu/LDP/HOWTO/mini/Xterm-Title.html, Ansi Prompts by Keebler, available at http://www.ncal.verio.com/~keebler/ansi.html, How to make a Bash Prompt Theme by Stephen Webb, available at http://bash.current.nu/bash/HOWTO.html, and X ANSI Fonts by Stumpy, available at http://home.earthlink.net/~us5zahns/enl/ansifont.html.

Also of immense help were several conversations and e-mails from Dan, an ex-co-worker at Georgia College & State University, whose knowledge of Unix far exceeds mine. He's given me several excellent suggestions, and ideas of his have led to some interesting prompts.

Three books that have been very useful while programming prompts are Linux in a Nutshell by Jessica Heckman Perry (O'Reilly, 1997), Learning the Bash Shell by Cameron Newham and Bill Rosenblatt (O'Reilly, 2nd. ed., 1998) and Unix Shell Programming by Lowell Jay Arthur (Wiley, 1986. This is the first edition, the fourth came out in 1997).

1.7 Copyright and Disclaimer

This document is copyright 1998-1999 by Giles Orr. You are encouraged to redistribute it. You may not modify this document (see the section on contacting me: I incorporate most changes recommended by readers). Please contact me if you're interested in doing a translation.

This document is available for free, and, while I have done the best I can to make it accurate and up to date, I take no responsibility for any problems you may encounter resulting from the use of this document.