codekingpro/portable-devtools

1*usr_21.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7			   Go away and come back8 9 10This chapter goes into mixing the use of other programs with Vim.  Either by11executing program from inside Vim or by leaving Vim and coming back later.12Furthermore, this is about the ways to remember the state of Vim and restore13it later.14 15|21.1|	Suspend and resume16|21.2|	Executing shell commands17|21.3|	Remembering information; viminfo18|21.4|	Sessions19|21.5|	Views20|21.6|	Modelines21 22     Next chapter: |usr_22.txt|  Finding the file to edit23 Previous chapter: |usr_20.txt|  Typing command-line commands quickly24Table of contents: |usr_toc.txt|25 26==============================================================================27*21.1*	Suspend and resume28 29Like most Unix programs Vim can be suspended by pressing CTRL-Z.  This stops30Vim and takes you back to the shell it was started in.  You can then do any31other commands until you are bored with them.  Then bring back Vim with the32"fg" command. >33 34	CTRL-Z35	{any sequence of shell commands}36	fg37 38You are right back where you left Vim, nothing has changed.39   In case pressing CTRL-Z doesn't work, you can also use ":suspend".40Don't forget to bring Vim back to the foreground, you would lose any changes41that you made!42 43Only Unix has support for this.  On other systems Vim will start a shell for44you.  This also has the functionality of being able to execute shell commands.45But it's a new shell, not the one that you started Vim from.46   When you are running the GUI you can't go back to the shell where Vim was47started.  CTRL-Z will minimize the Vim window instead.48 49==============================================================================50*21.2*	Executing shell commands51 52To execute a single shell command from Vim use ":!{command}".  For example, to53see a directory listing: >54 55	:!ls56	:!dir57 58The first one is for Unix, the second one for MS-Windows.59   Vim will execute the program.  When it ends you will get a prompt to hit60<Enter>.  This allows you to have a look at the output from the command before61returning to the text you were editing.62   The "!" is also used in other places where a program is run.  Let's take63a look at an overview:64 65	:!{program}		execute {program}66	:r !{program}		execute {program} and read its output67	:w !{program}		execute {program} and send text to its input68	:[range]!{program}	filter text through {program}69 70Notice that the presence of a range before "!{program}" makes a big71difference.  Without it executes the program normally, with the range a number72of text lines is filtered through the program.73 74Executing a whole row of programs this way is possible.  But a shell is much75better at it.  You can start a new shell this way: >76 77	:shell78 79This is similar to using CTRL-Z to suspend Vim.  The difference is that a new80shell is started.81 82When using the GUI the shell will be using the Vim window for its input and83output.  Since Vim is not a terminal emulator, this will not work perfectly.84If you have trouble, try toggling the 'guipty' option.  If this still doesn't85work well enough, start a new terminal to run the shell in.  For example with:86>87	:!xterm&88 89==============================================================================90*21.3*	Remembering information; viminfo91 92After editing for a while you will have text in registers, marks in various93files, a command line history filled with carefully crafted commands.  When94you exit Vim all of this is lost.  But you can get it back!95 96The viminfo file is designed to store status information:97 98	Command-line and Search pattern history99	Text in registers100	Marks for various files101	The buffer list102	Global variables103 104Each time you exit Vim it will store this information in a file, the viminfo105file.  When Vim starts again, the viminfo file is read and the information106restored.107 108The 'viminfo' option is set by default to restore a limited number of items.109You might want to set it to remember more information.  This is done through110the following command: >111 112	:set viminfo=string113 114The string specifies what to save.  The syntax of this string is an option115character followed by an argument.  The option/argument pairs are separated by116commas.117   Take a look at how you can build up your own viminfo string.  First, the '118option is used to specify how many files for which you save marks (a-z).  Pick119a nice even number for this option (1000, for instance).  Your command now120looks like this: >121 122	:set viminfo='1000123 124The f option controls whether global marks (A-Z and 0-9) are stored.  If this125option is 0, none are stored.  If it is 1 or you do not specify an f option,126the marks are stored.  You want this feature, so now you have this: >127 128	:set viminfo='1000,f1129 130The < option controls how many lines are saved for each of the registers.  By131default, all the lines are saved.  If 0, nothing is saved.  To avoid adding132thousands of lines to your viminfo file (which might never get used and makes133starting Vim slower) you use a maximum of 500 lines: >134 135	:set viminfo='1000,f1,<500136<137Other options you might want to use:138	:	number of lines to save from the command line history139	@	number of lines to save from the input line history140	/	number of lines to save from the search history141	r	removable media, for which no marks will be stored (can be142		used several times)143	!	global variables that start with an uppercase letter and144		don't contain lowercase letters145	h	disable 'hlsearch' highlighting when starting146	%	the buffer list (only restored when starting Vim without file147		arguments)148	c	convert the text using 'encoding'149	n	name used for the viminfo file (must be the last option)150 151See the 'viminfo' option and |viminfo-file| for more information.152 153When you run Vim multiple times, the last one exiting will store its154information.  This may cause information that previously exiting Vims stored155to be lost.  Each item can be remembered only once.156 157 158GETTING BACK TO WHERE YOU STOPPED VIM159 160You are halfway editing a file and it's time to leave for holidays.  You exit161Vim and go enjoy yourselves, forgetting all about your work.  After a couple162of weeks you start Vim, and type:163>164	'0165 166And you are right back where you left Vim.  So you can get on with your work.167   Vim creates a mark each time you exit Vim.  The last one is '0.  The168position that '0 pointed to is made '1.  And '1 is made to '2, and so forth.169Mark '9 is lost.170   The |:marks| command is useful to find out where '0 to '9 will take you.171 172 173GETTING BACK TO SOME FILE174 175If you want to go back to a file that you edited recently, but not when176exiting Vim, there is a slightly more complicated way.  You can see a list of177files by typing the command: >178 179	:oldfiles180<	1: ~/.viminfo ~181	2: ~/text/resume.txt ~182	3: /tmp/draft ~183 184Now you would like to edit the second file, which is in the list preceded by185"2:".  You type: >186 187	:e #<2188 189Instead of ":e" you can use any command that has a file name argument, the190"#<2" item works in the same place as "%" (current file name) and "#"191(alternate file name).  So you can also split the window to edit the third192file: >193 194	:split #<3195 196That #<123 thing is a bit complicated when you just want to edit a file.197Fortunately there is a simpler way: >198 199	:browse oldfiles200<	1: ~/.viminfo ~201	2: ~/text/resume.txt ~202	3: /tmp/draft ~203	-- More --204 205You get the same list of files as with |:oldfiles|.  If you want to edit206"resume.txt" first press "q" to stop the listing.  You will get a prompt:207 208	Type number and <Enter> (empty cancels): ~209 210Type "2" and press <Enter> to edit the second file.211 212If you know that the filename contains a pattern, you can also |:filter| the213list of files: >214 215	:filter /resume/ :browse oldfiles216<217Since there is only one single matching filename, Vim will directly edit that218file without prompting.  If the filter matches several files, you'll get219prompted for the list of matching files instead: >220 221	:filter! /resume/ browse oldfiles222<	1: ~/.viminfo ~223	3: /tmp/draft ~224	Type number and <Enter> (q or empty cancels): ~225 226Note: this time we filtered out all files NOT matching resume.227 228 229More info at |:oldfiles|, |v:oldfiles| and |c_#<|.230 231 232MOVE INFO FROM ONE VIM TO ANOTHER233 234You can use the ":wviminfo" and ":rviminfo" commands to save and restore the235information while still running Vim.  This is useful for exchanging register236contents between two instances of Vim, for example.  In the first Vim do: >237 238	:wviminfo! ~/tmp/viminfo239 240And in the second Vim do: >241 242	:rviminfo! ~/tmp/viminfo243 244Obviously, the "w" stands for "write" and the "r" for "read".245   The ! character is used by ":wviminfo" to forcefully overwrite an existing246file.  When it is omitted, and the file exists, the information is merged into247the file.248   The ! character used for ":rviminfo" means that all the information is249used, this may overwrite existing information.  Without the ! only information250that wasn't set is used.251   These commands can also be used to store info and use it again later.  You252could make a directory full of viminfo files, each containing info for a253different purpose.254 255==============================================================================256*21.4*	Sessions257 258Suppose you are editing along, and it is the end of the day.  You want to quit259work and pick up where you left off the next day.  You can do this by saving260your editing session and restoring it the next day.261   A Vim session contains all the information about what you are editing.262This includes things such as the file list, window layout, global variables,263options and other information.  (Exactly what is remembered is controlled by264the 'sessionoptions' option, described below.)265   The following command creates a session file: >266 267	:mksession vimbook.vim268 269Later if you want to restore this session, you can use this command: >270 271	:source vimbook.vim272 273If you want to start Vim and restore a specific session, you can use the274following command: >275 276	vim -S vimbook.vim277 278This tells Vim to read a specific file on startup.  The 'S' stands for279session (actually, you can source any Vim script with -S, thus it might as280well stand for "source").281 282The windows that were open are restored, with the same position and size as283before.  Mappings and option values are like before.284   What exactly is restored depends on the 'sessionoptions' option.  The285default value is:286"blank,buffers,curdir,folds,help,options,tabpages,winsize,terminal".287 288	blank		keep empty windows289	buffers		all buffers, not only the ones in a window290	curdir		the current directory291	folds		folds, also manually created ones292	help		the help window293	options		all options and mappings294	tabpages	all tab pages295	winsize		window sizes296	terminal	include terminal windows297 298Change this to your liking.  To also restore the size of the Vim window, for299example, use: >300 301	:set sessionoptions+=resize302 303 304SESSION HERE, SESSION THERE305 306The obvious way to use sessions is when working on different projects.307Suppose you store your session files in the directory "~/.vim".  You are308currently working on the "secret" project and have to switch to the "boring"309project: >310 311	:wall312	:mksession! ~/.vim/secret.vim313	:source ~/.vim/boring.vim314 315This first uses ":wall" to write all modified files.  Then the current session316is saved, using ":mksession!".  This overwrites the previous session.  The317next time you load the secret session you can continue where you were at this318point.  And finally you load the new "boring" session.319 320If you open help windows, split and close various windows, and generally mess321up the window layout, you can go back to the last saved session: >322 323	:source ~/.vim/boring.vim324 325Thus you have complete control over whether you want to continue next time326where you are now, by saving the current setup in a session, or keep the327session file as a starting point.328   Another way of using sessions is to create a window layout that you like to329use, and save this in a session.  Then you can go back to this layout whenever330you want.331   For example, this is a nice layout to use:332 333	+----------------------------------------+334	|		   VIM - main help file  |335	|					 |336	|Move around:  Use the cursor keys, or "h|337	|help.txt================================|338	|explorer   |				 |339	|dir	    |~				 |340	|dir	    |~				 |341	|file	    |~				 |342	|file	    |~				 |343	|file	    |~				 |344	|file	    |~				 |345	|~/=========|[No File]===================|346	|					 |347	+----------------------------------------+348 349This has a help window at the top, so that you can read this text.  The narrow350vertical window on the left contains a file explorer.  This is a Vim plugin351that lists the contents of a directory.  You can select files to edit there.352More about this in the next chapter.353   Create this from a just started Vim with: >354 355	:help356	CTRL-W w357	:vertical split ~/358 359You can resize the windows a bit to your liking.  Then save the session with:360>361	:mksession ~/.vim/mine.vim362 363Now you can start Vim with this layout: >364 365	vim -S ~/.vim/mine.vim366 367Hint: To open a file you see listed in the explorer window in the empty368window, move the cursor to the filename and press "O".  Double clicking with369the mouse will also do this.370 371 372UNIX AND MS-WINDOWS373 374Some people have to do work on MS-Windows systems one day and on Unix another375day.  If you are one of them, consider adding "slash" and "unix" to376'sessionoptions'.  The session files will then be written in a format that can377be used on both systems.  This is the command to put in your vimrc file: >378 379	:set sessionoptions+=unix,slash380 381Vim will use the Unix format then, because the MS-Windows Vim can read and382write Unix files, but Unix Vim can't read MS-Windows format session files.383Similarly, MS-Windows Vim understands file names with / to separate names, but384Unix Vim doesn't understand \.385 386 387SESSIONS AND VIMINFO388 389Sessions store many things, but not the position of marks, contents of390registers and the command line history.  You need to use the viminfo feature391for these things.392   In most situations you will want to use sessions separately from viminfo.393This can be used to switch to another session, but keep the command line394history.  And yank text into registers in one session, and paste it back in395another session.396   You might prefer to keep the info with the session.  You will have to do397this yourself then.  Example: >398 399	:mksession! ~/.vim/secret.vim400	:wviminfo! ~/.vim/secret.viminfo401 402And to restore this again: >403 404	:source ~/.vim/secret.vim405	:rviminfo! ~/.vim/secret.viminfo406 407==============================================================================408*21.5*	Views409 410A session stores the looks of the whole of Vim.  When you want to store the411properties for one window only, use a view.412   The use of a view is for when you want to edit a file in a specific way.413For example, you have line numbers enabled with the 'number' option and414defined a few folds.  Just like with sessions, you can remember this view on415the file and restore it later.  Actually, when you store a session, it stores416the view of each window.417   There are two basic ways to use views.  The first is to let Vim pick a name418for the view file.  You can restore the view when you later edit the same419file.  To store the view for the current window: >420 421	:mkview422 423Vim will decide where to store the view.  When you later edit the same file424you get the view back with this command: >425 426	:loadview427 428That's easy, isn't it?429   Now you want to view the file without the 'number' option on, or with all430folds open, you can set the options to make the window look that way.  Then431store this view with: >432 433	:mkview 1434 435Obviously, you can get this back with: >436 437	:loadview 1438 439Now you can switch between the two views on the file by using ":loadview" with440and without the "1" argument.441   You can store up to ten views for the same file this way, one unnumbered442and nine numbered 1 to 9.443 444 445A VIEW WITH A NAME446 447The second basic way to use views is by storing the view in a file with a name448you choose.  This view can be loaded while editing another file.  Vim will449then switch to editing the file specified in the view.  Thus you can use this450to quickly switch to editing another file, with all its options set as you451saved them.452   For example, to save the view of the current file: >453 454	:mkview ~/.vim/main.vim455 456You can restore it with: >457 458	:source ~/.vim/main.vim459 460==============================================================================461*21.6*	Modelines462 463When editing a specific file, you might set options specifically for that464file.  Typing these commands each time is boring.  Using a session or view for465editing a file doesn't work when sharing the file between several people.466   The solution for this situation is adding a modeline to the file.  This is467a line of text that tells Vim the values of options, to be used in this file468only.469   A typical example is a C program where you make indents by a multiple of 4470spaces.  This requires setting the 'shiftwidth' option to 4.  This modeline471will do that:472 473	/* vim:set shiftwidth=4: */ ~474 475Put this line as one of the first or last five lines in the file.  When476editing the file, you will notice that 'shiftwidth' will have been set to477four.  When editing another file, it's set back to the default value of eight.478   For some files the modeline fits well in the header, thus it can be put at479the top of the file.  For text files and other files where the modeline gets480in the way of the normal contents, put it at the end of the file.481 482The 'modelines' option specifies how many lines at the start and end of the483file are inspected for containing a modeline.  To inspect ten lines: >484 485	:set modelines=10486 487The 'modeline' option can be used to switch this off.  Do this when you are488working as root on Unix or Administrator on MS-Windows, or when you don't489trust the files you are editing: >490 491	:set nomodeline492 493Use this format for the modeline:494 495	any-text vim:set {option}={value} ... : any-text ~496 497The "any-text" indicates that you can put any text before and after the part498that Vim will use.  This allows making it look like a comment, like what was499done above with /* and */.500   The " vim:" part is what makes Vim recognize this line.  There must be501white space before "vim", or "vim" must be at the start of the line.  Thus502using something like "gvim:" will not work.503   The part between the colons is a ":set" command.  It works the same way as504typing the ":set" command, except that you need to insert a backslash before a505colon (otherwise it would be seen as the end of the modeline).506 507Another example:508 509	// vim:set textwidth=72 dir=c\:\tmp:  use c:\tmp here ~510 511There is an extra backslash before the first colon, so that it's included in512the ":set" command.  The text after the second colon is ignored, thus a remark513can be placed there.514 515For more details see |modeline|.516 517==============================================================================518 519Next chapter: |usr_22.txt|  Finding the file to edit520 521Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:522