(Uploaded by JohnBot from a locally edited file) |
|||
| (44 intermediate revisions by 21 users not shown) | |||
| Line 3: | Line 3: | ||
|previous=92 |
|previous=92 |
||
|next=95 |
|next=95 |
||
| − | |created= |
+ | |created=2001 |
|complexity=basic |
|complexity=basic |
||
|author=Yegappan Lakshmanan |
|author=Yegappan Lakshmanan |
||
| − | |version= |
+ | |version=6.0 |
|rating=672/235 |
|rating=672/235 |
||
| + | |category1=Navigation |
||
| + | |category2= |
||
}} |
}} |
||
| + | When editing programs, there is often a need to jump to another location, for example, to see how a function is defined. To help, Vim uses a tags file that lists each word you are likely to want, and their locations (file path and line number). Each wanted word is known as a "tag", for example, each function name or global variable may be a tag. |
||
| − | This Q&A gives an introduction to the various facilities available in Vim for using a tags file to browse through program source files. You can read the Vim online help, which explains in detail the tags support, using the ':help tagsearch.txt' command. You can also use the help keywords mentioned in this document to read more about a particular command or option. To read more about a particular command or option use, :help <helpkeyword> in Vim. |
||
| + | The tags file has to be created by a utility, and has to be updated after significant editing has occurred. An alternative to manual tag generation is to use a plugin like vim-gutentags. This tip provides an overview of creating and using tags files (for the details, see {{help|tagsrch.txt}}). |
||
| − | '''How do I create a tags file?''' |
||
| + | ==Using tags== |
||
| − | You can create a tags file either using the ctags utility or using a custom script or utility. |
||
| + | '''Jumping to a tag''' |
||
| + | *You can use the 'tag' ex command. For example, the command ':tag <tagname>' will jump to the tag named <tagname>. |
||
| + | *You can position the cursor over a tag name and then press Ctrl-]. |
||
| + | *You can visually select a text and then press Ctrl-] to jump to the tag matching the selected text. |
||
| + | *You can click on the tag name using the left mouse button, while pressing the <Ctrl> key. |
||
| + | *You can press the g key and then click on the tag name using the left mouse button. |
||
| + | *You can use the 'stag' ex command, to open the tag in a new window. For example, the command ':stag func1' will open the func1 definition in a new window. |
||
| + | *You can position the cursor over a tag name and then press Ctrl-W ]. This will open the tag location in a new window. |
||
| + | Help: :tag, Ctrl-], v_CTRL_], <C-LeftMouse>, g<LeftMouse>, :stag, Ctrl-W_] |
||
| − | Help keyword(s): tag |
||
| + | '''How do I jump to a particular tag match, if there are multiple matching tags?''' |
||
| − | '''Where can I download the tools to generate the tags file?''' |
||
| + | *You can use the 'tselect' ex command to list all the tag matches. For example, the command ':tselect func1' will list all the locations where func1 is defined. You can then enter the number of a tag match to jump to that location. |
||
| − | |||
| + | *You can position the cursor over the tag name and press g] to get a list of matching tags. |
||
| − | There are several utilities available to generate the tags file. |
||
| + | *You can visually select a text and press g] to get a list of matching tags. |
||
| − | Depending on the programming language, you can use any one of them. |
||
| + | *You can use the 'stselect' ex command. This will open the selected tag from the tag list in a new window. |
||
| − | *Exuberant ctags generates tags for the following programming language files: |
||
| + | *You can position the cursor over the tag name and press Ctrl-W g] to do a :stselect. |
||
| − | :Assembler, AWK, ASP, BETA, Bourne/Korn/Zsh Shell, C, C++, COBOL, Eiffel, Fortran, Java, Lisp, Make, Pascal, Perl, PHP, Python, REXX, Ruby, S-Lang, Scheme, Tcl, and Vim. |
||
| − | :You can download exuberant ctags from |
||
| − | ::http://ctags.sourceforge.net/ |
||
| − | *On Unix, you can use the /usr/bin/ctags utility. This utility is present in most of the Unix installations. |
||
| − | *You can use jtags for generating tags file for java programs. You can download jtags from: http://www.fleiner.com/jtags/ |
||
| − | *You can use ptags for generating tags file for perl programs. You can download ptags from: http://www.eleves.ens.fr:8080/home/nthiery/Tags/ |
||
| − | *You can download scripts from the following links for generating tags file for verilog files: |
||
| − | **http://www.probo.com/vtags.htm |
||
| − | **http://www.cs.albany.edu/~mosh/Perl/veri-tags |
||
| − | *You can download Hdrtag from the following link: http://mysite.verizon.net/astronaut/vim/index.html. This utility generates tags file for the following programming languages: assembly, c/c++, header files, lex, yacc,LaTeX, vim, and Maple V. |
||
| − | *pltags.pl - Create tags file for perl code |
||
| − | *tcltags - Create tags file for TCL code |
||
| − | *shtags.pl - Create tags file for shell script |
||
| − | |||
| − | Help keyword(s): ctags |
||
| − | |||
| − | '''How do I generate a tags file using ctags?''' |
||
| − | |||
| − | You can generate a tags file for all the C files in the current |
||
| − | directory using the following command: |
||
| − | |||
| − | $ ctags *.c |
||
| − | |||
| − | You can generate tags file for all the files in the current |
||
| − | directory and all the sub-directories using (this applies only to |
||
| − | exuberant ctags): |
||
| − | |||
| − | $ ctags -R . |
||
| − | |||
| − | You can generate tags file for all the files listed in a text file |
||
| − | named flist using (this applies only to exuberant ctags) |
||
| − | |||
| − | $ ctags -L flist |
||
| − | |||
| − | '''How do I configure Vim to locate a tags file?''' |
||
| − | |||
| − | You can set the 'tags' option in Vim to specify a particular tags |
||
| − | file. |
||
| − | |||
| − | set tags=/my/dir/tags |
||
| − | |||
| − | Help keyword(s): 'tags', tags-option |
||
| − | |||
| − | '''How do I configure Vim to use multiple tags files?''' |
||
| − | |||
| − | The 'tags' option can specify more than one tags file. The tag |
||
| − | filenames are separated using either comma or spaces. |
||
| − | |||
| − | set tags=/my/dir1/tags, /my/dir2/tags |
||
| − | |||
| − | '''How do I configure Vim to locate a tags file in a directory tree?''' |
||
| − | |||
| − | You can set the 'tags' option to make Vim search for the tags file in a directory tree. For example, if the 'tags' option is set like this: |
||
| − | |||
| − | set tags=tags;/ |
||
| − | |||
| − | Vim will search for the file named 'tags', starting with the current directory and then going to the parent directory and then recursively to the directory one level above, till it either locates the 'tags' file or reaches the root '/' directory. Note that the above will work only in Vim 6.0 and above. |
||
| − | |||
| − | Help keyword(s): file-searching |
||
| − | |||
| − | '''How do I jump to a tag?''' |
||
| − | |||
| − | There are several ways to jump to a tag location. |
||
| − | #You can use the 'tag' ex command. For example, the command ':tag <tagname>' will jump to the tag named <tagname>. |
||
| − | #You can position the cursor over a tag name and then press Ctrl-]. |
||
| − | #You can visually select a text and then press Ctrl-] to jump to the tag matching the selected text. |
||
| − | #You can click on the tag name using the left mouse button, while pressing the <Ctrl> key. |
||
| − | #You can press the g key and then click on the tag name using the left mouse button. |
||
| − | #You can use the 'stag' ex command, to open the tag in a new window. For example, the command ':stag func1' will open the func1 definition in a new window. |
||
| − | #You can position the cursor over a tag name and then press Ctrl-W ]. This will open the tag location in a new window. |
||
| − | |||
| − | Help keyword(s): :tag, Ctrl-], v_CTRL_], <C-LeftMouse>, g<LeftMouse>, :stag, Ctrl-W_] |
||
| + | Help: tag-matchlist, :tselect, g], v_g], :stselect, Ctrl-W_g] |
||
| − | '''How do I come back from a tag jump?''' |
||
| + | '''Returning after a tag jump''' |
||
| − | There are several ways to come back to the old location from a tag jump. |
||
| − | + | *You can use the 'pop' ex command. |
|
| − | + | *You can press Ctrl-t. |
|
| − | + | *You can click the right mouse button, while pressing the <Ctrl> key. |
|
| − | + | *You can press the g key and then click the right mouse button. |
|
| − | Help |
+ | Help: :pop, Ctrl-T, <C-RightMouse>, g<RightMouse> |
'''How do I jump again to a previously jumped tag location?''' |
'''How do I jump again to a previously jumped tag location?''' |
||
| + | *You can use the 'tag' ex command to jump to a previously jumped tag location, which is stored in the tag stack. |
||
| + | Help: tag |
||
| − | You can use the 'tag' ex command to jump to a previously jumped tag location, which is stored in the tag stack. |
||
| − | Help keyword(s): tag |
||
'''How do I list the contents of the tag stack?''' |
'''How do I list the contents of the tag stack?''' |
||
| + | *Vim remembers the location from which you jumped to a tag in the tag stack. You can list the current tag stack using the 'tags' ex command. |
||
| + | Help: :tags, tagstack |
||
| − | Vim remembers the location from which you jumped to a tag in the tag stack. You can list the current tag stack using the 'tags' ex command. |
||
| − | Help keyword(s): :tags, tagstack |
||
| − | |||
| − | '''How do I jump to a particular tag match, if there are multiple matching tags?''' |
||
| − | |||
| − | In some situations, there can be more than one match for a tag. For example, a C function or definition may be present in more than one file in a source tree. There are several ways to jump to a specific tag from a list of matching tags. |
||
| − | #You can use the 'tselect' ex command to list all the tag matches. For example, the command ':tselect func1' will list all the locations where func1 is defined. You can then enter the number of a tag match to jump to that location. |
||
| − | #You can position the cursor over the tag name and press g] to get a list of matching tags. |
||
| − | #You can visually select a text and press g] to get a list of matching tags. |
||
| − | #You can use the 'stselect' ex command. This will open the selected tag from the tag list in a new window. |
||
| − | #You can position the cursor over the tag name and press Ctrl-W g] to do a :stselect. |
||
| − | |||
| − | Help keyword(s): tag-matchlist, :tselect, g], v_g], :stselect, Ctrl-W_g] |
||
'''I want to jump to a tag, if there is only one matching tag, otherwise a list of matching tags should be displayed. How do I do this?''' |
'''I want to jump to a tag, if there is only one matching tag, otherwise a list of matching tags should be displayed. How do I do this?''' |
||
There are several ways to make Vim to jump to a tag directly, if there is only one tag match, otherwise present a list of tag matches. |
There are several ways to make Vim to jump to a tag directly, if there is only one tag match, otherwise present a list of tag matches. |
||
| − | + | *You can use the 'tjump' ex command. For example, the command ':tjump func1' will jump to the definition func1, if it is defined only once. If func1 is defined multiple times, a list of matching tags will be presented. |
|
| − | + | *You can position the cursor over the tag and press g Ctrl-]. |
|
| − | + | *You can visually select a text and press g Ctrl-] to jump or list the matching tags. |
|
| − | + | *You can use the 'stjump' ex command. This will open the matching or selected tag from the tag list in a new window. |
|
| − | + | *You can press Ctrl-W g Ctrl-] to do a :stjump. |
|
| − | Help |
+ | Help: :tjump, g_Ctrl-], v_g_CTRL-], :stjump, Ctrl-W_g_Ctrl-] |
'''How do browse through a list of multiple tag matches?''' |
'''How do browse through a list of multiple tag matches?''' |
||
If there are multiple tag matches, you can browse through all of them using several of the Vim ex commands. |
If there are multiple tag matches, you can browse through all of them using several of the Vim ex commands. |
||
| − | + | *To go to the first tag in the list, use the 'tfirst' or 'trewind' ex command. |
|
| − | + | *To go to the last tag in the list, use the 'tlast' ex command. |
|
| − | + | *To go to the next matching tag in the list, use the 'tnext' ex command. |
|
| − | + | *To go to the previous matching tag in the list, use the 'tprevious' or 'tNext' ex command. |
|
| − | Help |
+ | Help: :tfirst, :trewind, :tlast, :tnext, :tprevious, :tNext |
'''How do I preview a tag?''' |
'''How do I preview a tag?''' |
||
You can use the preview window to preview a tag, without leaving the original window. There are several ways to preview a tag: |
You can use the preview window to preview a tag, without leaving the original window. There are several ways to preview a tag: |
||
| − | + | *You can use the 'ptag' ex command to open a tag in the preview window. |
|
| − | + | *You can position the cursor on a tag name and press Ctrl-W } to open the tag in the preview window. |
|
| − | + | *You can use the 'ptselect' ex command to do the equivalent of the 'tselect' ex command in the preview window. |
|
| − | + | *You can use the 'ptjump' ex command to do the equivalent of the 'tjump' ex command in the preview window. |
|
| − | + | *You can position the cursor on the tag and press Ctrl-W g} to do a :ptjump on the tag. |
|
| − | Help |
+ | Help: :preview-window, :ptag, Ctrl-W_}, :ptselect, :ptjump, Ctrl-W_g} |
'''How do I browse through the tag list in a preview window?''' |
'''How do I browse through the tag list in a preview window?''' |
||
If there are multiple tag matches, you can browse through all of them in the preview window using several of the Vim ex commands. |
If there are multiple tag matches, you can browse through all of them in the preview window using several of the Vim ex commands. |
||
| − | + | *To go to the first tag in the list, use the 'ptfirst' or 'ptrewind' ex command. |
|
| − | + | *To go to the last tag in the list, use the 'ptlast' ex command. |
|
| − | + | *To go to the next matching tag in the list, use the 'ptnext' ex command. |
|
| − | + | *To go to the previous matching tag in the list, use the 'ptprevious' or 'ptNext' ex command. |
|
| − | Help |
+ | Help: :ptfirst, :ptrewind, :ptlast, :ptnext, :ptprevious, :ptNext |
'''How do I start Vim to start editing a file at a given tag match?''' |
'''How do I start Vim to start editing a file at a given tag match?''' |
||
| Line 172: | Line 100: | ||
While starting Vim, you can use the command line option '-t' to supply a tag name. Vim will directly jump to the supplied tag location. |
While starting Vim, you can use the command line option '-t' to supply a tag name. Vim will directly jump to the supplied tag location. |
||
| − | Help |
+ | Help: -t |
'''How do I list all the tags matching a search pattern?''' |
'''How do I list all the tags matching a search pattern?''' |
||
| Line 178: | Line 106: | ||
There are several ways to go through a list of all tags matching a pattern. |
There are several ways to go through a list of all tags matching a pattern. |
||
*You can list all the tags matching a particular regular expression pattern by prepending the tag name with the '/' search character. For example, |
*You can list all the tags matching a particular regular expression pattern by prepending the tag name with the '/' search character. For example, |
||
| + | <pre> |
||
| + | :tag /<pattern> |
||
| + | :stag /<pattern> |
||
| + | :ptag /<pattern> |
||
| + | :tselect /<pattern> |
||
| + | :tjump /<pattern> |
||
| + | :ptselect /<pattern> |
||
| + | :ptjump /<pattern> |
||
| + | </pre> |
||
| + | *If you have the 'wildmenu' option set, then you can press the <Tab> key to display a list of all the matching tags in the status bar. You can use the arrow keys to move between the tags and then use the Enter key to select a tag. |
||
| − | :tag /<pattern> |
||
| + | *If you don't have the 'wildmenu' option set, you can still use the <Tab> key to browse through the list of matching tags. |
||
| − | :stag /<pattern> |
||
| − | :ptag /<pattern> |
||
| − | :tselect /<pattern> |
||
| − | :tjump /<pattern> |
||
| − | :ptselect /<pattern> |
||
| − | :ptjump /<pattern> |
||
| + | Help: tag-regexp, wildmenu |
||
| − | *If you have the 'wildmenu' option set, then you can press the <Tab> key to display a list of all the matching tags in the status bar. You can use the arrow keys to move between the tags and then use the <Enter> key to select a tag. |
||
| − | *If you don't have the 'wildmenu' option set, you can still use the <Tab> key to browse through the list of matching tags. |
||
| − | |||
| − | Help keyword(s): tag-regexp, wildmenu |
||
'''What options are available to control how Vim handles the tags file?''' |
'''What options are available to control how Vim handles the tags file?''' |
||
You can use the following options to control the handling of tags file by Vim: |
You can use the following options to control the handling of tags file by Vim: |
||
| − | + | *'tagrelative' - Controls how the file names in the tags file are treated. When on, the filenames are relative to the directory where the tags file is present. |
|
| − | + | *'taglength' - Controls the number of significant characters used for recognizing a tag. |
|
| − | + | *'tagbsearch' - Controls the method used to search the tags file for a tag. If this option is on, binary search is used to search the tags file. Otherwise, linear search is used. |
|
| − | + | *'tagstack' - Controls how the tag stack is used. |
|
| − | Help |
+ | Help: 'tagrelative', 'taglength', 'tagbsearch', 'tagstack' |
'''Is it possible to highlight all the tags in the current file?''' |
'''Is it possible to highlight all the tags in the current file?''' |
||
Yes. Read the Vim online help on "tag-highlight". |
Yes. Read the Vim online help on "tag-highlight". |
||
| − | |||
| − | '''Is it possible to create a menu with all the tags in the current file?''' |
||
| − | |||
| − | Yes. You can use the taglist plugin to display a list of tags defined in the current file in a menu. You can download this plugin from {{script|id=273}}. |
||
'''Is there a workaround to make the Ctrl-] key not to be treated as the telnet escape character?''' |
'''Is there a workaround to make the Ctrl-] key not to be treated as the telnet escape character?''' |
||
The default escape characters for telnet in Unix systems is Ctrl-]. While using Vim in a telnet session, if you use Ctrl-] to jump to a tag, you will get the telnet prompt. There are two ways to avoid this problem: |
The default escape characters for telnet in Unix systems is Ctrl-]. While using Vim in a telnet session, if you use Ctrl-] to jump to a tag, you will get the telnet prompt. There are two ways to avoid this problem: |
||
| − | + | *Map the telnet escape character to some other character using the "-e <escape character>" telnet command line option |
|
| − | + | *Disable the telnet escape character using the "-E" telnet command line option. |
|
| − | Help |
+ | Help: telnet-CTRL-] |
| + | ==Tools to create a tags file== |
||
| − | ==Comments== |
||
| + | Usually ctags is used to create the required tags file. However, many other custom scripts or tools are used for the occasions when ctags is not suitable. |
||
| − | Heres an excellent tutorial on using cscope with Vim ; right from installing to becoming an expert. |
||
| + | *Universal-ctags https://ctags.io/ - successor of Exuberant Ctags |
||
| − | http://cscope.sourceforge.net/cscope_vim_tutorial.html |
||
| + | *Exuberant Ctags http://ctags.sourceforge.net/, {{help|ctags}}, most popular, stale since 2009. |
||
| + | *Java: [http://www.fleiner.com/jtags/ jtags] |
||
| + | *Perl: [http://www.eleves.ens.fr:8080/home/nthiery/Tags/ ptags] |
||
| + | *Python: utility <code>Tools/scripts/ptags.py</code> under your Python distribution. |
||
| + | *C, C++, LaTeX, maple, vim, yacc, assembly: [http://www.drchip.org/astronaut/src/index.html#HDRTAG Hdrtag] |
||
| + | *Perl or shell script: <code>pltags.pl</code> or <code>shtags.pl</code> provided with Vim (directory $VIMRUNTIME/tools) |
||
| + | *Erlang: [http://www.reddit.com/r/vim/comments/cve43/how_to_generate_tags_file_for_use_in_erlang/ This page] contains a Vim command to generate Erlang tags. |
||
| + | *CoffeeScript: [http://rubygems.org/gems/CoffeeTags This ruby gem] contains a ruby cli tool to generate tags for CoffeeScript. [https://github.com/lukaszkorecki/CoffeeTags Src is on github] |
||
| + | *JavaScript: |
||
| + | ** [https://github.com/mozilla/doctorjs DoctorJS/jsctags] is a ctags-compatible code indexing solution for JavaScript. Its interface and output are essentially identical to Exuberant Ctags. |
||
| + | ** Also here are ctags configurations for Javascript: [https://github.com/winstonwolff/ctags-javascript-coffeescript ctags configurations for Javascript] |
||
| + | * Haskell: see the Haskell [http://www.haskell.org/haskellwiki/Tags wiki] |
||
| + | * Go: [https://github.com/jstemmer/gotags Gotags] |
||
| + | * Ruby: [https://github.com/tmm1/ripper-tags Ripper-tags] |
||
| + | ==Extending Ctags== |
||
| − | ---- |
||
| − | Um, for some reason - I couldn't get recursive lookup of tags to work with just the |
||
| + | Universal-ctags https://ctags.io/ is extended successor of http://ctags.sourceforge.net/. |
||
| − | set tags=tags;/ |
||
| + | Following is an example of defining a language for Exuberant Ctags. IDL (Interactive Data Language) procedures and functions are supported by putting the following in your <code>.ctags</code> file: |
||
| − | line - changing it to |
||
| + | <pre> |
||
| + | --langdef=IDL |
||
| + | --langmap=IDL:.pro |
||
| + | --regex-IDL=/^pro[ \t]+([a-zA-Z0-9_:]+)/\1/p,procedure/i |
||
| + | --regex-IDL=/^function[ \t]+([a-zA-Z0-9_:]+)/\1/f,function/i |
||
| + | </pre> |
||
| + | Other examples, including for LaTeX, are in the [http://vim-taglist.sourceforge.net/extend.html documentation] for the {{script|id=273|text=taglist}} plugin. |
||
| − | set tags=./tags;/ |
||
| + | ==ctags usage basic examples== |
||
| − | works just fine - the only time I've EVER come across the need to use the ./ thing... |
||
| + | ctags *.c # Generate a tags file for all C files in the current directory |
||
| − | ---- |
||
| − | TagMenu has been moved to http://members.rogers.com/jayglanville/tagsmenu/ |
||
| + | ctags --recurse . # processing subdirectories recursively |
||
| − | ---- |
||
| + | |||
| − | In brazilian keyboards, CTRL-] is CTRL-� (CTRL + c-cedilla) |
||
| + | ctags -L list-of-files # Generate a tags file for all files listed in a file |
||
| − | I don't know why, since '�' is located just to the right of 'L' (it's ';' in US keyboards), but it works. |
||
| + | |||
| + | ==Configuring Vim== |
||
| + | Vim needs to be told where to look for your tags files, using the '<code>tags</code>' option. {{help|'tags'}} {{help|tags-option}} |
||
| + | :set tags=/my/dir/tags |
||
| + | |||
| + | The '<code>tags</code>' option can specify more than one tags file: |
||
| + | :set tags=/my/dir1/tags,/my/dir2/tags |
||
| + | |||
| + | In a large project, it is common to have a tags file in each directory (with each tags file handling the files in its directory). To assist, there is a special case: If a file specified in '<code>tags</code>' starts with "./", the '.' is replaced with the path of the current file. |
||
| + | |||
| + | With this setting, the tags file is in the directory of the current file (no matter what the current directory is). You can define which tag file is searched first: In the current directory ("<code>tags,./tags</code>"), or in the directory of the current file ("<code>./tags,tags</code>"). You might also consider [[VimTip64|setting your working directory to the current file]]. |
||
| + | |||
| + | With the following setting, Vim will search for the file named 'tags', starting with the directory of the current file and then going to the parent directory and then recursively to the directory one level above, till it either locates the 'tags' file or reaches the root directory. {{help|tags-option}} {{help|file-searching}} |
||
| + | :set tags=./tags; |
||
| + | |||
| + | ==Plugins== |
||
| + | *{{script|id=273|text=taglist}} source code browser plugin; uses ctags to display a list of tags for the current file in a menu |
||
| + | *{{script|id=3465|text=Tagbar}} similar to taglist but displays tags sorted by their scope like classes etc. |
||
| + | *{{script|id=2068|text=yate}} makes search in tags more convenient. It holds query and search result in one buffer for faster jump to desired tag. |
||
| + | *[http://peterodding.com/code/vim/easytags/ easytags.vim] ({{script|id=3114}}) automatically creates a global tags file and keeps it up-to-date as you edit files in Vim. The tags are also used to perform dynamic syntax highlighting of user-defined functions and types. |
||
| + | *[https://github.com/ludovicchabant/vim-gutentags vim-gutentags] pure-vim plugin that manages your tag file out of the box |
||
| + | ==See also== |
||
| − | ---- |
||
| + | *[[VimTip79|79 Use grep to get a clickable list of function names]] |
||
| − | When -R option is not availble (on Solaris), use find to generate the list of files and give them as input to ctags using -L option. |
||
| + | *[[VimTip404|404 Tags for Mixed Assembly and C]] |
||
| + | *[[VimTip558|558 Using TagList for ANT build files]] |
||
| + | *[[VimTip568|568 Use temporary tags file when browsing new source]] |
||
| + | *[[VimTip711|711 Tags generation for current file]] |
||
| + | *[[VimTip804|804 Single tags file for a source tree]] |
||
| + | *[[VimTip840|840 Show tags in a separate preview window]] |
||
| + | *[[VimTip858|858 Setting tags when working with multiple source branches]] |
||
| + | *[[VimTip1299|1299 Autocmd to update ctags file]] |
||
| + | *[[VimTip1608|1608 C++ code completion]] |
||
| + | *[http://stackoverflow.com/questions/680291/global-go-to-definition-in-vim-for-ruby including tags from external libraries or Ruby "gems"] |
||
| + | ==Comments== |
||
| + | {{todo}} |
||
| + | * too wordy, let's make it more concise |
||
| + | * add :help links |
||
---- |
---- |
||
| + | There is an [http://cscope.sourceforge.net/cscope_vim_tutorial.html excellent tutorial] on using cscope with Vim, from installing to becoming an expert. |
||
| − | To navigate with Alt+Left and Alt+Right with tags in Vim help or in source code I added the following mappings to my .vimrc: |
||
| − | map <M-Left> <C-T> |
||
| − | map <M-Right> <C-]> |
||
---- |
---- |
||
| + | TagMenu has been moved to http://members.rogers.com/jayglanville/tagsmenu/ |
||
| − | As for C++, try to use ctags with "--extra=+q" to qualify member function/variable with it's class type. |
||
---- |
---- |
||
| + | For C++, use ctags with "--extra=+q" to qualify member function/variable with its class type. |
||
| − | Vim is nice to use with cscope and ctags, |
||
| − | for this purpose |
||
| + | ---- |
||
| − | 1. add to file .vimrc follow strings |
||
| + | Vim is nice to use with cscope and ctags. For this purpose, put this in your vimrc (follow strings): |
||
| − | :map [I :cs find c <C-r><C-w><CR> |
||
| + | <pre> |
||
| − | :set csto=1 |
||
| + | map [I :cs find c <C-r><C-w><CR> |
||
| + | set csto=1 |
||
| + | </pre> |
||
| + | Before editing: |
||
| − | 2. before launch vim, generate: |
||
| + | <pre> |
||
| − | ctags -R |
||
| − | + | ctags -R |
|
| + | cscope -R -b |
||
| + | </pre> |
||
---- |
---- |
||
Revision as of 11:06, 15 June 2020
Tip 94 Printable Monobook Previous Next
created 2001 · complexity basic · author Yegappan Lakshmanan · version 6.0
When editing programs, there is often a need to jump to another location, for example, to see how a function is defined. To help, Vim uses a tags file that lists each word you are likely to want, and their locations (file path and line number). Each wanted word is known as a "tag", for example, each function name or global variable may be a tag.
The tags file has to be created by a utility, and has to be updated after significant editing has occurred. An alternative to manual tag generation is to use a plugin like vim-gutentags. This tip provides an overview of creating and using tags files (for the details, see :help tagsrch.txt).
Using tags
Jumping to a tag
- You can use the 'tag' ex command. For example, the command ':tag <tagname>' will jump to the tag named <tagname>.
- You can position the cursor over a tag name and then press Ctrl-].
- You can visually select a text and then press Ctrl-] to jump to the tag matching the selected text.
- You can click on the tag name using the left mouse button, while pressing the <Ctrl> key.
- You can press the g key and then click on the tag name using the left mouse button.
- You can use the 'stag' ex command, to open the tag in a new window. For example, the command ':stag func1' will open the func1 definition in a new window.
- You can position the cursor over a tag name and then press Ctrl-W ]. This will open the tag location in a new window.
Help: :tag, Ctrl-], v_CTRL_], <C-LeftMouse>, g<LeftMouse>, :stag, Ctrl-W_]
How do I jump to a particular tag match, if there are multiple matching tags?
- You can use the 'tselect' ex command to list all the tag matches. For example, the command ':tselect func1' will list all the locations where func1 is defined. You can then enter the number of a tag match to jump to that location.
- You can position the cursor over the tag name and press g] to get a list of matching tags.
- You can visually select a text and press g] to get a list of matching tags.
- You can use the 'stselect' ex command. This will open the selected tag from the tag list in a new window.
- You can position the cursor over the tag name and press Ctrl-W g] to do a :stselect.
Help: tag-matchlist, :tselect, g], v_g], :stselect, Ctrl-W_g]
Returning after a tag jump
- You can use the 'pop' ex command.
- You can press Ctrl-t.
- You can click the right mouse button, while pressing the <Ctrl> key.
- You can press the g key and then click the right mouse button.
Help: :pop, Ctrl-T, <C-RightMouse>, g<RightMouse>
How do I jump again to a previously jumped tag location?
- You can use the 'tag' ex command to jump to a previously jumped tag location, which is stored in the tag stack.
Help: tag
How do I list the contents of the tag stack?
- Vim remembers the location from which you jumped to a tag in the tag stack. You can list the current tag stack using the 'tags' ex command.
Help: :tags, tagstack
I want to jump to a tag, if there is only one matching tag, otherwise a list of matching tags should be displayed. How do I do this?
There are several ways to make Vim to jump to a tag directly, if there is only one tag match, otherwise present a list of tag matches.
- You can use the 'tjump' ex command. For example, the command ':tjump func1' will jump to the definition func1, if it is defined only once. If func1 is defined multiple times, a list of matching tags will be presented.
- You can position the cursor over the tag and press g Ctrl-].
- You can visually select a text and press g Ctrl-] to jump or list the matching tags.
- You can use the 'stjump' ex command. This will open the matching or selected tag from the tag list in a new window.
- You can press Ctrl-W g Ctrl-] to do a :stjump.
Help: :tjump, g_Ctrl-], v_g_CTRL-], :stjump, Ctrl-W_g_Ctrl-]
How do browse through a list of multiple tag matches?
If there are multiple tag matches, you can browse through all of them using several of the Vim ex commands.
- To go to the first tag in the list, use the 'tfirst' or 'trewind' ex command.
- To go to the last tag in the list, use the 'tlast' ex command.
- To go to the next matching tag in the list, use the 'tnext' ex command.
- To go to the previous matching tag in the list, use the 'tprevious' or 'tNext' ex command.
Help: :tfirst, :trewind, :tlast, :tnext, :tprevious, :tNext
How do I preview a tag?
You can use the preview window to preview a tag, without leaving the original window. There are several ways to preview a tag:
- You can use the 'ptag' ex command to open a tag in the preview window.
- You can position the cursor on a tag name and press Ctrl-W } to open the tag in the preview window.
- You can use the 'ptselect' ex command to do the equivalent of the 'tselect' ex command in the preview window.
- You can use the 'ptjump' ex command to do the equivalent of the 'tjump' ex command in the preview window.
- You can position the cursor on the tag and press Ctrl-W g} to do a :ptjump on the tag.
Help: :preview-window, :ptag, Ctrl-W_}, :ptselect, :ptjump, Ctrl-W_g}
How do I browse through the tag list in a preview window?
If there are multiple tag matches, you can browse through all of them in the preview window using several of the Vim ex commands.
- To go to the first tag in the list, use the 'ptfirst' or 'ptrewind' ex command.
- To go to the last tag in the list, use the 'ptlast' ex command.
- To go to the next matching tag in the list, use the 'ptnext' ex command.
- To go to the previous matching tag in the list, use the 'ptprevious' or 'ptNext' ex command.
Help: :ptfirst, :ptrewind, :ptlast, :ptnext, :ptprevious, :ptNext
How do I start Vim to start editing a file at a given tag match?
While starting Vim, you can use the command line option '-t' to supply a tag name. Vim will directly jump to the supplied tag location.
Help: -t
How do I list all the tags matching a search pattern?
There are several ways to go through a list of all tags matching a pattern.
- You can list all the tags matching a particular regular expression pattern by prepending the tag name with the '/' search character. For example,
:tag /<pattern> :stag /<pattern> :ptag /<pattern> :tselect /<pattern> :tjump /<pattern> :ptselect /<pattern> :ptjump /<pattern>
- If you have the 'wildmenu' option set, then you can press the <Tab> key to display a list of all the matching tags in the status bar. You can use the arrow keys to move between the tags and then use the Enter key to select a tag.
- If you don't have the 'wildmenu' option set, you can still use the <Tab> key to browse through the list of matching tags.
Help: tag-regexp, wildmenu
What options are available to control how Vim handles the tags file?
You can use the following options to control the handling of tags file by Vim:
- 'tagrelative' - Controls how the file names in the tags file are treated. When on, the filenames are relative to the directory where the tags file is present.
- 'taglength' - Controls the number of significant characters used for recognizing a tag.
- 'tagbsearch' - Controls the method used to search the tags file for a tag. If this option is on, binary search is used to search the tags file. Otherwise, linear search is used.
- 'tagstack' - Controls how the tag stack is used.
Help: 'tagrelative', 'taglength', 'tagbsearch', 'tagstack'
Is it possible to highlight all the tags in the current file?
Yes. Read the Vim online help on "tag-highlight".
Is there a workaround to make the Ctrl-] key not to be treated as the telnet escape character?
The default escape characters for telnet in Unix systems is Ctrl-]. While using Vim in a telnet session, if you use Ctrl-] to jump to a tag, you will get the telnet prompt. There are two ways to avoid this problem:
- Map the telnet escape character to some other character using the "-e <escape character>" telnet command line option
- Disable the telnet escape character using the "-E" telnet command line option.
Help: telnet-CTRL-]
Tools to create a tags file
Usually ctags is used to create the required tags file. However, many other custom scripts or tools are used for the occasions when ctags is not suitable.
- Universal-ctags https://ctags.io/ - successor of Exuberant Ctags
- Exuberant Ctags http://ctags.sourceforge.net/, :help ctags, most popular, stale since 2009.
- Java: jtags
- Perl: ptags
- Python: utility
Tools/scripts/ptags.pyunder your Python distribution. - C, C++, LaTeX, maple, vim, yacc, assembly: Hdrtag
- Perl or shell script:
pltags.plorshtags.plprovided with Vim (directory $VIMRUNTIME/tools) - Erlang: This page contains a Vim command to generate Erlang tags.
- CoffeeScript: This ruby gem contains a ruby cli tool to generate tags for CoffeeScript. Src is on github
- JavaScript:
- DoctorJS/jsctags is a ctags-compatible code indexing solution for JavaScript. Its interface and output are essentially identical to Exuberant Ctags.
- Also here are ctags configurations for Javascript: ctags configurations for Javascript
- Haskell: see the Haskell wiki
- Go: Gotags
- Ruby: Ripper-tags
Extending Ctags
Universal-ctags https://ctags.io/ is extended successor of http://ctags.sourceforge.net/.
Following is an example of defining a language for Exuberant Ctags. IDL (Interactive Data Language) procedures and functions are supported by putting the following in your .ctags file:
--langdef=IDL --langmap=IDL:.pro --regex-IDL=/^pro[ \t]+([a-zA-Z0-9_:]+)/\1/p,procedure/i --regex-IDL=/^function[ \t]+([a-zA-Z0-9_:]+)/\1/f,function/i
Other examples, including for LaTeX, are in the documentation for the taglist plugin.
ctags usage basic examples
ctags *.c # Generate a tags file for all C files in the current directory
ctags --recurse . # processing subdirectories recursively
ctags -L list-of-files # Generate a tags file for all files listed in a file
Configuring Vim
Vim needs to be told where to look for your tags files, using the 'tags' option. :help 'tags' :help tags-option
:set tags=/my/dir/tags
The 'tags' option can specify more than one tags file:
:set tags=/my/dir1/tags,/my/dir2/tags
In a large project, it is common to have a tags file in each directory (with each tags file handling the files in its directory). To assist, there is a special case: If a file specified in 'tags' starts with "./", the '.' is replaced with the path of the current file.
With this setting, the tags file is in the directory of the current file (no matter what the current directory is). You can define which tag file is searched first: In the current directory ("tags,./tags"), or in the directory of the current file ("./tags,tags"). You might also consider setting your working directory to the current file.
With the following setting, Vim will search for the file named 'tags', starting with the directory of the current file and then going to the parent directory and then recursively to the directory one level above, till it either locates the 'tags' file or reaches the root directory. :help tags-option :help file-searching
:set tags=./tags;
Plugins
- taglist source code browser plugin; uses ctags to display a list of tags for the current file in a menu
- Tagbar similar to taglist but displays tags sorted by their scope like classes etc.
- yate makes search in tags more convenient. It holds query and search result in one buffer for faster jump to desired tag.
- easytags.vim (script#3114) automatically creates a global tags file and keeps it up-to-date as you edit files in Vim. The tags are also used to perform dynamic syntax highlighting of user-defined functions and types.
- vim-gutentags pure-vim plugin that manages your tag file out of the box
See also
- 79 Use grep to get a clickable list of function names
- 404 Tags for Mixed Assembly and C
- 558 Using TagList for ANT build files
- 568 Use temporary tags file when browsing new source
- 711 Tags generation for current file
- 804 Single tags file for a source tree
- 840 Show tags in a separate preview window
- 858 Setting tags when working with multiple source branches
- 1299 Autocmd to update ctags file
- 1608 C++ code completion
- including tags from external libraries or Ruby "gems"
Comments
TO DO
- too wordy, let's make it more concise
- add :help links
There is an excellent tutorial on using cscope with Vim, from installing to becoming an expert.
TagMenu has been moved to http://members.rogers.com/jayglanville/tagsmenu/
For C++, use ctags with "--extra=+q" to qualify member function/variable with its class type.
Vim is nice to use with cscope and ctags. For this purpose, put this in your vimrc (follow strings):
map [I :cs find c <C-r><C-w><CR> set csto=1
Before editing:
ctags -R cscope -R -b