Vim自动生成tags插件vim-gutentag使用方法

在常规的使用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)，部分内容参考了

@韦易笑

的回答，感谢。