The ##<tab>## key is usually bound to do some mode-specific indentation. People new to Emacs often feel like they just want ##<tab>## to insert a tab. This is of course possible, but discouraged. Why make Emacs dumber than it is? Emacs can figure out how much indentation you need and do the right thing!

Remember, often the indentation engines of major modes can be customized. Specially modes based on [CcMode CC Mode] are notorious for their support of /styles/. See IndentingC for examples.

== Basic Control ==

The variable ##indent-tabs-mode## controls whether tabs are used for indentation. It is ##t## (true) by default, which means that the standard indentation commands will utilise tab characters where possible, and in accordance with the current ##tab-width## value.  (When the indentation is not an exact multiple of tab-width, spaces will be used for the remainder.)

To deactivate ##indent-tabs-mode##, put the following in <tt>[InitFile .emacs]</tt>.

    (setq-default indent-tabs-mode nil)

The variable ##backward-delete-char-untabify-method## controls what happens when you delete a tab character -- either converting the tab to spaces and deleting one space (the default); deleting all preceding whitespace; or deleting just the single tab character.  If the latter is what you want to happen, use:

    (setq backward-delete-char-untabify-method nil)

Note that you can also switch on `whitespace-mode' to visualise the whitespace; or, if you're using GUI frames, you can use ##(setq x-stretch-cursor t)## to make the cursor occupy the full width of the character it's on (including the full width of a tab character).

The rest of this page will assume tabs are used and discuss the use of the following two variables:

* ##c-basic-offset##: The basic indentation offset in [CcMode CC Mode], default is 2. For Perl, it is controlled by ##cperl-indent-level##.
* ##tab-width##: How wide a tab is, default is 8.

You /should/ ensure these variables have the same value to avoid interoperability problems with other editors ([http://lists.macromates.com/textmate/2007-November/023215.html TextMate, for example]) that are unable to separate tab width from indentation.  E.g.:

    (setq tab-width 4 ;; or any other preferred value
          c-basic-offset tab-width
          cperl-indent-level tab-width
          ...)

With this set-up, all lines but continuation lines become independent of the tab size used by the programmer.  (I.e. when the indentation is a combination of a base indent with some additional alignment spacing).  To fix continuation lines too, see SmartTabs.

The following would alternatively cause the indentation/offset variables to become aliases for the tab-width variable (causing all of the variables to evaluate to the same value); but aliases are intended to be used for variables that are actually the same thing (which is not the case here), and so this has the potential to be problematic:

    (setq tab-width 4) ; or any other preferred value
    (defvaralias 'c-basic-offset 'tab-width)
    (defvaralias 'cperl-indent-level 'tab-width)

----

The following two commands will be useful when looking at the examples below:

* ##M-x tabify##: Change spaces to tabs where appropriate.
* ##M-x untabify##: Change all tabs to the correct number of spaces (controlled by ##tab-width##).

If you are [IndentingPerl indenting Perl] and the mode is configured to indent by four, and you didn't change the variables above, then the following example will use /no/ tabs! There are no eight spaces in it to replace with a tab.

    sub SmileyReplace {
      foreach my $regexp (keys %Smilies) {
        if (m/\G($regexp)/cg) {
          return $q->img({-src=>$Smilies{$regexp}, -alt=>$1, -class=>'smiley'});
        }
      }
    }

If ##indent-tabs-mode## is ##t## and ##tab-width## is 4, however, you will see three tabs looking four spaces wide:

    sub SmileyReplace {
      foreach my $regexp (keys %Smilies) {
    ____if (m/\G($regexp)/cg) {
    ____  return $q->img({-src=>$Smilies{$regexp}, -alt=>$1, -class=>'smiley'});
    ____}
      }
    }

If you are collaborating with other people, however, and they use different settings, things will get ugly. The tabs may look twice as wide, since the default is 8:

    sub SmileyReplace {
      foreach my $regexp (keys %Smilies) {
    ________if (m/\G($regexp)/cg) {
    ________  return $q->img({-src=>$Smilies{$regexp}, -alt=>$1, -class=>'smiley'});
    ________}
      }
    }

Thus, you should either not change ##tab-width##, or make sure that it matches whatever the indentation steps of your current major mode are.

If you are a die-hard tab user, try using a ##tab-width## of 2. Here's how it will look for you:

    sub SmileyReplace {
    __foreach my $regexp (keys %Smilies) {
    ____if (m/\G($regexp)/cg) {
    ______return $q->img({-src=>$Smilies{$regexp}, -alt=>$1, -class=>'smiley'});
    ____}
    __}
    }

And here for the other poor bastards:

    sub SmileyReplace {
    ________foreach my $regexp (keys %Smilies) {
    ________________if (m/\G($regexp)/cg) {
    ________________________return $q->img({-src=>$Smilies{$regexp}, -alt=>$1, -class=>'smiley'});
    ________________}
    ________}
    }

In summary:

* Only change these variables when you know what you are doing.
* Rely on the indentation suggested by the Emacs major modes (but see also Project-specific Indentation Configuration, below).

== Project-specific Indentation Configuration ==

If your .emacs is set-up to do indentation one way and you are contributing to a project that expects indentation to be done in a different way, then you might want [[DirectoryVariables]].  For example, if you usually use spaces (##(indent-tabs-mode nil)##) to indent, and the project you're working on uses tabs, then you can add a ##.dir-locals.el## to the root directory of the project to make Emacs treat files in the project specially.  Here's an example ##.dir-locals.el## that uses tabs and highlights leading spaces to keep you honest:

    ;; The 'nil' configuration applies to all modes.
    ((nil . ((indent-tabs-mode . t)
            (tab-width . 2)))
     (haskell-mode . (
            ;; Highlight leading space characters in Haskell files.
            (eval . (highlight-regexp "^ *")))))

If other people are working on the same code, you might want to use [https://editorconfig.org EditorConfig] and the [https://github.com/editorconfig/editorconfig-emacs emacs extension].

== Smart Tabs ==
Is it possible to make Emacs use a /smart/ mix of tabs and spaces?

[new]
**Yes**, it is possible. See SmartTabs.

----
CategoryIndentation