vim-indenting.md (5492B)
1 --- 2 title: "Understanding Vim's Indenting System" 3 date: 2017-04-30 4 tags: tech vim tutorial 5 categories: tech 6 --- 7 8  9 10 Like most things in Vim, the indenting (tabs) system is complex making it 11 extremely flexible so that it can fit any programming language or use case. 12 However, the commands and terminology can be confusing for beginners, this 13 post is designed to explain all the different commands and options needed to 14 fully control and customize tab's size, type, and look for any purpose. 15 16 To start of you should know that Vim has two different types of tabs, hard tabs 17 and soft tabs. Hard tabs are a single `<TAB>` character per indent level, while 18 soft tabs are multiple spaces per level. Hard tabs, while being only one 19 character, can be displayed by a text editor or viewer as any size, normally 8. 20 Different languages have different recommendations for the type and length of 21 tab to use, so learning how to control them can sometimes be necessary to 22 format your code properly. 23 24 ## creating indents 25 26 To insert a tab in Vim you can do it much like any other editor by pressing 27 `<TAB>` at the start of a line while in insert mode. In insert mode you can 28 also press `<C-t>` anywhere in the line to increase the lines indentation 29 and `<C-b>` to decrease. 30 31 In normal mode you can also use `>` and `<` followed by a motion to increase 32 and decrease the lines tabs as well. For example, `>>` will increase the tabs 33 on the current line, `>ap` will increase the indentation level of the entire 34 paragraph, `<j` will decrease two lines. The `>` and `<` commands also work 35 with a selected region in visual mode, but after every indent you have to 36 select the area again if you want to add another indent. To solve this I use 37 the following mapping in my `.vimrc` to automatically reopen the visual 38 selection for multiple levels of indents. 39 40 vnoremap > >gv 41 vnoremap < <gv 42 43 ## stylizing indents 44 45 By default vim displays hard tabs as clear white space, however you can change 46 this with the `listchars` option. `listchars` has multiple different possible 47 options such as `eol`, `space`, `trail`, etc. The option we care about for 48 indents is `tab`, which takes two single character arguments: the first one 49 being the character shown at the start of a hard tab and the second one being 50 the character that is repeated for the rest of the tab space. See `:h 51 listchars` for more. 52 53 ### examples 54 55 The following command sets the first character to a vertical bar `|` and the 56 rest of the tab to spaces. Remember to put the space at the end after the 57 second `\ `. 58 59 :set listchars=tab:\|\ 60 61  62 63 To have hard tabs look like dots you can use this: 64 65 :set listchars=tab:·· 66 67  68 69 Another example: 70 71 :set listchars=tab:»- 72 73  74 75 ### indent-guides plugin 76 77 This customization can be extending beyond what Vim offers by default with a 78 plugin such as [vim-indent-guides][1]. indent-guides lets you color and 79 stylize not only hard tabs, but soft ones, as well as many other features. 80 81  82 83 ## configuring indents 84 85 Now if you need to learn to manually change tabs settings, here is an outline 86 of the options: 87 88 * `shiftwidth` sets the length that vim indents by (default 8) 89 * `expandtab` makes Vim insert soft tabs instead of hard tabs (default off) 90 * `noexpandtab` makes Vim hard tabs instead of soft ones (default: on) 91 * `tabstop` changes displayed length of hard tabs in Vim only, should almost 92 always be equal to `shiftwidth` (default 8) 93 * `softtabstop` like `tabstop` but only for soft tabs (default 0) 94 * `autoindent` automatically indent newline to the level of the last one 95 (default off) 96 * `smartindent` enables auto indenting based on context (eg after `{`) 97 (default off) 98 * `smarttab` when on Vim inserts tabs according to `shiftwidth` at the 99 beginning of the line, whereas `tabstop` and `softtabstop` are used 100 elsewhere. 101 102 For more info run `:help 'OPTION'` in Vim, where `OPTION` is any option from 103 above. 104 105 ### examples 106 107 Small hard tabs (html): 108 109 :set noexpandtab 110 :set shiftwidth=2 111 :set softtabstop=2 112 113 Soft tabs (python): 114 115 :set expandtab 116 :set shiftwidth=4 117 :set softtabstop=4 118 119 Normal hard tabs (C): 120 121 :set noexpandtab 122 :set shiftwidth=8 123 :set tabstop=8 124 125 To automatically change the options for indents per file type you could put 126 lines such as these in your `.vimrc` file: 127 128 autocmd FileType html setlocal shiftwidth=2 tabstop=2 129 autocmd FileType python setlocal expandtab shiftwidth=4 softtabstop=4 130 autocmd FileType c setlocal noexpandtab shiftwidth=8 softtabstop=8 131 132 ### polyglot plugin 133 134  135 136 Unless you want to add a new line to your `.vimrc` every time you want to edit 137 a new type of file, I would recommend installing the Vim plugin 138 [vim-polyglot][2]. Not only does this plugin provide syntax highlighting for 139 hundreds of languages but it also provides default indentation settings for 140 each as well. While these defaults are useful, it can also be necessary to 141 manually control each setting. For example if you want to change the defaults 142 to your own preference or if a file is already formatted a specific way 143 polyglot will not change it, so you will have to. 144 145 [1]: https://github.com/nathanaelkane/vim-indent-guides 146 [2]: https://github.com/sheerun/vim-polyglot