@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2023 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Indentation
@chapter Indentation
@cindex indentation
@cindex tabs
@cindex columns (indentation)

@cindex whitespace character
  @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace
characters} (space and/or tab characters) at the beginning of a line
of text.  This chapter documents indentation commands and options
which are common to Text mode and related modes, as well as
programming language modes.  @xref{Program Indent}, for additional
documentation about indenting in programming modes.

@findex indent-for-tab-command
@kindex TAB @r{(indentation)}
  The simplest way to perform indentation is the @key{TAB} key.  In
most major modes, this runs the command @code{indent-for-tab-command}.
(In C and related modes, @key{TAB} runs the command
@code{c-indent-line-or-region}, which behaves similarly, @pxref{C
Indent}).

@table @key
@item TAB
Insert whitespace, or indent the current line, in a mode-appropriate
way (@code{indent-for-tab-command}).  If the region is active, indent
all the lines within it.
@end table

  The exact behavior of @key{TAB} depends on the major mode.  In Text
mode and related major modes, @key{TAB} normally inserts some
combination of space and tab characters to advance point to the next
tab stop (@pxref{Tab Stops}).  For this purpose, the position of the
first non-whitespace character on the preceding line is treated as an
additional tab stop, so you can use @key{TAB} to align point with
the preceding line.  If the region is active (@pxref{Using Region}),
@key{TAB} acts specially: it indents each line in the region so that
its first non-whitespace character is aligned with the preceding line.

  In programming modes, @key{TAB} indents the current line of code in
a way that makes sense given the code in the preceding lines.  If the
region is active, all the lines in the region are indented this way.
If point was initially within the current line's indentation, it is
repositioned to the first non-whitespace character on the line.

  If you just want to insert a tab character in the buffer, type
@kbd{C-q @key{TAB}} (@pxref{Inserting Text}).

@menu
* Indentation Commands::  More commands for performing indentation.
* Tab Stops::             Stop points for indentation in Text modes.
* Just Spaces::           Using only space characters for indentation.
* Indent Convenience::    Optional indentation features.
* Code Alignment::        Making common parts of lines start at the same column.
@end menu

@node Indentation Commands
@section Indentation Commands

Apart from the @kbd{@key{TAB}} (@code{indent-for-tab-command})
command, Emacs provides a variety of commands to perform indentation
in other ways.

@table @kbd
@item C-M-o
@kindex C-M-o
@findex split-line
Split the current line at point (@code{split-line}).  The text on the
line after point becomes a new line, indented to the same column where
point is located.  This command first moves point forward over any
spaces and tabs.  Afterward, point is positioned before the inserted
newline.

@kindex M-m
@findex back-to-indentation
@item M-m
Move (forward or back) to the first non-whitespace character on the
current line (@code{back-to-indentation}).  If there are no
non-whitespace characters on the line, move to the end of the line.

@item M-i
@kindex M-i
@findex tab-to-tab-stop
Indent whitespace at point, up to the next tab stop
(@code{tab-to-tab-stop}).  @xref{Tab Stops}.

@findex indent-relative
@item M-x indent-relative
Insert whitespace at point, until point is aligned with the first
non-whitespace character on the previous line (actually, the last
non-blank line).  If point is already farther right than that, run
@code{tab-to-tab-stop} instead---unless called with a numeric
argument, in which case do nothing.

@item M-^
@kindex M-^
@findex delete-indentation
Merge the previous and the current line (@code{delete-indentation}).
This joins the two lines cleanly, by replacing any indentation at
the front of the current line, together with the line boundary, with a
single space.

As a special case (useful for Lisp code), the single space is omitted
if the characters to be joined are consecutive opening and closing
parentheses, or if the junction follows another newline.

If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it
appears after the newline that is deleted.  @xref{Fill Prefix}.

With a prefix argument, join the current line to the following line.
If the region is active, and no prefix argument is given, join all
lines in the region instead.

@item C-M-\
@kindex C-M-\
@findex indent-region
Indent all the lines in the region, as though you had typed
@kbd{@key{TAB}} at the beginning of each line (@code{indent-region}).

If a numeric argument is supplied, indent every line in the region to
that column number.

@item C-x @key{TAB}
@kindex C-x TAB
@findex indent-rigidly
@cindex remove indentation
Indent all lines that begin in the region, moving the affected lines
as a rigid unit (@code{indent-rigidly}).

If called with no argument, this command activates a transient mode for
adjusting the indentation of the affected lines interactively.  While
this transient mode is active, typing @kbd{@key{LEFT}} or
@kbd{@key{RIGHT}} indents leftward and rightward, respectively, by one
space.  You can also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to
indent leftward or rightward to the next tab stop (@pxref{Tab Stops}).
Typing any other key disables the transient mode, and this key is then
acted upon as normally.

