GNU Global setup for Drupal

Last updated on
2 March 2017

GNU Global is a modern, stand-alone, editor independent source code tag system. For Drupal its practical value is for looking up functions and arguments in Vim or Emacs.

Setting up GNU Global for use in a Drupal environment requires some care, and this document describes its quirks and how to work around them.

Short version:

  • Use global 6.3 or later
  • Copy gtags.conf to ~/.globalrc
  • Tag your code tree with
    gtags --gtagslabel drupal

Bug in versions prior to 6.3

There is a bug in GNU Global 6.2 and before causing gtags to segfault while parsing Drupal 7 core—or more specific—while parsing modules/system/system.api.php, due to a too large docblock for function hook_menu().

Workarounds if you don't have access to install a recent version:

  • Setup your ~/.globalrc to skip modules/system/system.api.php. See section Configure GNU Global.
  • Use Drush utilities for Emacs users and index the source with drush gtags. It does the same as above.
  • Reduce or remove the docblock (i.e. kill'em kittens) for function hook_menu() in modules/system/system.api.php in the Drupal source tree.

Install GNU Global

Debian / Ubuntu

As of Debian 9 (stretch) and Ubuntu 17.04 (zesty), an up to date version of global is included. No need to do anything here. Install using apt and move on.

In earlier versions of these distros global was old and caused many utilities to simply fail. On these version it's reccomended to install from source instead. Though you need to install its dependencies:

sudo apt-get install libncurses5-dev

If this isn't an option and you have to use the distribution's global package, make sure you find a proper workaround for its bug.


Homebrew gives you version 6.3 or newer out of the box.

brew install global

Whereas Fink has an old1 version. Don't use it and install from source instead.

From source

GNU Global has very few dependencies making the process of compiling it from source rather painless. All you need is the development files for the ncurses library.

Download the latest version, extract it, configure, compile and install:

tar xf /path/to/downloaded/global-6.5.6.tar.gz
cd global-6.5.6
sudo make install

Configure GNU Global for Drupal environments

Out of the box gtags will only tag .php, .php3 and .phtml as PHP files, ignoring extensions common in Drupal. As of version 6.2.8 the included gtags.conf comes with a parser for Drupal. But you have to copy this file to /etc/gtags.conf (system wide) or ~/.globalrc (per user) as it doesn't have the drupal parser in itself:

$ cp global-6.3.1/gtags.conf ~/.globalrc

It should include a section that look like this:

# Drupal configuration.
drupal|Drupal content management platform:\

If not, add it to the existing ~/.globalrc.

You can now tag your source tree with the following command:

gtags --gtagslabel drupal

This will create a few Berkeley DB files: GPATH, GRTAGS, GSYMS, and GTAGS. It is a good idea to add these files to your project's .gitignore.

Bug workaround

For versions prior to 6.3, you can use the same parser as above with an additional skip element for modules/system/system.api.php. Copy the sample gtags.conf provided with your version of GNU Global to ~/.globalrc and add the tuned parser:

# Drupal configuration.
drupal|Drupal content management platform:\