How Does Vim Auto-Indent Handle Mixed Tabs And Spaces?

If you've ever opened a file that looks like a bento box of tabs and spaces, Vim's auto-indent behavior is surprisingly predictable once you know the pieces involved.

Auto-indent (the basic 'autoindent' option) simply copies the leading characters from the previous line — literally. That means if the previous line starts with a tab, then two spaces, Vim will start the new line with that exact sequence. Nothing clever, just a straightforward copy. Where things get interesting is when you press Tab or when you run reindent commands: Tab insertion is governed by 'expandtab' and 'softtabstop'. If 'expandtab' is set, inserting a tab character from Insert mode actually inserts spaces. If it's unset, Vim inserts a real tab character, and 'softtabstop' affects how many spaces the Tab key represents while editing.

Reformatting with commands like '=' or using cindent/smartindent is different: Vim computes the desired indentation in columns based on 'shiftwidth' and the language indent rules, then writes the indentation according to your tab settings (usually honoring 'expandtab' to decide whether to use spaces, or using tabs where possible when it's unset). Practical tips: use ':set list' to reveal hidden whitespace, ':set tabstop=4 shiftwidth=4 softtabstop=4', ':set expandtab' to normalize new indentation to spaces, and ':retab' to convert existing characters if you want to clean the file up.

I tend to think about this like a little mechanical copier followed by a formatter. First the copier: with simple auto-indent on, Vim just copies the previous line's indentation characters verbatim — tabs, spaces, whatever sits at the start of the line. That’s why files can look inconsistent when they were edited by multiple people or different editors.

Then the formatter: when you ask Vim to fix indentation (operators like '=', or rules driven by 'cindent'/'indentexpr'), Vim calculates how many columns of indent the language rules demand. After that it writes that number of columns according to your settings. If 'expandtab' is enabled, it writes only spaces. If not, it will try to use tabs (based on 'tabstop') and then spaces for any leftover columns. This is why 'shiftwidth' controls the logical indent step, but 'tabstop' controls how those steps become physical characters.

Practical suggestions from my toolbox: install a tiny plugin like 'vim-sleuth' to auto-detect existing indentation, use ':set list' or ':set listchars' to inspect, and when you want uniform output pick either ':set expandtab' plus ':%retab' to convert tabs to spaces, or ':set noexpandtab' and a consistent tabstop to keep tabs. Also watch out for Makefiles and similar where literal tabs are required — in those files I explicitly force 'noexpandtab' so the copier/formatter won’t break them.

Okay, here’s the short technical walk-through from my desk: the plain auto-indent feature copies the prior line’s leading bytes — tabs and spaces — exactly as they are. So if you’ve got a mix on the previous line, the next line will start with that same mix.

What changes behavior is what you do next. Hitting Tab in Insert mode respects 'expandtab' and 'softtabstop' (so Tab can mean spaces or a real tab). Reindenting with '=' or using 'cindent' computes indentation in terms of columns (using 'shiftwidth' as the unit) then converts that column count into characters. That conversion will use spaces if 'expandtab' is set; otherwise Vim will insert tabs where they fit (using 'tabstop' to know tab width). To normalize a file I usually: turn on ':set list', pick a canonical tab/shiftwidth/softtabstop, ':set expandtab' if I want spaces, and then run ':%retab' followed by 'gg=G' to reindent everything.

If you need to preserve literal tabs (like in Makefiles), be careful: modelines or filetype plugins might alter behavior, so set options explicitly per-file.

Quick, friendly checklist from my late-night editing sessions: Vim’s basic auto-indent copies the previous line’s leading characters exactly, so mixed tabs+spaces are preserved on the next line.

If you press Tab or reformat, the editor's other settings matter. 'expandtab' makes Tab insert spaces; 'softtabstop' affects how Tab behaves in insert mode; 'shiftwidth' defines the size used by '>' '<' and reindent commands; 'tabstop' tells Vim how wide a real tab is when converting columns into characters. When reindenting, Vim computes the correct column amount and then emits tabs or spaces according to 'expandtab' and 'tabstop'.

To fix a messy file: reveal whitespace with ':set list', choose your canonical settings, then use ':%retab' and a full reindent. Simple, but it saves hours of annoying diffs.