If called with a prefix argument @var{n}, this command indents the
lines forward by @var{n} spaces (without enabling the transient mode).
Negative values of @var{n} indent backward, so you can remove all
indentation from the lines in the region using a large negative
argument, like this:

@smallexample
C-u -999 C-x @key{TAB}
@end smallexample
@end table

@node Tab Stops
@section Tab Stops
@cindex tab stops

@vindex tab-stop-list
  Emacs defines certain column numbers to be @dfn{tab stops}.  These
are used as stopping points by @key{TAB} when inserting whitespace in
Text mode and related modes (@pxref{Indentation}), and by commands
like @kbd{M-i} (@pxref{Indentation Commands}).  The variable
@code{tab-stop-list} controls these positions.  The default value is
@code{nil}, which means a tab stop every 8 columns.  The value can
also be a list of zero-based column numbers (in increasing order) at
which to place tab stops.  Emacs extends the list forever by repeating
the difference between the last and next-to-last elements.

@findex edit-tab-stops
@kindex C-c C-c @r{(Edit Tab Stops)}
  Instead of customizing the variable @code{tab-stop-list} directly, a
convenient way to view and set tab stops is via the command @kbd{M-x
edit-tab-stops}.  This switches to a buffer containing a description
of the tab stop settings, which looks like this:

@example
        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c
@end example

@noindent
The first line contains a colon at each tab stop.  The numbers on the
next two lines are present just to indicate where the colons are.
If the value of @code{tab-stop-list} is @code{nil}, as it is by default,
no colons are displayed initially.

  You can edit this buffer to specify different tab stops by placing
colons on the desired columns.  The buffer uses Overwrite mode
(@pxref{Minor Modes}).  Remember that Emacs will extend the list of
tab stops forever by repeating the difference between the last two
explicit stops that you place.  When you are done, type @kbd{C-c C-c} to make
the new tab stops take effect.  Normally, the new tab stop settings
apply to all buffers.  However, if you have made the
@code{tab-stop-list} variable local to the buffer where you called
@kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop
settings apply only to that buffer.  To save the tab stop settings for
future Emacs sessions, use the Customize interface to save the value
of @code{tab-stop-list} (@pxref{Easy Customization}).

  Note that the tab stops discussed in this section have nothing to do
with how tab characters are displayed in the buffer.  Tab characters
are always displayed as empty spaces extending to the next
@dfn{display tab stop}.  @xref{Text Display}.

@node Just Spaces
@section Tabs vs.@: Spaces

  Normally, indentation commands insert (or remove) the shortest
possible series of tab and space characters so as to align to the
desired column.  Tab characters are displayed as a stretch of empty
space extending to the next @dfn{display tab stop}.  By default, there
is one display tab stop every @code{tab-width} columns (the default is
8).  @xref{Text Display}.

@vindex indent-tabs-mode
  If you prefer, all indentation can be made from spaces only.  To
request this, set the buffer-local variable @code{indent-tabs-mode} to
@code{nil}.  @xref{Locals}, for information about setting buffer-local
variables.  Note, however, that @kbd{C-q @key{TAB}} always inserts a
tab character, regardless of the value of @code{indent-tabs-mode}.

  One reason to set @code{indent-tabs-mode} to @code{nil} is that not
all editors display tab characters in the same way.  Emacs users, too,
may have different customized values of @code{tab-width}.  By using
spaces only, you can make sure that your file always looks the same.
If you only care about how it looks within Emacs, another way to
tackle this problem is to set the @code{tab-width} variable in a
file-local variable (@pxref{File Variables}).

@findex tabify
@findex untabify
  There are also commands to convert tabs to spaces or vice versa, always
preserving the columns of all non-whitespace text.  @kbd{M-x tabify} scans the
region for sequences of spaces, and converts sequences of at least two
spaces to tabs if that can be done without changing indentation.  @kbd{M-x
untabify} changes all tabs in the region to appropriate numbers of spaces.

@node Indent Convenience
@section Convenience Features for Indentation

@vindex tab-always-indent
  The variable @code{tab-always-indent} tweaks the behavior of the
@key{TAB} (@code{indent-for-tab-command}) command.  The default value,
@code{t}, gives the behavior described in @ref{Indentation}.  If you
change the value to the symbol @code{complete}, then @key{TAB} first
tries to indent the current line, and if the line was already
indented, it tries to complete the text at point (@pxref{Symbol
Completion}).  If the value is @code{nil}, then @key{TAB} indents the
current line only if point is at the left margin or in the line's
indentation; otherwise, it inserts a tab character.

@vindex tab-first-completion
  If @code{tab-always-indent} is @code{complete}, whether to expand or
indent can be further customized via the @code{tab-first-completion}
variable.  For instance, if that variable is @code{eol}, only complete
if point is at the end of a line.  @xref{Mode-Specific Indent,,,
elisp, The Emacs Lisp Reference Manual}, for further details.

