I love Vim. But it isn't perfect, unfortunately.
And one part that is particularly confusing when setting up for the first time is indentation.
This guide strives to cover what options are relevant, what they do, how they interact, and how to set them up for most popular indentation styles.
Vim has 5 options relating to (manual) indentation:
| Name | Shorthand | Default Value |
|---|---|---|
| expandtab | et | off |
| tabstop | ts | 8 |
| shiftwidth | sw | 8 |
| softtabstop | sts | 0 |
| smarttab | sta | off (Neovim: on) |
You can find the documentation for each in Vim with :help 'option'.
For how to set options, see :help set-option.
expandtab is simple: If it is set, indentation is always done with spaces.
No tabs are inserted unless typed with <Ctrl-V>.
tabstop is similarly simple: It defines the width of a <Tab> character.
shiftwidth determines how many blanks are inserted when using the > and < commands, and when automatic indentation is used.
If set to 0, it uses the value of tabstop.
Here's where things become slightly more complex.
When softtabstop is not 0, <Tab> and <Backspace> insert and delete this many spaces.
If expandtab is not set, tabstop many spaces will be replaced by a <Tab>.
For example, with :set noexpandtab tabstop=8 softtabstop=2,
Pressing <Tab> four times gives you the following:
2 Spaces
4 Spaces
6 Spaces
1 Tab (8 spaces wide)
This allows tabstop to be left at the default value of 8, which is the most compatible.
If softtabstop is set to a negative value, the value of shiftwidth will be used.
When smarttab is set, pressing <Tab> at the start of a line (i.e. when using <Tab> for indentation), will always use the value of shiftwidth.
Anywhere else, softtabstop (if set) and tabstop are used.
Opinion: I heavily recommend always setting smarttab (the default if you use Neovim!), and use shiftwidth as the one true indentation width.
In this section I'll cover several indentation styles, and what combination of options to use for them.
Where N is your desired indentation size:
set noexpandtab " Default
set tabstop=N
set shiftwidth=0 " Use value of tabstop
set softtabstop=0 " Default
set smarttab " OptionalWhere N is your desired indentation size:
set expandtab
set tabstop=N " Optional, if you want files with tabs to look the same too.
set shiftwidth=N
set softtabstop=-1 " Use value of shiftwidth
set smarttab " Always use shiftwidthThis style can be used if you want to leave tabstop at its default of 8, but want <Tab> to behave as if it was a different value.
Where N is your desired indentation size:
set noexpandtab " Default
set shiftwidth=N
set softtabstop=-1 " Use value of shiftwidth
set smarttab " Always use shiftwidthsmarttabs behavior allows <Tab> to insert a different number of blanks when not at the start of a line.
This is done by using the softtabstop option.
This is useful for aligning comments and variable names, for example.
For a tabs-only style, this doesn't really work due to how softtabstop works, since changing the value of tabstop can then mess up your alignment, if it contains tabs.
If you want a 'indent with tabs, align with spaces' style, you'll have to look for a plugin like Smart Tabs.
For spaces-only and mixed styles, you can simply change softtabstop to your desired alignment size.
And that about wraps it up! I hope I was able to clear up some of the confusion around Vim's settings :)
If you have any suggestions or questions, let me know! And of course, happy vimming!
Hi thank you that was a nice guide. I could use some examples of a mixed style, where that would come in handy and how to utilize it - that would make it more clear, at least for me! thank you for this guide,