/usr/share/doc/vim-doc/html/tagsrch.html is in vim-doc 2:7.4.488-7+deb8u3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 | <HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: tagsrch</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: tagsrch</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>
<HR>
<PRE>
*<A NAME="tagsrch.txt"></A><B>tagsrch.txt</B>* For Vim version 7.4. Last change: 2013 Oct 01
VIM REFERENCE MANUAL by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>
Tags and special searches *<A NAME="tags-and-searches"></A><B>tags-and-searches</B>*
See section |<A HREF="usr_29.html#29.1">29.1</A>| of the user manual for an introduction.
1. Jump to a tag |<A HREF="#tag-commands">tag-commands</A>|
2. Tag stack |<A HREF="#tag-stack">tag-stack</A>|
3. Tag match list |<A HREF="#tag-matchlist">tag-matchlist</A>|
4. Tags details |<A HREF="#tag-details">tag-details</A>|
5. Tags file format |<A HREF="#tags-file-format">tags-file-format</A>|
6. Include file searches |<A HREF="#include-search">include-search</A>|
==============================================================================
1. Jump to a <A HREF="#tag">tag</A> *<A NAME="tag-commands"></A><B>tag-commands</B>*
*<A NAME="tag"></A><B>tag</B>* *<A NAME="tags"></A><B>tags</B>*
A <A HREF="#tag">tag</A> is an identifier that appears in a "<A HREF="#tags">tags</A>" file. It is a sort of label
that can be jumped to. For example: In C programs each function name can be
used <A HREF="motion.html#as">as</A> a <A HREF="#tag">tag</A>. The "<A HREF="#tags">tags</A>" file has to be generated by a program like <A HREF="#ctags">ctags</A>,
before the <A HREF="#tag">tag</A> commands can be used.
With the "<A HREF="#:tag">:tag</A>" command the cursor will be positioned on the <A HREF="#tag">tag</A>. With the
<A HREF="#CTRL-]">CTRL-]</A> command, the keyword on which the cursor is standing is used <A HREF="motion.html#as">as</A> the
<A HREF="#tag">tag</A>. If the cursor is not on a keyword, the first keyword to the right of the
cursor is used.
The "<A HREF="#:tag">:tag</A>" command works very well for C programs. If you see a call to a
function and wonder what that function does, position the cursor inside of the
function name and hit <A HREF="#CTRL-]">CTRL-]</A>. This will bring you to the function definition.
An <A HREF="starting.html#easy">easy</A> way back is with the <A HREF="#CTRL-T">CTRL-T</A> command. Also read about the <A HREF="#tag">tag</A> stack
below.
*<A NAME=":ta"></A><B>:ta</B>* *<A NAME=":tag"></A><B>:tag</B>* *<A NAME="E426"></A><B>E426</B>* *<A NAME="E429"></A><B>E429</B>*
:[count]ta[g][!] {ident}
Jump to the definition of {ident}, using the
information in the <A HREF="#tags">tags</A> file(s). Put {ident} in the
tag stack. See |<A HREF="#tag-!">tag-!</A>| for [!].
{ident} can be a regexp <A HREF="pattern.html#pattern">pattern</A>, see |<A HREF="#tag-regexp">tag-regexp</A>|.
When there are several matching <A HREF="#tags">tags</A> for {ident}, jump
to the <A HREF="intro.html#[count]">[count]</A> one. When <A HREF="intro.html#[count]">[count]</A> is omitted the
first one is jumped to. See |<A HREF="#tag-matchlist">tag-matchlist</A>| for
jumping to other matching <A HREF="#tags">tags</A>.
<A HREF="#g<LeftMouse>">g<LeftMouse></A> *<A NAME="g<LeftMouse>"></A><B>g<LeftMouse></B>*
<A HREF="#<C-LeftMouse>"><C-LeftMouse></A> *<A NAME="<C-LeftMouse>"></A><B><C-LeftMouse></B>* *<A NAME="CTRL-]"></A><B>CTRL-]</B>*
<A HREF="#CTRL-]">CTRL-]</A> Jump to the definition of the keyword under the
cursor. Same <A HREF="motion.html#as">as</A> "<A HREF="#:tag">:tag</A> {ident}", where {ident} is the
keyword under or after cursor.
When there are several matching <A HREF="#tags">tags</A> for {ident}, jump
to the <A HREF="intro.html#[count]">[count]</A> one. When no <A HREF="intro.html#[count]">[count]</A> is given the
first one is jumped to. See |<A HREF="#tag-matchlist">tag-matchlist</A>| for
jumping to other matching <A HREF="#tags">tags</A>.
{Vi: identifier after the cursor}
*<A NAME="v_CTRL-]"></A><B>v_CTRL-]</B>*
{Visual}CTRL-] Same <A HREF="motion.html#as">as</A> "<A HREF="#:tag">:tag</A> {ident}", where {ident} is the text that
is highlighted. {not in Vi}
*<A NAME="telnet-CTRL-]"></A><B>telnet-CTRL-]</B>*
<A HREF="#CTRL-]">CTRL-]</A> is the default telnet <A HREF="intro.html#escape">escape</A> key. When you type <A HREF="#CTRL-]">CTRL-]</A> to jump to a
<A HREF="#tag">tag</A>, you will get the telnet prompt instead. Most versions of telnet allow
<A HREF="change.html#changing">changing</A> or disabling the default <A HREF="intro.html#escape">escape</A> key. See the telnet man page. You
can 'telnet <A HREF="starting.html#-E">-E</A> {Hostname}' to disable the <A HREF="intro.html#escape">escape</A> character, or 'telnet <A HREF="starting.html#-e">-e</A>
{EscapeCharacter} {Hostname}' to specify another <A HREF="intro.html#escape">escape</A> character. If
possible, try to use "ssh" instead of "telnet" to avoid this problem.
*<A NAME="tag-priority"></A><B>tag-priority</B>*
When there are multiple matches for a <A HREF="#tag">tag</A>, this priority is used:
1. "FSC" A full matching static <A HREF="#tag">tag</A> for the current file.
2. "<A HREF="motion.html#F">F</A> C" A full matching global <A HREF="#tag">tag</A> for the current file.
3. "<A HREF="motion.html#F">F</A> " A full matching global <A HREF="#tag">tag</A> for another file.
4. "FS " A full matching static <A HREF="#tag">tag</A> for another file.
5. " SC" An ignore-case matching static <A HREF="#tag">tag</A> for the current file.
6. " C" An ignore-case matching global <A HREF="#tag">tag</A> for the current file.
7. " " An ignore-case matching global <A HREF="#tag">tag</A> for another file.
8. " <A HREF="change.html#S">S</A> " An ignore-case matching static <A HREF="#tag">tag</A> for another file.
Note that when the current file changes, the priority <A HREF="eval.html#list">list</A> is mostly not
changed, to avoid confusion when using "<A HREF="#:tnext">:tnext</A>". It is changed when using
"<A HREF="#:tag">:tag</A> {ident}".
The ignore-case matches are not found for a "<A HREF="#:tag">:tag</A>" command when the
<A HREF="options.html#'ignorecase'">'ignorecase'</A> option is off. They are found when a <A HREF="pattern.html#pattern">pattern</A> is used (starting
with a "<A HREF="pattern.html#/">/</A>") and for "<A HREF="#:tselect">:tselect</A>", also when <A HREF="options.html#'ignorecase'">'ignorecase'</A> is off. Note that
using ignore-case <A HREF="#tag">tag</A> searching disables binary searching in the <A HREF="#tags">tags</A> file,
which causes a slowdown. This can be avoided by fold-case <A HREF="change.html#sorting">sorting</A> the <A HREF="#tag">tag</A>
file. See the <A HREF="options.html#'tagbsearch'">'tagbsearch'</A> option for an explanation.
==============================================================================
2. Tag stack *<A NAME="tag-stack"></A><B>tag-stack</B>* *<A NAME="tagstack"></A><B>tagstack</B>* *<A NAME="E425"></A><B>E425</B>*
On the <A HREF="#tag">tag</A> stack is remembered which <A HREF="#tags">tags</A> you jumped to, and from where.
Tags are only pushed onto the stack when the <A HREF="options.html#'tagstack'">'tagstack'</A> option is set.
<A HREF="#g<RightMouse>">g<RightMouse></A> *<A NAME="g<RightMouse>"></A><B>g<RightMouse></B>*
<A HREF="#<C-RightMouse>"><C-RightMouse></A> *<A NAME="<C-RightMouse>"></A><B><C-RightMouse></B>* *<A NAME="CTRL-T"></A><B>CTRL-T</B>*
<A HREF="#CTRL-T">CTRL-T</A> Jump to <A HREF="intro.html#[count]">[count]</A> older entry in the <A HREF="#tag">tag</A> stack
(default 1). {not in Vi}
*<A NAME=":po"></A><B>:po</B>* *<A NAME=":pop"></A><B>:pop</B>* *<A NAME="E555"></A><B>E555</B>* *<A NAME="E556"></A><B>E556</B>*
:[count]po[p][!] Jump to <A HREF="intro.html#[count]">[count]</A> older entry in <A HREF="#tag">tag</A> stack (default 1).
See |<A HREF="#tag-!">tag-!</A>| for [!]. {not in Vi}
:[count]ta[g][!] Jump to <A HREF="intro.html#[count]">[count]</A> newer entry in <A HREF="#tag">tag</A> stack (default 1).
See |<A HREF="#tag-!">tag-!</A>| for [!]. {not in Vi}
*<A NAME=":tags"></A><B>:tags</B>*
<A HREF="#:tags">:tags</A> Show the contents of the <A HREF="#tag">tag</A> stack. The active
entry is marked with a '<A HREF="change.html#>">></A>'. {not in Vi}
The output of "<A HREF="#:tags">:tags</A>" looks like this:
# TO <A HREF="#tag">tag</A> FROM line in file/text
1 1 main 1 harddisk2:text/vim/test
<A HREF="change.html#>">></A> 2 2 FuncA 58 <A HREF="insert.html#i">i</A> = FuncA(10);
3 1 FuncC 357 harddisk2:text/vim/src/amiga.c
This <A HREF="eval.html#list">list</A> shows the <A HREF="#tags">tags</A> that you jumped to and the cursor position before
that jump. The older <A HREF="#tags">tags</A> are at the top, the newer at the bottom.
The '<A HREF="change.html#>">></A>' points to the active entry. This is the <A HREF="#tag">tag</A> that will be used by the
next "<A HREF="#:tag">:tag</A>" command. The <A HREF="#CTRL-T">CTRL-T</A> and "<A HREF="#:pop">:pop</A>" command will use the position
above the active entry.
Below the "TO" is the number of the current match in the match <A HREF="eval.html#list">list</A>. Note
that this doesn't change when using "<A HREF="#:pop">:pop</A>" or "<A HREF="#:tag">:tag</A>".
The line number and file name are remembered to be able to get back to where
you were before the <A HREF="#tag">tag</A> command. The line number will be correct, also when
deleting/inserting lines, unless this was done by another program (e.g.
another instance of Vim).
For the current file, the "file/text" column shows the text at the position.
An indent is removed and a long line is truncated to fit in the <A HREF="windows.html#window">window</A>.
You can jump to previously used <A HREF="#tags">tags</A> with several commands. Some examples:
"<A HREF="#:pop">:pop</A>" or <A HREF="#CTRL-T">CTRL-T</A> to position before previous <A HREF="#tag">tag</A>
{count}CTRL-T to position before {count} older <A HREF="#tag">tag</A>
"<A HREF="#:tag">:tag</A>" to newer <A HREF="#tag">tag</A>
":0tag" to last used <A HREF="#tag">tag</A>
The most obvious way to use this is while browsing through the call graph of
a program. Consider the following call graph:
main ---> FuncA ---> FuncC
---> FuncB
(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
You can get from main to FuncA by using <A HREF="#CTRL-]">CTRL-]</A> on the call to FuncA. Then
you can <A HREF="#CTRL-]">CTRL-]</A> to get to FuncC. If you now want to go back to main you can
use <A HREF="#CTRL-T">CTRL-T</A> <A HREF="if_cscop.html#twice">twice</A>. Then you can <A HREF="#CTRL-]">CTRL-]</A> to FuncB.
If you issue a "<A HREF="#:ta">:ta</A> {ident}" or <A HREF="#CTRL-]">CTRL-]</A> command, this <A HREF="#tag">tag</A> is inserted at the
current position in the stack. If the stack was full (it can hold up to 20
entries), the oldest entry is deleted and the older entries <A HREF="intro.html#shift">shift</A> one
position up (their index number is decremented by one). If the last used
entry was not at the bottom, the entries below the last used one are
deleted. This means that an old branch in the call graph is lost. After the
commands explained above the <A HREF="#tag">tag</A> stack will look like this:
# TO <A HREF="#tag">tag</A> FROM line in file/text
1 1 main 1 harddisk2:text/vim/test
2 1 FuncB 59 harddisk2:text/vim/src/main.c
*<A NAME="E73"></A><B>E73</B>*
When you try to use the <A HREF="#tag">tag</A> stack while <A HREF="motion.html#it">it</A> doesn't contain anything you will
get an error message.
==============================================================================
3. Tag match <A HREF="eval.html#list">list</A> *<A NAME="tag-matchlist"></A><B>tag-matchlist</B>* *<A NAME="E427"></A><B>E427</B>* *<A NAME="E428"></A><B>E428</B>*
When there are several matching <A HREF="#tags">tags</A>, these commands can be used to jump
between them. Note that these commands don't change the <A HREF="#tag">tag</A> stack, they keep
the same entry.
*<A NAME=":ts"></A><B>:ts</B>* *<A NAME=":tselect"></A><B>:tselect</B>*
:ts[elect][!] [ident] <A HREF="eval.html#List">List</A> the <A HREF="#tags">tags</A> that match [ident], using the
information in the <A HREF="#tags">tags</A> file(s).
When [ident] is not given, the last <A HREF="#tag">tag</A> name from the
<A HREF="#tag">tag</A> stack is used.
With a '<A HREF="change.html#>">></A>' in the first column is indicated which is
the current position in the <A HREF="eval.html#list">list</A> (if there is one).
[ident] can be a regexp <A HREF="pattern.html#pattern">pattern</A>, see |<A HREF="#tag-regexp">tag-regexp</A>|.
See |<A HREF="#tag-priority">tag-priority</A>| for the priorities used in the
listing. {not in Vi}
Example output:
<B> nr pri kind tag file</B>
<B> 1 F f mch_delay os_amiga.c</B>
<B> mch_delay(msec, ignoreinput)</B>
<B> > 2 F f mch_delay os_msdos.c</B>
<B> mch_delay(msec, ignoreinput)</B>
<B> 3 F f mch_delay os_unix.c</B>
<B> mch_delay(msec, ignoreinput)</B>
<B> Enter nr of choice (<CR> to abort):</B>
See |<A HREF="#tag-priority">tag-priority</A>| for the "pri" column. Note that
this depends on the current file, thus using
"<A HREF="#:tselect">:tselect</A> xxx" can produce different results.
The "kind" column gives the kind of <A HREF="#tag">tag</A>, if this was
included in the <A HREF="#tags">tags</A> file.
The "info" column shows information that could be
found in the <A HREF="#tags">tags</A> file. It depends on the program
that produced the <A HREF="#tags">tags</A> file.
When the <A HREF="eval.html#list">list</A> is long, you may get the |<A HREF="message.html#more-prompt">more-prompt</A>|.
If you already see the <A HREF="#tag">tag</A> you want to use, you can
type '<A HREF="repeat.html#q">q</A>' and enter the number.
*<A NAME=":sts"></A><B>:sts</B>* *<A NAME=":stselect"></A><B>:stselect</B>*
:sts[elect][!] [ident] Does ":tselect[!] [ident]" and splits the <A HREF="windows.html#window">window</A> for
the selected <A HREF="#tag">tag</A>. {not in Vi}
*<A NAME="g]"></A><B>g]</B>*
<A HREF="#g]">g]</A> Like <A HREF="#CTRL-]">CTRL-]</A>, but use "<A HREF="#:tselect">:tselect</A>" instead of "<A HREF="#:tag">:tag</A>".
{not in Vi}
*<A NAME="v_g]"></A><B>v_g]</B>*
{Visual}g] Same <A HREF="motion.html#as">as</A> "<A HREF="#g]">g]</A>", but use the highlighted text <A HREF="motion.html#as">as</A> the
identifier. {not in Vi}
*<A NAME=":tj"></A><B>:tj</B>* *<A NAME=":tjump"></A><B>:tjump</B>*
:tj[ump][!] [ident] Like "<A HREF="#:tselect">:tselect</A>", but jump to the <A HREF="#tag">tag</A> directly when
there is only one match. {not in Vi}
*<A NAME=":stj"></A><B>:stj</B>* *<A NAME=":stjump"></A><B>:stjump</B>*
:stj[ump][!] [ident] Does ":tjump[!] [ident]" and splits the <A HREF="windows.html#window">window</A> for the
selected <A HREF="#tag">tag</A>. {not in Vi}
*<A NAME="g_CTRL-]"></A><B>g_CTRL-]</B>*
<A HREF="index.html#g">g</A> <A HREF="#CTRL-]">CTRL-]</A> Like <A HREF="#CTRL-]">CTRL-]</A>, but use "<A HREF="#:tjump">:tjump</A>" instead of "<A HREF="#:tag">:tag</A>".
{not in Vi}
*<A NAME="v_g_CTRL-]"></A><B>v_g_CTRL-]</B>*
{Visual}g <A HREF="#CTRL-]">CTRL-]</A> Same <A HREF="motion.html#as">as</A> "g CTRL-]", but use the highlighted text <A HREF="motion.html#as">as</A>
the identifier. {not in Vi}
*<A NAME=":tn"></A><B>:tn</B>* *<A NAME=":tnext"></A><B>:tnext</B>*
:[count]tn[ext][!] Jump to <A HREF="intro.html#[count]">[count]</A> next matching <A HREF="#tag">tag</A> (default 1). See
|<A HREF="#tag-!">tag-!</A>| for [!]. {not in Vi}
*<A NAME=":tp"></A><B>:tp</B>* *<A NAME=":tprevious"></A><B>:tprevious</B>*
:[count]tp[revious][!] Jump to <A HREF="intro.html#[count]">[count]</A> previous matching <A HREF="#tag">tag</A> (default 1).
See |<A HREF="#tag-!">tag-!</A>| for [!]. {not in Vi}
*<A NAME=":tN"></A><B>:tN</B>* *<A NAME=":tNext"></A><B>:tNext</B>*
:[count]tN[ext][!] Same <A HREF="motion.html#as">as</A> "<A HREF="#:tprevious">:tprevious</A>". {not in Vi}
*<A NAME=":tr"></A><B>:tr</B>* *<A NAME=":trewind"></A><B>:trewind</B>*
:[count]tr[ewind][!] Jump to first matching <A HREF="#tag">tag</A>. If <A HREF="intro.html#[count]">[count]</A> is given, jump
to [count]th matching tag. See |<A HREF="#tag-!">tag-!</A>| for [!]. {not
in Vi}
*<A NAME=":tf"></A><B>:tf</B>* *<A NAME=":tfirst"></A><B>:tfirst</B>*
:[count]tf[irst][!] Same <A HREF="motion.html#as">as</A> "<A HREF="#:trewind">:trewind</A>". {not in Vi}
*<A NAME=":tl"></A><B>:tl</B>* *<A NAME=":tlast"></A><B>:tlast</B>*
:tl[ast][!] Jump to last matching tag. See |<A HREF="#tag-!">tag-!</A>| for [!]. {not
in Vi}
*<A NAME=":lt"></A><B>:lt</B>* *<A NAME=":ltag"></A><B>:ltag</B>*
:lt[ag][!] [ident] Jump to <A HREF="#tag">tag</A> [ident] and add the matching <A HREF="#tags">tags</A> to a new
location <A HREF="eval.html#list">list</A> for the current <A HREF="windows.html#window">window</A>. [ident] can be
a regexp <A HREF="pattern.html#pattern">pattern</A>, see |<A HREF="#tag-regexp">tag-regexp</A>|. When [ident] is
not given, the last <A HREF="#tag">tag</A> name from the <A HREF="#tag">tag</A> stack is
used. The search <A HREF="pattern.html#pattern">pattern</A> to locate the <A HREF="#tag">tag</A> line is
prefixed with "\V" to <A HREF="intro.html#escape">escape</A> all the special
characters (very nomagic). The location <A HREF="eval.html#list">list</A> showing
the matching <A HREF="#tags">tags</A> is independent of the <A HREF="#tag">tag</A> stack.
See |<A HREF="#tag-!">tag-!</A>| for [!].
{not in Vi}
When there is no other message, Vim shows which matching <A HREF="#tag">tag</A> has been jumped
to, and the number of matching <A HREF="#tags">tags</A>:
<B> tag 1 of 3 or more</B>
The " or more" is used to indicate that Vim didn't try all the <A HREF="#tags">tags</A> files yet.
When using "<A HREF="#:tnext">:tnext</A>" a few times, or with "<A HREF="#:tlast">:tlast</A>", more matches may be found.
When you didn't see this message because of some other message, or you just
want to know where you are, this command will show <A HREF="motion.html#it">it</A> again (and jump to the
same <A HREF="#tag">tag</A> <A HREF="motion.html#as">as</A> last time):
<B> :0tn</B>
*<A NAME="tag-skip-file"></A><B>tag-skip-file</B>*
When a matching <A HREF="#tag">tag</A> is found for which the file doesn't exist, this match is
skipped and the next matching <A HREF="#tag">tag</A> is used. Vim reports this, to notify you of
missing files. When the end of the <A HREF="eval.html#list">list</A> of matches has been reached, an error
message is given.
*<A NAME="tag-preview"></A><B>tag-preview</B>*
The <A HREF="#tag">tag</A> match <A HREF="eval.html#list">list</A> can also be used in the preview <A HREF="windows.html#window">window</A>. The commands are
the same <A HREF="motion.html#as">as</A> above, with a "<A HREF="change.html#p">p</A>" prepended.
{not available when compiled without the |<A HREF="various.html#+quickfix">+quickfix</A>| feature}
*<A NAME=":pts"></A><B>:pts</B>* *<A NAME=":ptselect"></A><B>:ptselect</B>*
:pts[elect][!] [ident] Does ":tselect[!] [ident]" and shows the new <A HREF="#tag">tag</A> in a
"Preview" <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>| for more info.
{not in Vi}
*<A NAME=":ptj"></A><B>:ptj</B>* *<A NAME=":ptjump"></A><B>:ptjump</B>*
:ptj[ump][!] [ident] Does ":tjump[!] [ident]" and shows the new <A HREF="#tag">tag</A> in a
"Preview" <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>| for more info.
{not in Vi}
*<A NAME=":ptn"></A><B>:ptn</B>* *<A NAME=":ptnext"></A><B>:ptnext</B>*
:[count]ptn[ext][!] "<A HREF="#:tnext">:tnext</A>" in the preview <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>|.
{not in Vi}
*<A NAME=":ptp"></A><B>:ptp</B>* *<A NAME=":ptprevious"></A><B>:ptprevious</B>*
:[count]ptp[revious][!] "<A HREF="#:tprevious">:tprevious</A>" in the preview <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>|.
{not in Vi}
*<A NAME=":ptN"></A><B>:ptN</B>* *<A NAME=":ptNext"></A><B>:ptNext</B>*
:[count]ptN[ext][!] Same <A HREF="motion.html#as">as</A> "<A HREF="#:ptprevious">:ptprevious</A>". {not in Vi}
*<A NAME=":ptr"></A><B>:ptr</B>* *<A NAME=":ptrewind"></A><B>:ptrewind</B>*
:[count]ptr[ewind][!] "<A HREF="#:trewind">:trewind</A>" in the preview <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>|.
{not in Vi}
*<A NAME=":ptf"></A><B>:ptf</B>* *<A NAME=":ptfirst"></A><B>:ptfirst</B>*
:[count]ptf[irst][!] Same <A HREF="motion.html#as">as</A> "<A HREF="#:ptrewind">:ptrewind</A>". {not in Vi}
*<A NAME=":ptl"></A><B>:ptl</B>* *<A NAME=":ptlast"></A><B>:ptlast</B>*
:ptl[ast][!] "<A HREF="#:tlast">:tlast</A>" in the preview <A HREF="windows.html#window">window</A>. See |<A HREF="windows.html#:ptag">:ptag</A>|.
{not in Vi}
==============================================================================
4. Tags details *<A NAME="tag-details"></A><B>tag-details</B>*
*<A NAME="static-tag"></A><B>static-tag</B>*
A static <A HREF="#tag">tag</A> is a <A HREF="#tag">tag</A> that is defined for a specific file. In a C program
this could be a static function.
In <A HREF="intro.html#Vi">Vi</A> jumping to a <A HREF="#tag">tag</A> sets the current search <A HREF="pattern.html#pattern">pattern</A>. This means that
the "<A HREF="pattern.html#n">n</A>" command after jumping to a <A HREF="#tag">tag</A> does not search for the same <A HREF="pattern.html#pattern">pattern</A>
that <A HREF="motion.html#it">it</A> did before jumping to the <A HREF="#tag">tag</A>. Vim does not <A HREF="diff.html#do">do</A> this <A HREF="motion.html#as">as</A> we consider <A HREF="motion.html#it">it</A>
to be a bug. You can still find the <A HREF="#tag">tag</A> search <A HREF="pattern.html#pattern">pattern</A> in the search <A HREF="cmdline.html#history">history</A>.
If you really want the old <A HREF="intro.html#Vi">Vi</A> behavior, set the '<A HREF="motion.html#t">t</A>' flag in <A HREF="options.html#'cpoptions'">'cpoptions'</A>.
*<A NAME="tag-binary-search"></A><B>tag-binary-search</B>*
Vim uses binary searching in the <A HREF="#tags">tags</A> file to find the desired <A HREF="#tag">tag</A> quickly
(when enabled at compile time |<A HREF="various.html#+tag_binary">+tag_binary</A>|). But this only works if the
<A HREF="#tags">tags</A> file was sorted on ASCII byte value. Therefore, if no match was found,
another try is done with a linear search. If you only want the linear search,
reset the <A HREF="options.html#'tagbsearch'">'tagbsearch'</A> option. Or better: Sort the <A HREF="#tags">tags</A> file!
Note that the binary searching is disabled when not looking for a <A HREF="#tag">tag</A> with a
specific name. This happens when ignoring <A HREF="change.html#case">case</A> and when a regular <A HREF="eval.html#expression">expression</A>
is used that doesn't start with a fixed <A HREF="eval.html#string">string</A>. Tag searching can be a lot
slower then. The former can be avoided by case-fold <A HREF="change.html#sorting">sorting</A> the <A HREF="#tags">tags</A> file.
See <A HREF="options.html#'tagbsearch'">'tagbsearch'</A> for details.
*<A NAME="tag-regexp"></A><B>tag-regexp</B>*
The "<A HREF="#:tag">:tag</A>" and "<A HREF="#:tselect">:tselect</A>" commands accept a regular <A HREF="eval.html#expression">expression</A> argument. See
|<A HREF="pattern.html#pattern">pattern</A>| for the special characters that can be used.
When the argument starts with '<A HREF="pattern.html#/">/</A>', <A HREF="motion.html#it">it</A> is used <A HREF="motion.html#as">as</A> a <A HREF="pattern.html#pattern">pattern</A>. If the argument
does not start with '<A HREF="pattern.html#/">/</A>', <A HREF="motion.html#it">it</A> is taken literally, <A HREF="motion.html#as">as</A> a full <A HREF="#tag">tag</A> name.
Examples:
<B> :tag main</B>
jumps to the <A HREF="#tag">tag</A> "main" that has the highest priority.
<B> :tag /^get</B>
jumps to the <A HREF="#tag">tag</A> that starts with "get" and has the highest priority.
<B> :tag /norm</B>
lists all the <A HREF="#tags">tags</A> that contain "norm", including "id_norm".
When the argument both exists literally, and match when used <A HREF="motion.html#as">as</A> a <A HREF="pattern.html#regexp">regexp</A>, a
literal match has a higher priority. For example, "<A HREF="#:tag">:tag</A> /open" matches "open"
before "open_file" and "file_open".
When using a <A HREF="pattern.html#pattern">pattern</A> <A HREF="change.html#case">case</A> is ignored. If you want to match <A HREF="change.html#case">case</A> use "\C" in
the <A HREF="pattern.html#pattern">pattern</A>.
*<A NAME="tag-!"></A><B>tag-!</B>*
If the <A HREF="#tag">tag</A> is in the current file this will always work. Otherwise the
performed actions depend on whether the current file was changed, whether a !
is added to the command and on the <A HREF="options.html#'autowrite'">'autowrite'</A> option:
<B><FONT COLOR="PURPLE"> tag in file autowrite </FONT></B>
<B><FONT COLOR="PURPLE">current file changed ! option action </FONT></B>
-----------------------------------------------------------------------------
yes <A HREF="change.html#x">x</A> <A HREF="change.html#x">x</A> <A HREF="change.html#x">x</A> goto <A HREF="#tag">tag</A>
no no <A HREF="change.html#x">x</A> <A HREF="change.html#x">x</A> read other file, goto <A HREF="#tag">tag</A>
no yes yes <A HREF="change.html#x">x</A> <A HREF="editing.html#abandon">abandon</A> current file, read other file, goto
<A HREF="#tag">tag</A>
no yes no on write current file, read other file, goto
<A HREF="#tag">tag</A>
no yes no off fail
-----------------------------------------------------------------------------
- If the <A HREF="#tag">tag</A> is in the current file, the command will always work.
- If the <A HREF="#tag">tag</A> is in another file and the current file was not changed, the
other file will be made the current file and read into the buffer.
- If the <A HREF="#tag">tag</A> is in another file, the current file was changed and a ! is
added to the command, the changes to the current file are lost, the other
file will be made the current file and read into the buffer.
- If the <A HREF="#tag">tag</A> is in another file, the current file was changed and the
<A HREF="options.html#'autowrite'">'autowrite'</A> option is on, the current file will be written, the other
file will be made the current file and read into the buffer.
- If the <A HREF="#tag">tag</A> is in another file, the current file was changed and the
<A HREF="options.html#'autowrite'">'autowrite'</A> option is off, the command will fail. If you want to save
the changes, use the "<A HREF="editing.html#:w">:w</A>" command and then use "<A HREF="#:tag">:tag</A>" without an argument.
This works because the <A HREF="#tag">tag</A> is put on the stack anyway. If you want to lose
the changes you can use the ":tag!" command.
*<A NAME="tag-security"></A><B>tag-security</B>*
Note that Vim forbids some commands, for security reasons. This works like
using the <A HREF="options.html#'secure'">'secure'</A> option for exrc/vimrc files in the current directory. See
|<A HREF="starting.html#trojan-horse">trojan-horse</A>| and |<A HREF="eval.html#sandbox">sandbox</A>|.
When the {tagaddress} changes a buffer, you will get a warning message:
"WARNING: <A HREF="#tag">tag</A> command changed a buffer!!!"
In a future version <A HREF="change.html#changing">changing</A> the buffer will be impossible. All this for
security reasons: Somebody might hide a nasty command in the <A HREF="#tags">tags</A> file, which
would otherwise go unnoticed. Example:
<B> :$d|/tag-function-name/</B>
{this security prevention is not present in Vi}
In <A HREF="intro.html#Vi">Vi</A> the "<A HREF="#:tag">:tag</A>" command sets the last search <A HREF="pattern.html#pattern">pattern</A> when the <A HREF="#tag">tag</A> is searched
for. In Vim this is not done, the previous search <A HREF="pattern.html#pattern">pattern</A> is still remembered,
unless the '<A HREF="motion.html#t">t</A>' flag is present in <A HREF="options.html#'cpoptions'">'cpoptions'</A>. The search <A HREF="pattern.html#pattern">pattern</A> is always
put in the search <A HREF="cmdline.html#history">history</A>, so you can modify <A HREF="motion.html#it">it</A> if searching fails.
*<A NAME="emacs-tags"></A><B>emacs-tags</B>* *<A NAME="emacs_tags"></A><B>emacs_tags</B>* *<A NAME="E430"></A><B>E430</B>*
Emacs style <A HREF="#tag">tag</A> files are only supported if Vim was compiled with the
|<A HREF="various.html#+emacs_tags">+emacs_tags</A>| feature enabled. Sorry, there is no explanation about Emacs tag
files here, <A HREF="motion.html#it">it</A> is only supported for backwards compatibility :-).
Lines in Emacs <A HREF="#tags">tags</A> files can be very long. Vim only deals with lines of up
to about 510 bytes. To see whether lines are ignored set <A HREF="options.html#'verbose'">'verbose'</A> to 5 or
higher.
*<A NAME="tags-option"></A><B>tags-option</B>*
The <A HREF="options.html#'tags'">'tags'</A> option is a <A HREF="eval.html#list">list</A> of file names. Each of these files is searched
for the <A HREF="#tag">tag</A>. This can be used to use a different <A HREF="#tags">tags</A> file than the default
file "<A HREF="#tags">tags</A>". It can also be used to access a common <A HREF="#tags">tags</A> file.
The next file in the <A HREF="eval.html#list">list</A> is not used when:
- A matching static <A HREF="#tag">tag</A> for the current buffer has been found.
- A matching global <A HREF="#tag">tag</A> has been found.
This also depends on the <A HREF="options.html#'ignorecase'">'ignorecase'</A> option. If <A HREF="motion.html#it">it</A> is off, and the <A HREF="#tags">tags</A> file
only has a match without matching <A HREF="change.html#case">case</A>, the next <A HREF="#tags">tags</A> file is searched for a
match with matching <A HREF="change.html#case">case</A>. If no <A HREF="#tag">tag</A> with matching <A HREF="change.html#case">case</A> is found, the first
match without matching <A HREF="change.html#case">case</A> is used. If <A HREF="options.html#'ignorecase'">'ignorecase'</A> is on, and a matching
global <A HREF="#tag">tag</A> with or without matching <A HREF="change.html#case">case</A> is found, this one is used, no
further <A HREF="#tags">tags</A> files are searched.
When a <A HREF="#tag">tag</A> file name starts with "./", the '<A HREF="repeat.html#.">.</A>' is replaced with the path of
the current file. This makes <A HREF="motion.html#it">it</A> possible to use a <A HREF="#tags">tags</A> file in the directory
where the current file is (no matter what the current directory is). The idea
of using "./" is that you can define which <A HREF="#tag">tag</A> file is searched first: In the
current directory ("tags,./tags") or in the directory of the current file
("./tags,tags").
For example:
<B> :set tags=./tags,tags,/home/user/commontags</B>
In this example the <A HREF="#tag">tag</A> will first be searched for in the file "<A HREF="#tags">tags</A>" in the
directory where the current file is. Next the "<A HREF="#tags">tags</A>" file in the current
directory. If <A HREF="motion.html#it">it</A> is not found there, then the file "/home/user/commontags"
will be searched for the <A HREF="#tag">tag</A>.
This can be switched off by including the '<A HREF="change.html#d">d</A>' flag in <A HREF="options.html#'cpoptions'">'cpoptions'</A>, to make
<A HREF="motion.html#it">it</A> <A HREF="intro.html#Vi">Vi</A> compatible. "./tags" will then be the <A HREF="#tags">tags</A> file in the current
directory, instead of the <A HREF="#tags">tags</A> file in the directory where the current file
is.
Instead of the comma a space may be used. Then a <A HREF="intro.html#backslash">backslash</A> is required for
the space to be included in the <A HREF="eval.html#string">string</A> option:
<B> :set tags=tags\ /home/user/commontags</B>
To include a space in a file name use three backslashes. To include a comma
in a file name use two backslashes. For example, use:
<B> :set tags=tag\\\ file,/home/user/common\\,tags</B>
for the files "<A HREF="#tag">tag</A> file" and "/home/user/common,tags". The <A HREF="options.html#'tags'">'tags'</A> option will
have the value "tag\ file,/home/user/common\,tags".
If the <A HREF="options.html#'tagrelative'">'tagrelative'</A> option is on (which is the default) and using a <A HREF="#tag">tag</A> file
in another directory, file names in that <A HREF="#tag">tag</A> file are relative to the
directory where the <A HREF="#tag">tag</A> file is.
==============================================================================
5. Tags file format *<A NAME="tags-file-format"></A><B>tags-file-format</B>* *<A NAME="E431"></A><B>E431</B>*
*<A NAME="ctags"></A><B>ctags</B>* *<A NAME="jtags"></A><B>jtags</B>*
A <A HREF="#tags">tags</A> file can be created with an external command, for example "<A HREF="#ctags">ctags</A>". It
will contain a <A HREF="#tag">tag</A> for each function. Some versions of "<A HREF="#ctags">ctags</A>" will also make
a <A HREF="#tag">tag</A> for each "#defined" <A HREF="map.html#macro">macro</A>, typedefs, enums, etc.
Some programs that generate <A HREF="#tags">tags</A> files:
<A HREF="#ctags">ctags</A> As found on most <A HREF="os_unix.html#Unix">Unix</A> systems. Only supports C. Only
does the basic work.
*<A NAME="Exuberant_ctags"></A><B>Exuberant_ctags</B>*
exuberant <A HREF="#ctags">ctags</A> This a very good one. It works for C, C++, Java,
Fortran, Eiffel and others. It can generate <A HREF="#tags">tags</A> for
many items. See <A HREF="http://ctags.sourceforge.net">http://ctags.sourceforge.net</A>.
etags Connected to Emacs. Supports many languages.
JTags For Java, in Java. It can be found at
<A HREF="http://www.fleiner.com/jtags/">http://www.fleiner.com/jtags/</A>.
ptags.py For <A HREF="if_pyth.html#Python">Python</A>, in <A HREF="if_pyth.html#Python">Python</A>. Found in your <A HREF="if_pyth.html#Python">Python</A> source
directory at Tools/scripts/ptags.py.
ptags For <A HREF="if_perl.html#Perl">Perl</A>, in <A HREF="if_perl.html#Perl">Perl</A>. It can be found at
<A HREF="http://www.eleves.ens.fr:8080/home/nthiery/Tags/">http://www.eleves.ens.fr:8080/home/nthiery/Tags/</A>.
gnatxref For Ada. See <A HREF="http://www.gnuada.org/">http://www.gnuada.org/</A>. gnatxref is
part of the gnat package.
The lines in the <A HREF="#tags">tags</A> file must have one of these three formats:
1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress}
3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
The first is a normal <A HREF="#tag">tag</A>, which is completely compatible with <A HREF="intro.html#Vi">Vi</A>. It is the
only format produced by traditional <A HREF="#ctags">ctags</A> implementations. This is often used
for <A HREF="eval.html#functions">functions</A> that are global, also referenced in other files.
The lines in the <A HREF="#tags">tags</A> file can end in <LF> or <CR><LF>. On the <A HREF="os_mac.html#Macintosh">Macintosh</A> <A HREF="motion.html#<CR>"><CR></A>
also works. The <A HREF="motion.html#<CR>"><CR></A> and <A HREF="motion.html#<NL>"><NL></A> characters can never appear inside a line.
*<A NAME="tag-old-static"></A><B>tag-old-static</B>*
The second format is for a static <A HREF="#tag">tag</A> only. It is obsolete now, replaced by
the third format. It is only supported by <A HREF="intro.html#Elvis">Elvis</A> 1.x and Vim and a few
versions of <A HREF="#ctags">ctags</A>. A static <A HREF="#tag">tag</A> is often used for <A HREF="eval.html#functions">functions</A> that are local,
only referenced in the file {tagfile}. Note that for the static <A HREF="#tag">tag</A>, the two
occurrences of {tagfile} must be exactly the same. Also see |<A HREF="#tags-option">tags-option</A>|
below, for how static <A HREF="#tags">tags</A> are used.
The third format is new. It includes additional information in optional
fields at the end of each line. It is backwards compatible with <A HREF="intro.html#Vi">Vi</A>. It is
only supported by new versions of <A HREF="#ctags">ctags</A> (such <A HREF="motion.html#as">as</A> Exuberant <A HREF="#ctags">ctags</A>).
{tagname} The identifier. Normally the name of a function, but <A HREF="motion.html#it">it</A> can
be any identifier. It cannot contain a <A HREF="motion.html#<Tab>"><Tab></A>.
{TAB} One <A HREF="motion.html#<Tab>"><Tab></A> character. Note: previous versions allowed any
white space here. This has been abandoned to allow spaces in
{tagfile}. It can be re-enabled by including the
|<A HREF="various.html#+tag_any_white">+tag_any_white</A>| feature at compile time. *<A NAME="tag-any-white"></A><B>tag-any-white</B>*
{tagfile} The file that contains the definition of {tagname}. It can
have an absolute or relative path. It may contain environment
<A HREF="eval.html#variables">variables</A> and <A HREF="editing.html#wildcards">wildcards</A> (although the use of <A HREF="editing.html#wildcards">wildcards</A> is
doubtful). It cannot contain a <A HREF="motion.html#<Tab>"><Tab></A>.
{tagaddress} The <A HREF="intro.html#Ex">Ex</A> command that positions the cursor on the <A HREF="#tag">tag</A>. It can
be any <A HREF="intro.html#Ex">Ex</A> command, although restrictions apply (see
|<A HREF="#tag-security">tag-security</A>|). <A HREF="intro.html#Posix">Posix</A> only allows line numbers and search
commands, which are mostly used.
{term} ;" The two characters semicolon and double <A HREF="change.html#quote.">quote.</A> This is
interpreted by <A HREF="intro.html#Vi">Vi</A> <A HREF="motion.html#as">as</A> the start of a comment, which makes the
following be ignored. This is for backwards compatibility
with <A HREF="intro.html#Vi">Vi</A>, <A HREF="motion.html#it">it</A> ignores the following fields.
{field} .. A <A HREF="eval.html#list">list</A> of optional fields. Each field has the form:
<Tab>{fieldname}:{value}
The {fieldname} identifies the field, and can only contain
alphabetical characters [a-zA-Z].
The {value} is any <A HREF="eval.html#string">string</A>, but cannot contain a <A HREF="motion.html#<Tab>"><Tab></A>.
These characters are special:
"\t" stands for a <A HREF="motion.html#<Tab>"><Tab></A>
"\r" stands for a <A HREF="motion.html#<CR>"><CR></A>
"\n" stands for a <A HREF="motion.html#<NL>"><NL></A>
"\\" stands for a single '\' character
There is one field that doesn't have a '<A HREF="cmdline.html#:">:</A>'. This is the kind
of the <A HREF="#tag">tag</A>. It is handled like <A HREF="motion.html#it">it</A> was preceded with "kind:".
See the documentation of <A HREF="#ctags">ctags</A> for the kinds <A HREF="motion.html#it">it</A> produces.
The only other field currently recognized by Vim is "file:"
(with an empty value). It is used for a static <A HREF="#tag">tag</A>.
The first lines in the <A HREF="#tags">tags</A> file can contain lines that start with
!_TAG_
These are sorted to the first lines, only rare <A HREF="#tags">tags</A> that start with "<A HREF="change.html#!">!</A>" can
sort to before them. Vim recognizes two items. The first one is the line
that indicates if the file was sorted. When this line is found, Vim uses
binary searching for the <A HREF="#tags">tags</A> file:
<B><FONT COLOR="PURPLE"> !_TAG_FILE_SORTED<Tab>1<Tab>{anything} </FONT></B>
A <A HREF="#tag">tag</A> file may be case-fold sorted to avoid a linear search when <A HREF="options.html#'ignorecase'">'ignorecase'</A>
is on. See <A HREF="options.html#'tagbsearch'">'tagbsearch'</A> for details. The value '2' should be used then:
<B><FONT COLOR="PURPLE"> !_TAG_FILE_SORTED<Tab>2<Tab>{anything} </FONT></B>
The other <A HREF="#tag">tag</A> that Vim recognizes, but only when compiled with the
|<A HREF="various.html#+multi_byte">+multi_byte</A>| feature, is the encoding of the <A HREF="#tags">tags</A> file:
<B><FONT COLOR="PURPLE"> !_TAG_FILE_ENCODING<Tab>utf-8<Tab>{anything} </FONT></B>
Here "<A HREF="mbyte.html#utf-8">utf-8</A>" is the encoding used for the <A HREF="#tags">tags</A>. Vim will then convert the <A HREF="#tag">tag</A>
being searched for from <A HREF="options.html#'encoding'">'encoding'</A> to the encoding of the <A HREF="#tags">tags</A> file. And when
listing <A HREF="#tags">tags</A> the reverse happens. When the conversion fails the unconverted
<A HREF="#tag">tag</A> is used.
*<A NAME="tag-search"></A><B>tag-search</B>*
The command can be any <A HREF="intro.html#Ex">Ex</A> command, but often <A HREF="motion.html#it">it</A> is a search command.
Examples:
<B><FONT COLOR="PURPLE"> tag1 file1 /^main(argc, argv)/ </FONT></B>
<B><FONT COLOR="PURPLE"> tag2 file2 108 </FONT></B>
The command is always executed with <A HREF="options.html#'magic'">'magic'</A> not set. The only special
characters in a search <A HREF="pattern.html#pattern">pattern</A> are "<A HREF="motion.html#^">^</A>" (begin-of-line) and "<A HREF="motion.html#$">$</A>" (<EOL>).
See |<A HREF="pattern.html#pattern">pattern</A>|. Note that you must put a <A HREF="intro.html#backslash">backslash</A> before each <A HREF="intro.html#backslash">backslash</A> in
the search text. This is for backwards compatibility with <A HREF="intro.html#Vi">Vi</A>.
*<A NAME="E434"></A><B>E434</B>* *<A NAME="E435"></A><B>E435</B>*
If the command is a normal search command (it starts and ends with "<A HREF="pattern.html#/">/</A>" or
"?"), some special handling is done:
- Searching starts on line 1 of the file.
The direction of the search is forward for "<A HREF="pattern.html#/">/</A>", backward for "<A HREF="pattern.html#?">?</A>".
Note that <A HREF="options.html#'wrapscan'">'wrapscan'</A> does not matter, the whole file is always searched. (Vi
does use <A HREF="options.html#'wrapscan'">'wrapscan'</A>, which caused <A HREF="#tags">tags</A> sometimes not be found.) {Vi starts
searching in line 2 of another file. It does not find a <A HREF="#tag">tag</A> in line 1 of
another file when <A HREF="options.html#'wrapscan'">'wrapscan'</A> is not set}
- If the search fails, another try is done ignoring <A HREF="change.html#case">case</A>. If that fails too,
a search is done for:
"^tagname[ \t]*("
(the <A HREF="#tag">tag</A> with '<A HREF="motion.html#^">^</A>' prepended and "[ \t]*(" appended). When using function
names, this will find the function name when <A HREF="motion.html#it">it</A> is in column 0. This will
help when the arguments to the function have changed since the <A HREF="#tags">tags</A> file was
made. If this search also fails another search is done with:
"^[#a-zA-Z_].*\<tagname[ \t]*("
This means: A line starting with '<A HREF="pattern.html##">#</A>' or an identifier and containing the <A HREF="#tag">tag</A>
followed by white space and a '<A HREF="motion.html#(">(</A>'. This will find <A HREF="map.html#macro">macro</A> names and function
names with a type prepended. {the extra searches are not in Vi}
==============================================================================
6. Include file searches *<A NAME="include-search"></A><B>include-search</B>* *<A NAME="definition-search"></A><B>definition-search</B>*
*<A NAME="E387"></A><B>E387</B>* *<A NAME="E388"></A><B>E388</B>* *<A NAME="E389"></A><B>E389</B>*
These commands look for a <A HREF="eval.html#string">string</A> in the current file and in all encountered
included files (recursively). This can be used to find the definition of a
variable, function or <A HREF="map.html#macro">macro</A>. If you only want to search in the current
buffer, use the commands listed at |<A HREF="pattern.html#pattern-searches">pattern-searches</A>|.
These commands are not available when the |<A HREF="various.html#+find_in_path">+find_in_path</A>| feature was disabled
at compile time.
When a line is encountered that includes another file, that file is searched
before continuing in the current buffer. Files included by included files are
also searched. When an include file could not be found <A HREF="motion.html#it">it</A> is silently
ignored. Use the |<A HREF="#:checkpath">:checkpath</A>| command to discover which files could not be
found, possibly your <A HREF="options.html#'path'">'path'</A> option is not set up correctly. Note: the
included file is searched, not a buffer that may be editing that file. Only
for the current file the lines in the buffer are used.
The <A HREF="eval.html#string">string</A> can be any keyword or a defined <A HREF="map.html#macro">macro</A>. For the keyword any match
will be found. For defined macros only lines that match with the <A HREF="options.html#'define'">'define'</A>
option will be found. The default is "^#\s*define", which is for C programs.
For other languages you probably want to change this. See <A HREF="options.html#'define'">'define'</A> for an
example for C++. The <A HREF="eval.html#string">string</A> cannot contain an end-of-line, only matches
within a line are found.
When a match is found for a defined <A HREF="map.html#macro">macro</A>, the displaying of lines continues
with the next line when a line ends in a <A HREF="intro.html#backslash">backslash</A>.
The commands that start with "<A HREF="index.html#[">[</A>" start searching from the start of the current
file. The commands that start with "<A HREF="index.html#]">]</A>" start at the current cursor position.
The <A HREF="options.html#'include'">'include'</A> option is used to define a line that includes another file. The
default is "\^#\s*include", which is for C programs. Note: Vim does not
recognize C <A HREF="syntax.html#syntax">syntax</A>, if the <A HREF="options.html#'include'">'include'</A> option matches a line inside
"#ifdef/#endif" or inside a comment, <A HREF="motion.html#it">it</A> is searched anyway. The <A HREF="options.html#'isfname'">'isfname'</A>
option is used to recognize the file name that comes after the matched
<A HREF="pattern.html#pattern">pattern</A>.
The <A HREF="options.html#'path'">'path'</A> option is used to find the directory for the include files that
<A HREF="diff.html#do">do</A> not have an absolute path.
The <A HREF="options.html#'comments'">'comments'</A> option is used for the commands that display a single line or
jump to a line. It defines patterns that may start a comment. Those lines
are ignored for the search, unless [!] is used. One exception: When the line
matches the <A HREF="pattern.html#pattern">pattern</A> "^# *define" <A HREF="motion.html#it">it</A> is not considered to be a comment.
If you want to <A HREF="eval.html#list">list</A> matches, and then select one to jump to, you could use a
<A HREF="map.html#mapping">mapping</A> to <A HREF="diff.html#do">do</A> that for you. Here is an example:
<B> :map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR></B>
*<A NAME="[i"></A><B>[i</B>*
<A HREF="#[i">[i</A> Display the first line that contains the keyword
under the cursor. The search starts at the beginning
of the file. Lines that look like a comment are
ignored (see <A HREF="options.html#'comments'">'comments'</A> option). If a <A HREF="intro.html#count">count</A> is given,
the count'th matching line is displayed, and comment
lines are not ignored. {not in Vi}
*<A NAME="]i"></A><B>]i</B>*
<A HREF="#]i">]i</A> like "<A HREF="#[i">[i</A>", but start at the current cursor position.
{not in Vi}
*<A NAME=":is"></A><B>:is</B>* *<A NAME=":isearch"></A><B>:isearch</B>*
:[range]is[earch][!] <A HREF="intro.html#[count]">[count]</A> [/]pattern[/]
Like "<A HREF="#[i">[i</A>" and "<A HREF="#]i">]i</A>", but search in <A HREF="cmdline.html#[range]">[range]</A> lines
(default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
*<A NAME="[I"></A><B>[I</B>*
<A HREF="#[I">[I</A> Display all lines that contain the keyword under the
cursor. Filenames and line numbers are displayed
for the found lines. The search starts at the
beginning of the file. {not in Vi}
*<A NAME="]I"></A><B>]I</B>*
<A HREF="#]I">]I</A> like "<A HREF="#[I">[I</A>", but start at the current cursor position.
{not in Vi}
*<A NAME=":il"></A><B>:il</B>* *<A NAME=":ilist"></A><B>:ilist</B>*
:[range]il[ist][!] [/]pattern[/]
Like "<A HREF="#[I">[I</A>" and "<A HREF="#]I">]I</A>", but search in <A HREF="cmdline.html#[range]">[range]</A> lines
(default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
*<A NAME="[_CTRL-I"></A><B>[_CTRL-I</B>*
[ <A HREF="motion.html#CTRL-I">CTRL-I</A> Jump to the first line that contains the keyword
under the cursor. The search starts at the beginning
of the file. Lines that look like a comment are
ignored (see <A HREF="options.html#'comments'">'comments'</A> option). If a <A HREF="intro.html#count">count</A> is given,
the count'th matching line is jumped to, and comment
lines are not ignored. {not in Vi}
*<A NAME="]_CTRL-I"></A><B>]_CTRL-I</B>*
] <A HREF="motion.html#CTRL-I">CTRL-I</A> like "[ CTRL-I", but start at the current cursor
position. {not in Vi}
*<A NAME=":ij"></A><B>:ij</B>* *<A NAME=":ijump"></A><B>:ijump</B>*
:[range]ij[ump][!] <A HREF="intro.html#[count]">[count]</A> [/]pattern[/]
Like "[ CTRL-I" and "<A HREF="index.html#]">]</A> CTRL-I", but search in
<A HREF="cmdline.html#[range]">[range]</A> lines (default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="motion.html#CTRL-I">CTRL-I</A> *<A NAME="CTRL-W_CTRL-I"></A><B>CTRL-W_CTRL-I</B>* *<A NAME="CTRL-W_i"></A><B>CTRL-W_i</B>*
<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="insert.html#i">i</A> Open a new <A HREF="windows.html#window">window</A>, with the cursor on the first line
that contains the keyword under the cursor. The
search starts at the beginning of the file. Lines
that look like a comment line are ignored (see
<A HREF="options.html#'comments'">'comments'</A> option). If a <A HREF="intro.html#count">count</A> is given, the count'th
matching line is jumped to, and comment lines are not
ignored. {not in Vi}
*<A NAME=":isp"></A><B>:isp</B>* *<A NAME=":isplit"></A><B>:isplit</B>*
:[range]isp[lit][!] <A HREF="intro.html#[count]">[count]</A> [/]pattern[/]
Like "<A HREF="index.html#CTRL-W">CTRL-W</A> i" and "<A HREF="index.html#CTRL-W">CTRL-W</A> i", but search in
<A HREF="cmdline.html#[range]">[range]</A> lines (default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
*<A NAME="[d"></A><B>[d</B>*
<A HREF="#[d">[d</A> Display the first <A HREF="map.html#macro">macro</A> definition that contains the
<A HREF="map.html#macro">macro</A> under the cursor. The search starts from the
beginning of the file. If a <A HREF="intro.html#count">count</A> is given, the
count'th matching line is displayed. {not in Vi}
*<A NAME="]d"></A><B>]d</B>*
<A HREF="#]d">]d</A> like "<A HREF="#[d">[d</A>", but start at the current cursor position.
{not in Vi}
*<A NAME=":ds"></A><B>:ds</B>* *<A NAME=":dsearch"></A><B>:dsearch</B>*
:[range]ds[earch][!] <A HREF="intro.html#[count]">[count]</A> [/]string[/]
Like "<A HREF="#[d">[d</A>" and "<A HREF="#]d">]d</A>", but search in <A HREF="cmdline.html#[range]">[range]</A> lines
(default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
*<A NAME="[D"></A><B>[D</B>*
<A HREF="#[D">[D</A> Display all <A HREF="map.html#macro">macro</A> <A HREF="intro.html#definitions">definitions</A> that contain the <A HREF="map.html#macro">macro</A>
under the cursor. Filenames and line numbers are
displayed for the found lines. The search starts
from the beginning of the file. {not in Vi}
*<A NAME="]D"></A><B>]D</B>*
<A HREF="#]D">]D</A> like "<A HREF="#[D">[D</A>", but start at the current cursor position.
{not in Vi}
*<A NAME=":dli"></A><B>:dli</B>* *<A NAME=":dlist"></A><B>:dlist</B>*
:[range]dli[st][!] [/]string[/]
Like `[D` and `]D`, but search in <A HREF="cmdline.html#[range]">[range]</A> lines
(default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
Note that `:dl` works like `:delete` with the "<A HREF="motion.html#l">l</A>"
flag, not `:dlist`.
*<A NAME="[_CTRL-D"></A><B>[_CTRL-D</B>*
[ <A HREF="scroll.html#CTRL-D">CTRL-D</A> Jump to the first <A HREF="map.html#macro">macro</A> definition that contains the
keyword under the cursor. The search starts from
the beginning of the file. If a <A HREF="intro.html#count">count</A> is given, the
count'th matching line is jumped to. {not in Vi}
*<A NAME="]_CTRL-D"></A><B>]_CTRL-D</B>*
] <A HREF="scroll.html#CTRL-D">CTRL-D</A> like "[ CTRL-D", but start at the current cursor
position. {not in Vi}
*<A NAME=":dj"></A><B>:dj</B>* *<A NAME=":djump"></A><B>:djump</B>*
:[range]dj[ump][!] <A HREF="intro.html#[count]">[count]</A> [/]string[/]
Like "[ CTRL-D" and "<A HREF="index.html#]">]</A> CTRL-D", but search in
<A HREF="cmdline.html#[range]">[range]</A> lines (default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="scroll.html#CTRL-D">CTRL-D</A> *<A NAME="CTRL-W_CTRL-D"></A><B>CTRL-W_CTRL-D</B>* *<A NAME="CTRL-W_d"></A><B>CTRL-W_d</B>*
<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="change.html#d">d</A> Open a new <A HREF="windows.html#window">window</A>, with the cursor on the first
<A HREF="map.html#macro">macro</A> definition line that contains the keyword
under the cursor. The search starts from the
beginning of the file. If a <A HREF="intro.html#count">count</A> is given, the
count'th matching line is jumped to. {not in Vi}
*<A NAME=":dsp"></A><B>:dsp</B>* *<A NAME=":dsplit"></A><B>:dsplit</B>*
:[range]dsp[lit][!] <A HREF="intro.html#[count]">[count]</A> [/]string[/]
Like "<A HREF="index.html#CTRL-W">CTRL-W</A> d", but search in <A HREF="cmdline.html#[range]">[range]</A> lines
(default: whole file).
See |<A HREF="#:search-args">:search-args</A>| for [/] and [!]. {not in Vi}
*<A NAME=":che"></A><B>:che</B>* *<A NAME=":checkpath"></A><B>:checkpath</B>*
:che[ckpath] <A HREF="eval.html#List">List</A> all the included files that could not be found.
{not in Vi}
:che[ckpath]! <A HREF="eval.html#List">List</A> all the included files. {not in Vi}
*<A NAME=":search-args"></A><B>:search-args</B>*
Common arguments for the commands above:
[!] When included, find matches in lines that are recognized <A HREF="motion.html#as">as</A> comments.
When excluded, a match is ignored when the line is recognized <A HREF="motion.html#as">as</A> a
comment (according to 'comments'), or the match is in a C comment (after
"<A HREF="version7.html#//">//</A>" or inside /* */). Note that a match may be missed if a line is
recognized <A HREF="motion.html#as">as</A> a comment, but the comment ends halfway the line.
And if the line is a comment, but <A HREF="motion.html#it">it</A> is not recognized (according to
<A HREF="options.html#'comments'">'comments'</A>) a match may be found in <A HREF="motion.html#it">it</A> anyway. Example:
<B> /* comment</B>
<B> foobar */</B>
A match for "foobar" is found, because this line is not recognized <A HREF="motion.html#as">as</A> a
comment (even though <A HREF="syntax.html#syntax">syntax</A> highlighting does recognize <A HREF="motion.html#it">it</A>).
Note: Since a <A HREF="map.html#macro">macro</A> definition mostly doesn't look like a comment, the
[!] makes no difference for "<A HREF="#:dlist">:dlist</A>", "<A HREF="#:dsearch">:dsearch</A>" and "<A HREF="#:djump">:djump</A>".
[/] A <A HREF="pattern.html#pattern">pattern</A> can be surrounded by '<A HREF="pattern.html#/">/</A>'. Without '<A HREF="pattern.html#/">/</A>' only whole words are
matched, using the <A HREF="pattern.html#pattern">pattern</A> "\<pattern\>". Only after the second '<A HREF="pattern.html#/">/</A>' a
next command can be appended with '|'. Example:
<B> :isearch /string/ | echo "the last one"</B>
For a "<A HREF="#:djump">:djump</A>", "<A HREF="#:dsplit">:dsplit</A>", "<A HREF="#:dlist">:dlist</A>" and "<A HREF="#:dsearch">:dsearch</A>" command the <A HREF="pattern.html#pattern">pattern</A>
is used <A HREF="motion.html#as">as</A> a literal <A HREF="eval.html#string">string</A>, not <A HREF="motion.html#as">as</A> a search <A HREF="pattern.html#pattern">pattern</A>.
<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>
</HTML>
|