@cindex Electric Indent mode
@cindex mode, Electric Indent
@findex electric-indent-mode
  Electric Indent mode is a global minor mode that automatically
indents the line after every @key{RET} you type.  This mode is enabled
by default.  To toggle this minor mode, type @kbd{M-x
electric-indent-mode}.  To toggle the mode in a single buffer,
use @kbd{M-x electric-indent-local-mode}.

@node Code Alignment
@section Code Alignment
@cindex code alignment
@cindex aligning code

  @dfn{Alignment} is the process of adjusting whitespace in a sequence
of lines in the region such that in all lines certain parts begin at
the same column.  This is usually something you do to enhance
readability of a piece of text or code.  The classic example is
aligning a series of assignments in C-like programming languages:

@example
int a = 1;
short foo = 2;
double blah = 4;
@end example

@noindent
is commonly aligned to:

@example
int    a    = 1;
short  foo  = 2;
double blah = 4;
@end example

@cindex alignment rules
@findex align
  You can use the command @kbd{M-x align} to align lines in the
current region.  This command knows about common alignment patterns
across many markup and programming languages.  It encodes these
patterns as a set of @dfn{alignment rules}, that say how to align
different kinds of text in different contexts.

@vindex align-rules-list
@vindex align-mode-rules-list
The user option @code{align-rules-list} says which alignment rules
@kbd{M-x align} should consult.  The value of this option is a list
with elements describing alignment rules.  Each element is a cons cell
@code{(@var{title} . @var{attributes})}, where @var{title} is the name
of the alignment rule as a symbol, and @var{attributes} is a list of
rule attributes that define when the rule should apply and how it
partitions and aligns lines.  Each rule attribute is a cons cell
@code{(@var{attribute} . @var{value})}, where @var{attribute} is the
name of attribute and @var{value} is its value.  The only required
attribute is @code{regexp}, whose value is a regular expression
(@pxref{Regular Expressions,,,elisp,The Emacs Lisp Reference Manual})
with sub-expressions matching the parts of each line where @kbd{M-x
align} should expand or contract whitespace.  See the documentation
string of @code{align-rules-list} (@kbd{C-h v align-rules-list
@key{RET}}) for a full description of possible alignment rule
attributes.  By default, this option is set to a long list of
alignment rules for many languages that Emacs supports.  The default
rules use the @code{modes} rule attribute to specify major modes in
which @kbd{M-x align} should apply them.  Major modes can also
override @code{align-rules-list} by setting the buffer-local variable
@code{align-mode-rules-list} to a non-@code{nil} list of alignment
rules.  When @code{align-mode-rules-list} is non-@code{nil}, @kbd{M-x
align} consults it instead of @code{align-rules-list}.

@cindex align exclusion rules
@vindex align-exclude-rules-list
@vindex align-mode-exclude-rules-list
Besides alignment rules, @kbd{M-x align} uses another kind of rules
called @dfn{exclusion rules}.  The exclusion rules say which parts in
the region @kbd{M-x align} should not align and instead leave them
intact.  The user option @code{align-exclude-rules-list} specifies
these exclusion rules.  Similarly to @code{align-rules-list}, the
value of @code{align-exclude-rules-list} is also a list of cons cells
that describe the exclusion rules.  By default,
@code{align-exclude-rules-list} includes rules that exclude alignment
in quoted strings and comments in Lisp, C and other languages.  Beyond
the default exclusion rules in @code{align-exclude-rules-list}, major
modes can define bespoke exclusion rules by setting
@code{align-mode-exclude-rules-list} to a non-@code{nil} list of
rules, this overrides @code{align-exclude-rules-list} just like
@code{align-mode-rules-list} overrides @code{align-rules-list}.

@cindex alignment sections
@vindex align-region-separate
@kbd{M-x align} splits the region into a series of @dfn{sections},
usually sequences of non-blank lines, and aligns each section
according to all matching alignment rule by expanding or contracting
stretches of whitespace.  @kbd{M-x align} consistently aligns all
lines inside a single section, but it may align different sections in
the region differently.  The user option @code{align-region-separate}
specifies how @kbd{M-x align} separates the region to sections.  This
option can be one of the symbols @code{entire}, @code{group}, or a
regular expression.  If @code{align-region-separate} is @code{entire},
Emacs aligns the entire region as a single section.  If this option is
@code{group}, Emacs aligns each group of consecutive non-blank lines
in the region as a separate section.  If @code{align-region-separate}
is a regular expression, @kbd{M-x align} scans the region for matches
to that regular expression and treats them as section separators.  By
default @code{align-region-separate} is set to a regular expression
that matches blank lines and lines that contains only whitespace and a
single curly brace (@samp{@{} or @samp{@}}).  For special cases where
regular expressions are not accurate enough, you can also set
@code{align-region-separate} to a function that says how to separate
the region to alignment sections.  See the documentation string of
@code{align-region-separate} for more details.  Specific alignment
rules can override the value of @code{align-region-separate} and
define their own section separator by specifying the @code{separate}
rule attribute.

