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: