How to Use and Setup Emacs's whitespace-mode

This page tells you how to setup emacs's whitespace-mode (bundled with emacs 23), and how to use it.

whitespace-mode renders {spaces, tabs, newlines} characters with a visible glyph. This feature is useful for working with “comma/tab separated values” (CSV, TSV) that's commonly used format for importing/exporting address books or spreadsheets. It's also important in whitespace-significant langs such as Python.

To use it, call whitespace-mode. (【Alt+x】) The command will toggle it on and off, for current file. Call global-whitespace-mode to toggle it globally for current emacs session.

There is also whitespace-newline-mode and global-whitespace-newline-mode. They only show newline chars.

Setting Up whitespace-mode

How to make whitespace-mode use the pilcrow sign “¶” for newline instead of the dollar sign?

Put the following in your emacs init file:

;; make whitespace-mode use “¶” for newline and “▷” for tab.
;; together with the rest of its defaults
(setq whitespace-display-mappings
 '(
   (space-mark 32 [183] [46]) ; normal space, ·
   (space-mark 160 [164] [95])
   (space-mark 2208 [2212] [95])
   (space-mark 2336 [2340] [95])
   (space-mark 3616 [3620] [95])
   (space-mark 3872 [3876] [95])
   (newline-mark 10 [182 10]) ; newlne, ¶
   (tab-mark 9 [9655 9] [92 9]) ; tab, ▷
))

In the above, the numbers are Unicode char code in decimal. Depending on your choice of font, some glyphs may not show up or correctly. If so, you can try the following glyphs.

Glyph	Unicode Code Point (Decimal)	Unicode Name
·	183	MIDDLE DOT
¶	182	PILCROW SIGN
↵	8629	DOWNWARDS ARROW WITH CORNER LEFTWARDS
↩	8617	LEFTWARDS ARROW WITH HOOK
⏎	9166	RETURN SYMBOL
▷	9655	WHITE RIGHT POINTING TRIANGLE
▶	9654	BLACK RIGHT-POINTING TRIANGLE
→	8594	RIGHTWARDS ARROW
↦	8614	RIGHTWARDS ARROW FROM BAR
⇥	8677	RIGHTWARDS ARROW TO BAR
⇨	8680	RIGHTWARDS WHITE ARROW

If you are wondering what are those other decimal numbers in the default whitespace settings, here they are:

Decimal	Glyph	Name or UNICODE NAME
10		line feed
32		space
46	.	full stop
95	_	underscore LOW LINE
160		NO-BREAK SPACE
164	¤	Symbol, Currency
2208		invalid Unicode decimal
2212		invalid Unicode decimal
2336	ठ	DEVANAGARI LETTER TTHA
2340	त	DEVANAGARI LETTER TA
3616	ภ	THAI CHARACTER PHO SAMPHAO
3620	ฤ	THAI CHARACTER RU
3872	༠	TIBETAN DIGIT ZERO
3876	༤	TIBETAN DIGIT FOUR

I have no idea why those {Indian, Thai, Tibetan} characters are doing there.

Common Questions for Editing Whitespaces

Command Name	Area of Action	Action
`whitespace-cleanup`	text selection	delete whitespace in a smart way
`delete-trailing-whitespace`	buffer	delete all trailing whitespaces
`delete-whitespace-rectangle`	selection as rectangle	delete whitespace in text selection start/end points as a rectangle

For more fine control of deleting whitespaces, you can use use query-replace, or query-replace-regexp. (➲ Find ＆ Replace with Emacs)

The following methods works everywhere (also works in minibuffer).

To insert a literal tab char, press 【Ctrl+q Tab ⇆】.

To insert a newline char, type 【Ctrl+q Ctrl+j】.

You need to use the above method to insert these characters, because for example in minibuffer, pressing Tab ⇆ does name completion and pressing Enter finishes the prompt. In most programing language modes, pressing Enter or Tab ⇆ also does some auto indenting and formatting.

For detail, see: Emacs's Key Notations Explained (/r, ^M, C-m, RET, <return>, M-, meta).