vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_29.txt (20255B)


      1 *usr_29.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			    Moving through programs
      8 
      9 
     10 The creator of Vim is a computer programmer.  It's no surprise that Vim
     11 contains many features to aid in writing programs.  Jump around to find where
     12 identifiers are defined and used.  Preview declarations in a separate window.
     13 There is more in the next chapter.
     14 
     15 |29.1|	Using tags
     16 |29.2|	The preview window
     17 |29.3|	Moving through a program
     18 |29.4|	Finding global identifiers
     19 |29.5|	Finding local identifiers
     20 
     21      Next chapter: |usr_30.txt|  Editing programs
     22  Previous chapter: |usr_28.txt|  Folding
     23 Table of contents: |usr_toc.txt|
     24 
     25 ==============================================================================
     26 *29.1*	Using tags
     27 
     28 What is a tag?  It is a location where an identifier is defined.  An example
     29 is a function definition in a C or C++ program.  A list of tags is kept in a
     30 tags file.  This can be used by Vim to directly jump from any place to the
     31 tag, the place where an identifier is defined.
     32    To generate the tags file for all C files in the current directory, use the
     33 following command: >
     34 
     35 	ctags *.c
     36 
     37 "ctags" is a separate program.  Most Unix systems already have it installed.
     38 If you do not have it yet, you can find Universal/Exuberant ctags at:
     39 	http://ctags.io
     40 	http://ctags.sf.net
     41 
     42 Universal ctags is preferred, Exuberant ctags is no longer being developed.
     43 
     44 Now when you are in Vim and you want to go to a function definition, you can
     45 jump to it by using the following command: >
     46 
     47 	:tag startlist
     48 
     49 This command will find the function "startlist" even if it is in another file.
     50    The CTRL-] command jumps to the tag of the word that is under the cursor.
     51 This makes it easy to explore a tangle of C code.  Suppose, for example, that
     52 you are in the function "write_block".  You can see that it calls
     53 "write_line".  But what does "write_line" do?  By placing the cursor on the
     54 call to "write_line" and pressing CTRL-], you jump to the definition of this
     55 function.
     56    The "write_line" function calls "write_char".  You need to figure out what
     57 it does.  So you position the cursor over the call to "write_char" and press
     58 CTRL-].  Now you are at the definition of "write_char".
     59 
     60 	+-------------------------------------+
     61 	|void write_block(char **s; int cnt)  |
     62 	|{				      |
     63 	|   int i;			      |
     64 	|   for (i = 0; i < cnt; ++i)	      |
     65 	|      write_line(s[i]);	      |
     66 	|}	    |			      |
     67 	+-----------|-------------------------+
     68 		    |
     69 	     CTRL-] |
     70 		    |	 +----------------------------+
     71 		    +--> |void write_line(char *s)    |
     72 			 |{			      |
     73 			 |   while (*s != 0)	      |
     74 			 |	write_char(*s++);     |
     75 			 |}	  |		      |
     76 			 +--------|-------------------+
     77 				  |
     78 			   CTRL-] |
     79 				  |    +------------------------------------+
     80 				  +--> |void write_char(char c)		    |
     81 				       |{				    |
     82 				       |    putchar((int)(unsigned char)c); |
     83 				       |}				    |
     84 				       +------------------------------------+
     85 
     86 The ":tags" command shows the list of tags that you traversed through:
     87 
     88 	:tags
     89 	  # TO tag	   FROM line  in file/text ~
     90 	  1  1 write_line	   8  write_block.c ~
     91 	  2  1 write_char	   7  write_line.c ~
     92 	> ~
     93 >
     94 Now to go back.  The CTRL-T command goes to the preceding tag.  In the example
     95 above you get back to the "write_line" function, in the call to "write_char".
     96    This command takes a count argument that indicates how many tags to jump
     97 back.  You have gone forward, and now back.  Let's go forward again.  The
     98 following command goes to the tag on top of the list: >
     99 
    100 	:tag
    101 
    102 You can prefix it with a count and jump forward that many tags.  For example:
    103 ":3tag".  CTRL-T also can be preceded with a count.
    104    These commands thus allow you to go down a call tree with CTRL-] and back
    105 up again with CTRL-T.  Use ":tags" to find out where you are.
    106 
    107 
    108 SPLIT WINDOWS
    109 
    110 The ":tag" command replaces the file in the current window with the one
    111 containing the new function.  But suppose you want to see not only the old
    112 function but also the new one?  You can split the window using the ":split"
    113 command followed by the ":tag" command.  Vim has a shorthand command that does
    114 both: >
    115 	:stag tagname
    116 
    117 To split the current window and jump to the tag under the cursor use this
    118 command: >
    119 
    120 	CTRL-W ]
    121 
    122 If a count is specified, the new window will be that many lines high.
    123 
    124 
    125 MORE TAGS FILES
    126 
    127 When you have files in many directories, you can create a tags file in each of
    128 them.  Vim will then only be able to jump to tags within that directory.
    129    To find more tags files, set the 'tags' option to include all the relevant
    130 tags files.  Example: >
    131 
    132 	:set tags=./tags,./../tags,./*/tags
    133 
    134 This finds a tags file in the same directory as the current file, one
    135 directory level higher and in all subdirectories.
    136    This is quite a number of tags files, but it may still not be enough.  For
    137 example, when editing a file in "~/proj/src", you will not find the tags file
    138 "~/proj/sub/tags".  For this situation Vim offers to search a whole directory
    139 tree for tags files.  Example: >
    140 
    141 	:set tags=~/proj/**/tags
    142 
    143 
    144 ONE TAGS FILE
    145 
    146 When Vim has to search many places for tags files, you can hear the disk
    147 rattling.  It may get a bit slow.  In that case it's better to spend this
    148 time while generating one big tags file.  You might do this overnight.
    149    This requires the Universal or Exuberant ctags program, mentioned above.
    150 It offers an argument to search a whole directory tree: >
    151 
    152 	cd ~/proj
    153 	ctags -R .
    154 
    155 The nice thing about this is that Universal/Exuberant ctags recognizes various
    156 file types.  Thus this doesn't work just for C and C++ programs, also for
    157 Eiffel and even Vim scripts.  See the ctags documentation to tune this.
    158    Now you only need to tell Vim where your big tags file is: >
    159 
    160 	:set tags=~/proj/tags
    161 
    162 
    163 MULTIPLE MATCHES
    164 
    165 When a function is defined multiple times (or a method in several classes),
    166 the ":tag" command will jump to the first one.  If there is a match in the
    167 current file, that one is used first.
    168    You can now jump to other matches for the same tag with: >
    169 
    170 	:tnext
    171 
    172 Repeat this to find further matches.  If there are many, you can select which
    173 one to jump to: >
    174 
    175 	:tselect tagname
    176 
    177 Vim will present you with a list of choices:
    178 
    179 	  # pri kind tag	       file ~
    180 	  1 F	f    mch_init	       os_amiga.c ~
    181 		       mch_init() ~
    182 	  2 F	f    mch_init	       os_mac.c ~
    183 		       mch_init() ~
    184 	  3 F	f    mch_init	       os_msdos.c ~
    185 		       mch_init(void) ~
    186 	  4 F	f    mch_init	       os_riscos.c ~
    187 		       mch_init() ~
    188 	Enter nr of choice (<CR> to abort):  ~
    189 
    190 You can now enter the number (in the first column) of the match that you would
    191 like to jump to.  The information in the other columns give you a good idea of
    192 where the match is defined.
    193 
    194 To move between the matching tags, these commands can be used:
    195 
    196 	:tfirst			go to first match
    197 	:[count]tprevious	go to [count] previous match
    198 	:[count]tnext		go to [count] next match
    199 	:tlast			go to last match
    200 
    201 If [count] is omitted then one is used.
    202 
    203 
    204 GUESSING TAG NAMES
    205 
    206 Command line completion is a good way to avoid typing a long tag name.  Just
    207 type the first bit and press <Tab>: >
    208 
    209 	:tag write_<Tab>
    210 
    211 You will get the first match.  If it's not the one you want, press <Tab> until
    212 you find the right one.
    213    Sometimes you only know part of the name of a function.  Or you have many
    214 tags that start with the same string, but end differently.  Then you can tell
    215 Vim to use a pattern to find the tag.
    216    Suppose you want to jump to a tag that contains "block".  First type
    217 this: >
    218 
    219 	:tag /block
    220 
    221 Now use command line completion: press <Tab>.  Vim will find all tags that
    222 contain "block" and use the first match.
    223    The "/" before a tag name tells Vim that what follows is not a literal tag
    224 name, but a pattern.  You can use all the items for search patterns here.  For
    225 example, suppose you want to select a tag that starts with "write_": >
    226 
    227 	:tselect /^write_
    228 
    229 The "^" specifies that the tag starts with "write_".  Otherwise it would also
    230 be found halfway a tag name.  Similarly "$" at the end makes sure the pattern
    231 matches until the end of a tag.
    232 
    233 
    234 A TAGS BROWSER
    235 
    236 Since CTRL-] takes you to the definition of the identifier under the cursor,
    237 you can use a list of identifier names as a table of contents.  Here is an
    238 example.
    239    First create a list of identifiers (this requires Universal or Exuberant
    240 ctags): >
    241 
    242 	ctags --c-types=f -f functions *.c
    243 
    244 Now start Vim without a file, and edit this file in Vim, in a vertically split
    245 window: >
    246 
    247 	vim
    248 	:vsplit functions
    249 
    250 The window contains a list of all the functions.  There is some more stuff,
    251 but you can ignore that.  Do ":setlocal ts=99" to clean it up a bit.
    252    In this window, define a mapping: >
    253 
    254 	:nnoremap <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR>
    255 
    256 Move the cursor to the line that contains the function you want to go to.
    257 Now press <Enter>.  Vim will go to the other window and jump to the selected
    258 function.
    259 
    260 
    261 RELATED ITEMS
    262 
    263 To make case in tag names be ignored, you can set 'ignorecase' while leaving
    264 'tagcase' as "followic", or set 'tagcase' to "ignore".
    265 
    266 The 'tagbsearch' option tells if the tags file is sorted or not.  The default
    267 is to assume a sorted tags file, which makes a tags search a lot faster, but
    268 doesn't work if the tags file isn't sorted.
    269 
    270 The 'taglength' option can be used to tell Vim the number of significant
    271 characters in a tag.
    272 
    273 Cscope is a free program.  It does not only find places where an identifier is
    274 declared, but also where it is used.  See |cscope|.
    275 
    276 ==============================================================================
    277 *29.2*	The preview window
    278 
    279 When you edit code that contains a function call, you need to use the correct
    280 arguments.  To know what values to pass you can look at how the function is
    281 defined.  The tags mechanism works very well for this.  Preferably the
    282 definition is displayed in another window.  For this the preview window can be
    283 used.
    284    To open a preview window to display the function "write_char": >
    285 
    286 	:ptag write_char
    287 
    288 Vim will open a window, and jumps to the tag "write_char".  Then it takes you
    289 back to the original position.  Thus you can continue typing without the need
    290 to use a CTRL-W command.
    291    If the name of a function appears in the text, you can get its definition
    292 in the preview window with: >
    293 
    294 	CTRL-W }
    295 
    296 There is a script that automatically displays the text where the word under
    297 the cursor was defined.  See |CursorHold-example|.
    298 
    299 To close the preview window use this command: >
    300 
    301 	:pclose
    302 
    303 To edit a specific file in the preview window, use ":pedit".  This can be
    304 useful to edit a header file, for example: >
    305 
    306 	:pedit defs.h
    307 
    308 Finally, ":psearch" can be used to find a word in the current file and any
    309 included files and display the match in the preview window.  This is
    310 especially useful when using library functions, for which you do not have a
    311 tags file.  Example: >
    312 
    313 	:psearch popen
    314 
    315 This will show the "stdio.h" file in the preview window, with the function
    316 prototype for popen():
    317 
    318 	FILE	*popen __P((const char *, const char *)); ~
    319 
    320 You can specify the height of the preview window, when it is opened, with the
    321 'previewheight' option.
    322 
    323 ==============================================================================
    324 *29.3*	Moving through a program
    325 
    326 Since a program is structured, Vim can recognize items in it.  Specific
    327 commands can be used to move around.
    328    C programs often contain constructs like this:
    329 
    330 	#ifdef USE_POPEN ~
    331 	    fd = popen("ls", "r") ~
    332 	#else ~
    333 	    fd = fopen("tmp", "w") ~
    334 	#endif ~
    335 
    336 But then much longer, and possibly nested.  Position the cursor on the
    337 "#ifdef" and press %.  Vim will jump to the "#else".  Pressing % again takes
    338 you to the "#endif".  Another % takes you to the "#ifdef" again.
    339    When the construct is nested, Vim will find the matching items.  This is a
    340 good way to check if you didn't forget an "#endif".
    341    When you are somewhere inside a "#if" - "#endif", you can jump to the start
    342 of it with: >
    343 
    344 	[#
    345 
    346 If you are not after a "#if" or "#ifdef" Vim will beep.  To jump forward to
    347 the next "#else" or "#endif" use: >
    348 
    349 	]#
    350 
    351 These two commands skip any "#if" - "#endif" blocks that they encounter.
    352 Example:
    353 
    354 	#if defined(HAS_INC_H) ~
    355 	    a = a + inc(); ~
    356 	# ifdef USE_THEME ~
    357 	    a += 3; ~
    358 	# endif ~
    359 	    set_width(a); ~
    360 
    361 With the cursor in the last line, "[#" moves to the first line.  The "#ifdef"
    362 - "#endif" block in the middle is skipped.
    363 
    364 
    365 MOVING IN CODE BLOCKS
    366 
    367 In C code blocks are enclosed in {}.  These can get pretty long.  To move to
    368 the start of the outer block use the "[[" command.  Use "][" to find the end.
    369 This assumes that the "{" and "}" are in the first column.
    370    The "[{" command moves to the start of the current block.  It skips over
    371 pairs of {} at the same level.  "]}" jumps to the end.
    372    An overview:
    373 
    374 			function(int a)
    375 	   +->		{
    376 	   |		    if (a)
    377 	   |	   +->	    {
    378 	[[ |	   |		for (;;)	       --+
    379 	   |	   |	  +->	{			 |
    380 	   |	[{ |	  |	    foo(32);		 |     --+
    381 	   |	   |   [{ |	    if (bar(a))  --+	 | ]}	 |
    382 	   +--	   |	  +--		break;	   | ]}  |	 |
    383 		   |		}		 <-+	 |	 | ][
    384 		   +--		foobar(a)		 |	 |
    385 			    }			       <-+	 |
    386 			}				       <-+
    387 
    388 When writing C++ or Java, the outer {} block is for the class.  The next level
    389 of {} is for a method.  When somewhere inside a class use "[m" to find the
    390 previous start of a method.  "]m" finds the next start of a method.
    391 
    392 Additionally, "[]" moves backward to the end of a function and "]]" moves
    393 forward to the start of the next function.  The end of a function is defined
    394 by a "}" in the first column.
    395 
    396 				int func1(void)
    397 				{
    398 					return 1;
    399 		  +---------->  }
    400 		  |
    401 	      []  |		int func2(void)
    402 		  |	   +->	{
    403 		  |    [[  |		if (flag)
    404 	start	  +--	   +--			return flag;
    405 		  |    ][  |		return 2;
    406 		  |	   +->	}
    407 	      ]]  |
    408 		  |		int func3(void)
    409 		  +---------->	{
    410 					return 3;
    411 				}
    412 
    413 Don't forget you can also use "%" to move between matching (), {} and [].
    414 That also works when they are many lines apart.
    415 
    416 
    417 MOVING IN BRACES
    418 
    419 The "[(" and "])" commands work similar to "[{" and "]}", except that they
    420 work on () pairs instead of {} pairs.
    421 >
    422 				  [(
    423 <		    <--------------------------------
    424 			      <-------
    425 		if (a == b && (c == d || (e > f)) && x > y) ~
    426 				  -------------->
    427 			  --------------------------------> >
    428 				       ])
    429 
    430 MOVING IN COMMENTS
    431 
    432 To move back to the start of a comment use "[/".  Move forward to the end of a
    433 comment with "]/".  This only works for /* - */ comments.
    434 
    435 	  +->	  +-> /*
    436 	  |    [/ |    * A comment about      --+
    437        [/ |	  +--  * wonderful life.	| ]/
    438 	  |	       */		      <-+
    439 	  |
    440 	  +--	       foo = bar * 3;	      --+
    441 						| ]/
    442 		       /* a short comment */  <-+
    443 
    444 ==============================================================================
    445 *29.4*	Finding global identifiers
    446 
    447 You are editing a C program and wonder if a variable is declared as "int" or
    448 "unsigned".  A quick way to find this is with the "[I" command.
    449    Suppose the cursor is on the word "column".  Type: >
    450 
    451 	[I
    452 
    453 Vim will list the matching lines it can find.  Not only in the current file,
    454 but also in all included files (and files included in them, etc.).  The result
    455 looks like this:
    456 
    457 	structs.h ~
    458 	 1:   29     unsigned     column;    /* column number */ ~
    459 
    460 The advantage over using tags or the preview window is that included files are
    461 searched.  In most cases this results in the right declaration to be found.
    462 Also when the tags file is out of date.  Also when you don't have tags for the
    463 included files.
    464    However, a few things must be right for "[I" to do its work.  First of all,
    465 the 'include' option must specify how a file is included.  The default value
    466 works for C and C++.  For other languages you will have to change it.
    467 
    468 
    469 LOCATING INCLUDED FILES
    470 
    471    Vim will find included files in the places specified with the 'path'
    472 option.  If a directory is missing, some include files will not be found.  You
    473 can discover this with this command: >
    474 
    475 	:checkpath
    476 
    477 It will list the include files that could not be found.  Also files included
    478 by the files that could be found.  An example of the output:
    479 
    480 	--- Included files not found in path --- ~
    481 	<io.h> ~
    482 	vim.h --> ~
    483 	  <functions.h> ~
    484 	  <clib/exec_protos.h> ~
    485 
    486 The "io.h" file is included by the current file and can't be found.  "vim.h"
    487 can be found, thus ":checkpath" goes into this file and checks what it
    488 includes.  The "functions.h" and "clib/exec_protos.h" files, included by
    489 "vim.h" are not found.
    490 
    491 	Note:
    492 	Vim is not a compiler.  It does not recognize "#ifdef" statements.
    493 	This means every "#include" statement is used, also when it comes
    494 	after "#if NEVER".
    495 
    496 To fix the files that could not be found, add a directory to the 'path'
    497 option.  A good place to find out about this is the Makefile.  Look out for
    498 lines that contain "-I" items, like "-I/usr/local/X11".  To add this directory
    499 use: >
    500 
    501 	:set path+=/usr/local/X11
    502 
    503 When there are many subdirectories, you can use the "*" wildcard.  Example: >
    504 
    505 	:set path+=/usr/*/include
    506 
    507 This would find files in "/usr/local/include" as well as "/usr/X11/include".
    508 
    509 When working on a project with a whole nested tree of included files, the "**"
    510 items is useful.  This will search down in all subdirectories.  Example: >
    511 
    512 	:set path+=/projects/invent/**/include
    513 
    514 This will find files in the directories:
    515 
    516 	/projects/invent/include ~
    517 	/projects/invent/main/include ~
    518 	/projects/invent/main/os/include ~
    519 	etc.
    520 
    521 There are even more possibilities.  Check out the 'path' option for info.
    522    If you want to see which included files are actually found, use this
    523 command: >
    524 
    525 	:checkpath!
    526 
    527 You will get a (very long) list of included files, the files they include, and
    528 so on.  To shorten the list a bit, Vim shows "(Already listed)" for files that
    529 were found before and doesn't list the included files in there again.
    530 
    531 
    532 JUMPING TO A MATCH
    533 
    534 "[I" produces a list with only one line of text.  When you want to have a
    535 closer look at the first item, you can jump to that line with the command: >
    536 
    537 	[<Tab>
    538 
    539 You can also use "[ CTRL-I", since CTRL-I is the same as pressing <Tab>.
    540 
    541 The list that "[I" produces has a number at the start of each line.  When you
    542 want to jump to another item than the first one, type the number first: >
    543 
    544 	3[<Tab>
    545 
    546 Will jump to the third item in the list.  Remember that you can use CTRL-O to
    547 jump back to where you started from.
    548 
    549 
    550 RELATED COMMANDS
    551 
    552 	[i		only lists the first match
    553 	]I		only lists items below the cursor
    554 	]i		only lists the first item below the cursor
    555 
    556 
    557 FINDING DEFINED IDENTIFIERS
    558 
    559 The "[I" command finds any identifier.  To find only macros, defined with
    560 "#define" use: >
    561 
    562 	[D
    563 
    564 Again, this searches in included files.  The 'define' option specifies what a
    565 line looks like that defines the items for "[D".  You could change it to make
    566 it work with other languages than C or C++.
    567    The commands related to "[D" are:
    568 
    569 	[d		only lists the first match
    570 	]D		only lists items below the cursor
    571 	]d		only lists the first item below the cursor
    572 
    573 ==============================================================================
    574 *29.5*	Finding local identifiers
    575 
    576 The "[I" command searches included files.  To search in the current file only,
    577 and jump to the first place where the word under the cursor is used: >
    578 
    579 	gD
    580 
    581 Hint: Goto Definition.  This command is very useful to find a variable or
    582 function that was declared locally ("static", in C terms).  Example (cursor on
    583 "counter"):
    584 
    585 	   +->   static int counter = 0;
    586 	   |
    587 	   |     int get_counter(void)
    588 	gD |     {
    589 	   |	     ++counter;
    590 	   +--	     return counter;
    591 		 }
    592 
    593 To restrict the search even further, and look only in the current function,
    594 use this command: >
    595 
    596 	gd
    597 
    598 This will go back to the start of the current function and find the first
    599 occurrence of the word under the cursor.  Actually, it searches backwards to
    600 an empty line above a "{" in the first column.  From there it searches forward
    601 for the identifier.  Example (cursor on "idx"):
    602 
    603 		int find_entry(char *name)
    604 		{
    605 	   +->	    int idx;
    606 	   |
    607 	gd |	    for (idx = 0; idx < table_len; ++idx)
    608 	   |		if (strcmp(table[idx].name, name) == 0)
    609 	   +--		    return idx;
    610 		}
    611 
    612 ==============================================================================
    613 
    614 Next chapter: |usr_30.txt|  Editing programs
    615 
    616 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: