(Move categories to tip template) |
JohnBeckett (talk | contribs) (Simplify.) Tag: rollback |
||
(39 intermediate revisions by 24 users not shown) | |||
Line 1: | Line 1: | ||
− | {{review}} |
||
{{TipImported |
{{TipImported |
||
|id=331 |
|id=331 |
||
|previous=330 |
|previous=330 |
||
|next=332 |
|next=332 |
||
− | |created= |
+ | |created=2002 |
|complexity=basic |
|complexity=basic |
||
− | |author= |
+ | |author= |
− | |version= |
+ | |version=6.0 |
|rating=154/50 |
|rating=154/50 |
||
|category1= |
|category1= |
||
|category2= |
|category2= |
||
}} |
}} |
||
+ | Options set in your [[vimrc]] will apply to all files that you edit. You can also set: |
||
− | One of the things about Vim that are both quite simple yet very useful is that you can store by-file settings... That is each file can contain settings specific to it. This thing is called a modeline {{help|modeline}}. Though this is limited only to the 'set' command arguments, you can store quite a lot local file settings like the indent type, folding method and so on. |
||
+ | *Different options for all files of a certain type (for example, all <code>*.py</code> files). See [[filetype.vim]] and [[VimTip1510|filetypes]] and an [[VimTip1565|example]]. |
||
+ | *Different options for a particular file using modelines (this tip). |
||
+ | Note that the 'modeline' option must be set in order to take advantage of this tip. This option is set by default for Vim running in nocompatible mode, but some notable distributions of Vim disable this option in the system vimrc for security. In addition, it is off by default when editing as root. See {{help|'modeline'}} for more information. |
||
− | The syntax is as follows: |
||
+ | |||
+ | ==Examples== |
||
+ | For example, in a particular file you may want each tab character that you type to be expanded to spaces. To achieve this, put the following modeline near the top or the bottom of that file: |
||
<pre> |
<pre> |
||
− | + | # vim: set expandtab: |
|
</pre> |
</pre> |
||
+ | The space between the comment opening and <code>vim:</code> is required, otherwise the modeline will not be recognized. |
||
− | or |
||
+ | |||
+ | The modeline cannot be anywhere in the file: it must be in the first or last few lines. The exact location where vim checks for the modeline is controlled by the <code>modelines</code> variable; see {{help|'modelines'}}. By default, it is set to 5 lines. |
||
+ | |||
+ | The following examples show some alternatives that could be in a C file: |
||
<pre> |
<pre> |
||
− | / |
+ | // vim: noai:ts=4:sw=4 |
+ | -or- |
||
+ | /* vim: noai:ts=4:sw=4 |
||
+ | */ |
||
+ | -or- |
||
+ | /* vim: set noai ts=4 sw=4: */ |
||
+ | -or- |
||
+ | /* vim: set fdm=expr fde=getline(v\:lnum)=~'{'?'>1'\:'1': */ |
||
</pre> |
</pre> |
||
+ | With "<code>set</code>", the modeline ends at the first colon not following a backslash. Without "<code>set</code>", no text can follow the options, so for example, the following is invalid: |
||
− | The modelines can be contained in comments so as to not interfere with the file syntax (shown here for C/C++). These lines are read by Vim when it loads the file, and they can either be in the first or last 5 lines (by default). |
||
+ | <pre> |
||
+ | Error E518: Unknown option: */ |
||
+ | /* vim: noai:ts=4:sw=4 */ |
||
+ | </pre> |
||
+ | ==Adding a modeline== |
||
− | Please note that the second modeline syntax (the one using "se[t]") _must_ be colon terminated, while the first (plain) one _may_. |
||
+ | With the following in your [[vimrc]] and the default leader key, you could type <code>\ml</code> to add a modeline based on your current settings: |
||
+ | <pre> |
||
⚫ | |||
+ | " Use substitute() instead of printf() to handle '%%s' modeline in LaTeX |
||
+ | " files. |
||
⚫ | |||
+ | let l:modeline = printf(" vim: set ts=%d sw=%d tw=%d %set :", |
||
+ | \ &tabstop, &shiftwidth, &textwidth, &expandtab ? '' : 'no') |
||
+ | let l:modeline = substitute(&commentstring, "%s", l:modeline, "") |
||
+ | call append(line("$"), l:modeline) |
||
⚫ | |||
⚫ | |||
+ | </pre> |
||
+ | In a C file, you would get a modeline like this: |
||
⚫ | |||
− | Speaking of modelines I find it handy to have a very primitive menu entry to insert my normal modeline for me: |
||
<pre> |
<pre> |
||
+ | /* vim: set ts=8 sw=4 tw=0 noet : */ |
||
⚫ | |||
</pre> |
</pre> |
||
+ | Alternatively, you could use a simple menu entry, for example: |
||
− | This will net you a (I think proper) modeline at the start of the file like so: |
||
+ | <pre> |
||
⚫ | |||
+ | </pre> |
||
+ | |||
+ | Choosing the menu item would insert two modelines like this: |
||
<pre> |
<pre> |
||
vim:ff=unix ts=4 ss=4 |
vim:ff=unix ts=4 ss=4 |
||
Line 39: | Line 75: | ||
</pre> |
</pre> |
||
+ | ==Enabling modelines== |
||
⚫ | |||
+ | Vim executes a modeline only if all of the following apply: |
||
⚫ | |||
+ | *'modeline' is set to "modeline" (not "nomodeline") |
||
+ | *'modelines' is set to a positive integer (not "0") |
||
+ | *You are not root. |
||
+ | Enter the following to see the current settings and, if not the default, where they were last set. |
||
⚫ | |||
− | |||
− | It is also possible to append a modeline using the file type's comment string: |
||
<pre> |
<pre> |
||
+ | :verbose set modeline? modelines? |
||
⚫ | |||
− | " save the old position |
||
− | let l:pos = line( '.' ).' | normal! '.virtcol( '.' ).'|' |
||
⚫ | |||
− | execute "normal Go" . printf(&commentstring, "vim: ts=".tabstop." sw=".&shiftwidth." tw=".&textwidth.": " ) |
||
− | " restore the old position |
||
− | exe l:pos |
||
− | endif |
||
⚫ | |||
</pre> |
</pre> |
||
+ | |||
− | Then one may create a mapping such as: |
||
+ | Debian, Ubuntu, Gentoo, OSX, etc. by default disable modelines for security reasons. To enable modelines, edit your vimrc file (for example, in Vim enter <code>:e $MYVIMRC</code>) and check you have lines like the following. |
||
<pre> |
<pre> |
||
+ | set modeline |
||
⚫ | |||
+ | set modelines=5 |
||
</pre> |
</pre> |
||
+ | |||
+ | ==Security== |
||
+ | {{Todo}} |
||
+ | *Need note on security implications of modelines and reference to alternatives. |
||
+ | *Text other than "vim:" can be recognised as a modeline. |
||
+ | *Google "vim modeline vulnerability" (without quotes) for information. |
||
+ | |||
+ | ==References== |
||
+ | *{{help|auto-setting}} |
||
+ | *{{help|modeline}} |
||
+ | *{{help|'modeline'}} determines whether to look for modelines |
||
+ | *{{help|'modelines'}} number of lines checked to find each modeline |
||
+ | |||
⚫ | |||
⚫ | |||
+ | |||
+ | See {{script|id=1876}} - securemodelines |
||
⚫ | |||
+ | |||
+ | How is it that the modeline: |
||
+ | <code>vim: noai:ts=4:sw=4</code> |
||
+ | is used as an example of correct modeline usage and then used as an error example (when describing use of 'set') right afterwards? |
||
+ | :Because, if you are using the <code>set:</code> syntax, then the modeline ends on the first <code>:</code> character it finds. Thus, you can include the modeline in <code>/* ... */</code> style comments. When you are *not* using the <code>set:</code> syntax, then the modeline always continues to the end of the line. Any text at all in the line will be considered part of the modeline. Therefore you cannot use <code>/* ... */</code> style comments, you must use <code>//</code> style comments. --[[User:Fritzophrenic|Fritzophrenic]] ([[User talk:Fritzophrenic|talk]]) 18:11, February 5, 2015 (UTC) |
||
⚫ |
Revision as of 00:38, 9 February 2015
Options set in your vimrc will apply to all files that you edit. You can also set:
- Different options for all files of a certain type (for example, all
*.py
files). See filetype.vim and filetypes and an example. - Different options for a particular file using modelines (this tip).
Note that the 'modeline' option must be set in order to take advantage of this tip. This option is set by default for Vim running in nocompatible mode, but some notable distributions of Vim disable this option in the system vimrc for security. In addition, it is off by default when editing as root. See :help 'modeline' for more information.
Examples
For example, in a particular file you may want each tab character that you type to be expanded to spaces. To achieve this, put the following modeline near the top or the bottom of that file:
# vim: set expandtab:
The space between the comment opening and vim:
is required, otherwise the modeline will not be recognized.
The modeline cannot be anywhere in the file: it must be in the first or last few lines. The exact location where vim checks for the modeline is controlled by the modelines
variable; see :help 'modelines'. By default, it is set to 5 lines.
The following examples show some alternatives that could be in a C file:
// vim: noai:ts=4:sw=4 -or- /* vim: noai:ts=4:sw=4 */ -or- /* vim: set noai ts=4 sw=4: */ -or- /* vim: set fdm=expr fde=getline(v\:lnum)=~'{'?'>1'\:'1': */
With "set
", the modeline ends at the first colon not following a backslash. Without "set
", no text can follow the options, so for example, the following is invalid:
Error E518: Unknown option: */ /* vim: noai:ts=4:sw=4 */
Adding a modeline
With the following in your vimrc and the default leader key, you could type \ml
to add a modeline based on your current settings:
" Append modeline after last line in buffer. " Use substitute() instead of printf() to handle '%%s' modeline in LaTeX " files. function! AppendModeline() let l:modeline = printf(" vim: set ts=%d sw=%d tw=%d %set :", \ &tabstop, &shiftwidth, &textwidth, &expandtab ? '' : 'no') let l:modeline = substitute(&commentstring, "%s", l:modeline, "") call append(line("$"), l:modeline) endfunction nnoremap <silent> <Leader>ml :call AppendModeline()<CR>
In a C file, you would get a modeline like this:
/* vim: set ts=8 sw=4 tw=0 noet : */
Alternatively, you could use a simple menu entry, for example:
amenu Edit.Insert\ &modeline <C-\><C-N>ggOvim:ff=unix ts=4 ss=4<CR>vim60:fdm=marker<Esc>
Choosing the menu item would insert two modelines like this:
vim:ff=unix ts=4 ss=4 vim60:fdm=marker
Enabling modelines
Vim executes a modeline only if all of the following apply:
- 'modeline' is set to "modeline" (not "nomodeline")
- 'modelines' is set to a positive integer (not "0")
- You are not root.
Enter the following to see the current settings and, if not the default, where they were last set.
:verbose set modeline? modelines?
Debian, Ubuntu, Gentoo, OSX, etc. by default disable modelines for security reasons. To enable modelines, edit your vimrc file (for example, in Vim enter :e $MYVIMRC
) and check you have lines like the following.
set modeline set modelines=5
Security
TO DO
- Need note on security implications of modelines and reference to alternatives.
- Text other than "vim:" can be recognised as a modeline.
- Google "vim modeline vulnerability" (without quotes) for information.
References
- :help auto-setting
- :help modeline
- :help 'modeline' determines whether to look for modelines
- :help 'modelines' number of lines checked to find each modeline
Comments
This mechanism can be extended to 'let' – see script#83.
See script#1876 - securemodelines
How is it that the modeline:
vim: noai:ts=4:sw=4
is used as an example of correct modeline usage and then used as an error example (when describing use of 'set') right afterwards?
- Because, if you are using the
set:
syntax, then the modeline ends on the first:
character it finds. Thus, you can include the modeline in/* ... */
style comments. When you are *not* using theset:
syntax, then the modeline always continues to the end of the line. Any text at all in the line will be considered part of the modeline. Therefore you cannot use/* ... */
style comments, you must use//
style comments. --Fritzophrenic (talk) 18:11, February 5, 2015 (UTC)