If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), it
enables more alignment rules that are often useful but may sometimes
be too intrusive.  For example, in a Lisp buffer with the following
form:

@lisp
(set-face-attribute 'mode-line-inactive nil
                    :box nil
                    :background nil
                    :underline "black")
@end lisp

@noindent
Typing (@kbd{C-u M-x align}) yields:

@lisp
(set-face-attribute 'mode-line-inactive nil
                    :box                nil
                    :background         nil
                    :underline          "black")
@end lisp

In most cases, you should try @kbd{M-x align} without a prefix
argument first, and if that doesn't produce the right result you can
undo with @kbd{C-/} and try again with @kbd{C-u M-x align}.

@findex align-highlight-rule
@findex align-unhighlight-rule
You can use the command @kbd{M-x align-highlight-rule} to visualize
the effect of a specific alignment or exclusion rule in the current
region.  This command prompts you for the title of a rule and
highlights the parts on the region that this rule affects.  For
alignment rules, this command highlights the whitespace that @kbd{M-x
align} would expand or contract, and for exclusion this command
highlights the parts that @kbd{M-x align} would exclude from
alignment.  To remove the highlighting that this command creates, type
@kbd{M-x align-unhighlight-rule}.

@findex align-current
@findex align-entire
  The command @kbd{M-x align-current} is similar to @kbd{M-x align},
except that it operates only on the alignment section that contains
point regardless of the current region.  This command determines the
boundaries of the current section according to the section separators
that @code{align-region-separate} define.  @kbd{M-x align-entire} is
another variant of @kbd{M-x align}, that disregards
@code{align-region-separate} and aligns the entire region as a single
alignment section with consistent alignment.  If you set
@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves
like @kbd{M-x align-entire} by default.  To illustrate the effect of
aligning the entire region as a single alignment section, consider the
following code:

@example
one = 1;
foobarbaz = 2;

spam = 3;
emacs = 4;
@end example

@noindent
when the region covers all of these lines, typing @kbd{M-x align}
yields:

@example
one       = 1;
foobarbaz = 2;

spam  = 3;
emacs = 4;
@end example

@noindent
On the other hand, @kbd{M-x align-entire} aligns all of the lines as a
single section, so the @samp{=} appears at the same column in all
lines:

@example
one       = 1;
foobarbaz = 2;

spam      = 3;
emacs     = 4;
@end example

@findex align-regexp
  The command @kbd{M-x align-regexp} lets you align the current region
with an alignment rule that you define ad-hoc, instead of using the
predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
prompts you for a regular expression and uses that expression as the
@code{regexp} attribute for an ad-hoc alignment rule that this command
uses to align the current region.  By default, this command adjusts
the whitespace that matches the first sub-expression of the regular
expression you specify.  If you call @kbd{M-x align-regexp} with a
prefix argument, it also prompts you for the sub-expression to use and
lets you specify the amount of whitespace to use as padding, as well
as whether to apply the rule repeatedly to all matches of the regular
expression in each line.  @xref{Regular Expressions,,,elisp,The Emacs
Lisp Reference Manual}, for more information about regular expressions
and their sub-expressions.

@vindex align-indent-before-aligning
  If the user option @code{align-indent-before-aligning} is
non-@code{nil}, Emacs indents the region before aligning it with
@kbd{M-x align}.  @xref{Indentation}.  By default
@code{align-indent-before-aligning} is set to @code{nil}.

@vindex align-to-tab-stop
  The user option @code{align-to-tab-stop} says whether aligned parts
should start at a tab stop (@pxref{Tab Stops}).  If this option is
@code{nil}, @kbd{M-x align} uses just enough whitespace for alignment,
disregarding tab stops.  If this is a non-@code{nil} symbol, @kbd{M-x
align} checks the value of that symbol, and if this value is
non-@code{nil}, @kbd{M-x align} aligns to tab stops.  By default, this
option is set to @code{indent-tabs-mode}, so alignment respects tab
stops in buffers that use tabs for indentation.  @xref{Just Spaces}.

@vindex align-default-spacing
  The user option @code{align-default-spacing} specifies the default
amount of whitespace that @kbd{M-x align} and its related commands use
for padding between the different parts of each line when aligning it.
When @code{align-to-tab-stop} is @code{nil}, the value of
@code{align-default-spacing} is the number of spaces to use for
padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of
@code{align-default-spacing} is instead the number of tab stops to
use.  Each alignment rule can override the default that
@code{align-default-spacing} specifies with the @code{spacing}
attribute rule.