在常规的使用ctags生成tag标签文件实现跳转的方式下,每次需要更新tags文件时都需要手工运行 ctags -R
生成当前项目所有源文件对应的tag标签文件。
当工程文件多、文件更新频繁时,上述生成tags文件的方法显得笨拙、低效。
得益于 Vim 8 提供的异步机制,vim插件vim-gutentags能够自动异步生成 tags 文件,当检测到同一个工程下面的文件有修改时,gutentags能自动增量更新对应工程的 tags 文件,而不用全部重新生成tags文件,是一个非常高效的tags生成工具。
1.1 软件依赖
vim-gutentags的本质仍然是使用ctags生成tag标签来实现函数跳转等功能,只是在ctags的基础上进行了封装和简化(具体封装方式在后文有简单分析),方便用户在vim中使用。
由于vim-gutentags依赖ctags工具,因此在使用vim-gutentags插件的系统中必须安装ctags软件,否则会报错"Excutable 'ctags' can't be found."。
关于ctags的介绍和安装方法,可以参考vim教程网上的文章Vim使用ctags实现函数跳转。
其次,vim-gutentags需要在vim8.0 以上版本才能正常工作,因为vim-gutentags实现的是增量更新tags的方式,依赖于vim8提供的异步机制。
在低于vim8.0的版本是运行vim-gutentags插件,会报错"this plugin requires the job API from Vim8 or Neovim"。
关于vim8的编译和安装,可以参考vim教程网上的文章vim安装教程。
1.2 gutentags安装方法
本文介绍使用插件管理器vim-plug安装vim-gutentags插件。
在配置文件 ~/.vimrc
中增加配置项 Plug 'ludovicchabant/vim-gutentags'
后再在vim命令行模式下执行命令 :PlugInstall
即可完成vim-gutentags插件的安装。
二、vim-gutentags配置介绍和原理分析
vim-gutentags插件的基本工作原理可以这么理解:首先确定vim当前打开的文件是否需要自动生成 tags标签,若需要则通过某种方式确定tag文件的路径,再基于tag标签文件完成函数跳转、结构体定义跳转等功能。
因此,vim-gutentags需要确定是否需要生成tags标签文件,又需要告诉ctags软件自身生成的tags文件的具体路径信息 (因为从Vim使用ctags实现函数跳转一文已知,默认情况下,生成的tags文件必须在vim运行的当前目录才能在vim里面正确跳转)。
2.1 gutentags配置
为了提供上述信息给vim-gutentags,安装完gutentags后,需要在vim配置文件中增加以下必要的配置项。
" gutentags搜索工程目录的标志,碰到这些文件/目录名就停止向上一级目录递归 "
let g:gutentags_project_root = ['.root', '.svn', '.git', '.project']
" 所生成的数据文件的名称 "
let g:gutentags_ctags_tagfile = '.tags'
" 将自动生成的 tags 文件全部放入 ~/.cache/tags 目录中,避免污染工程目录 "
let s:vim_tags = expand('~/.cache/tags')
let g:gutentags_cache_dir = s:vim_tags
" 检测 ~/.cache/tags 不存在就新建 "
if !isdirectory(s:vim_tags)
silent! call mkdir(s:vim_tags, 'p')
endif
" 配置 ctags 的参数 "
let g:gutentags_ctags_extra_args = ['--fields=+niazS', '--extra=+q']
let g:gutentags_ctags_extra_args += ['--c++-kinds=+pxI']
let g:gutentags_ctags_extra_args += ['--c-kinds=+px']
- 变量
gutentags_project_root
是vim-gutentags提供的用于搜索工程目录的标志,gutentags插件启动后,会从文件当前路径递归往上查找gutentags_project_root
中指定的文件或目录名,直到第一次找到对应目标文件或目录名停止。若没有找到gutentags_project_root
变量指定的文件或目录名,则gutentags不会生成tag文件。 - 变量
gutentags_ctags_tagfile
和gutentags_cache_dir
分别用于告诉ctags要使用的tag文件目录 和tag文件名后缀 ,tag文件名的生成规则默认是根据生成tag文件的工程绝对路径按 - 分割而成。 - 变量
gutentags_ctags_extra_args
用于配置ctags生成tag标签的参数,具体参数含义可参考文章ctags参数介绍
所以,上面的gutentags配置指定了从当前路径向上递归查找是否有 .root
、.svn
、 .git
、.project
等标志性文件来确定当前文档所属的工程目录;而ctags要使用的tag标签文件的路径为 ~/.cache/tags
,文件后缀为 .tags
。
ctags 软件需要使用命令 :set tags+=tags文件路径
显式地指定tag文件路径,从文件 ~/plugged/vim-gutentags/autoload/gutentags/ctags.vim
可以看出,gutentags执行了命令 setlocal tags+=
来添加变量 gutentags_ctags_tagfile
指定的tag文件到局部 tags 搜索列表中。
2.2 gutentags示例
安装了gutentags并且进行了上面的设置后,平时打开vim编辑文件基本感觉不到 tags 文件的生成过程了,只要文件修改过,gutentags 都在后台默默分析是否需要更新数据文件,还会帮你:setlocal tags+=... 添加到局部 tags 搜索列表中。得益于 Vim 8 的异步机制,你可以任意随时使用 ctags 相关功能,并且数据库都是最新的。
就像下面的vim视频教程一样,假设已经在vim配置文件中添加了上面的配置项,在当前目录新建文件 .project
后再打开当前目录下的任意文件,再退出vim后可以看到,gutentags已经为当前目录生成了tags文件 ~/.cache/tags/home-vim-vim.ink-libevent-.tags
。
需要注意的是,gutentags 需要靠上面定义的 gutentags_project_root
判断文件所在的工程,如果一个文件没有保存在包含 .git
、.svn
、.root
等 定义在 gutentags_project_root
中的文件,gutentags就不会为该野文件生成 tags。
想要避免的话,你可以在你的野文件目录中放一个名字为 .root
的空白文件,主动告诉 gutentags 这里就是工程目录。
2.3 基于gutentags实现跳转
在为当前目录生成tags文件后,可以通过按键 Ctrl + ]
跳转到对应的定义位置,再使用命令 Ctrl + o
回退到原来的位置。关于跳转的具体应用,可以参考Vim使用ctags实现函数跳转
另外,建议多使用 Ctrl - W + ]
用新窗口打开并查看光标下符号的定义,或者 Ctrl -W }
使用 preview 窗口预览光标下符号的定义。
PS:本文首发于我的个人博客:Vim自动生成tags插件vim-gutentags安装和自动跳转方法-Vim插件(10),部分内容参考了
的回答,感谢。