Installation

Where to get Vim

The vim home page is http://www.vim.org/, and the main download page is http://www.vim.org/download.php. Most Mac users prefer this version: http://code.google.com/p/macvim/.

To use the vimrc project, you need at least vim 7.0 with "normal" features enabled at compilation time. As of early 2012, the current version is 7.3. See Prerequisites if you are not sure what version of vim you already have.

The sections below describe

• Installation with drush (recommended)
• Installation as a Vim 8 package
• Installation with pathogen
• Installation with vundle
• Installation with Plug
• Installation as a git submodule
• Basic installation (without pathogen)

and additional steps needed for some features:

• Vimrc files
• Autocompletion in .info files
• Tagbar (Exuberant ctags)
• Drush integration
• Highlighting and correcting errors
• Gotchas

Installation with drush

$ drush @none dl vimrc
$ drush help vimrc-install
$ drush -v vimrc-install <options>

Installation can be very quick, and there is little feedback if you leave off the -v option. If the drush version is at least 5.5, then the recommended plugins will be installed in the bundle/ subdirectory of your vimfiles directory.

Note:

Make sure the unzip executable is available, otherwise, you will get errors like the following when executing drush -v vimrc-install <options>:
Unable to unzip /tmp/drush_tmp_1402705669_539b9705ce524/master.zip.

Installation as a Vim 8 package

If you use Vim 8, then you can install most of this project using the new package feature.

Download this project to your packages directory, usually ~/.vim/pack/, and rename the bundle subdirectory to start. Then you should have, for example, ~/.vim/pack/vimrc/start/vim-plugin-for-drupal/plugin/drupal.vim.

Before the line filetype plugin on in your vimrc file, add the lines

if v:version >= 800
  packloadall
endif

You can omit the version check if you only use Vim 8.

The only thing you lose with this method are the drush commands. If you want to use them, then you can copy or symlink vimrc.drush.inc to a directory that drush searches for commands, such as ~/.drush.

Installation with pathogen

First, install pathogen (or get it from GitHub). As you add and update vim plugins, this will make your life easier! Make sure to follow the installation instructions for pathogen, including adding a line near the start of your vimrc file. Here are the instructions from the Github page for pathogen:

Install to ~/.vim/autoload/pathogen.vim. Or copy and paste:

mkdir -p ~/.vim/autoload ~/.vim/bundle; \
curl -Sso ~/.vim/autoload/pathogen.vim \
    https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim

If you're using Windows, change all occurrences of ~/.vim to ~\vimfiles.
...
Add this to your vimrc:

call pathogen#infect()

(The https://.../pathogen.vim should all be on one line. See also the section on vimrc files below.)

Where to put it

With pathogen, you can install this project wherever you like. One suggestion is to save the project as ~/.drush/vimrc. Explicitly, the project's README.txt file will be

        ~/.drush/vimrc/README.txt (Linux, Mac, etc.)
        ~\.drush\vimrc\README.txt (Windows)

Then add the line
:call pathogen#infect('~/.drush/vimrc/bundle')
to your vimrc file. (The Windows variant is left as an exercise.) Another suggestion is to make a symbolic link to the bundle/ directory under your vimfiles directory. Explicitly,

$ mkdir ~/.vim/bundle
$ ln -s path/to/vimrc/bundle/vim-plugin-for-drupal ~/.vim/bundle

In this case, add the line :call pathogen#infect()
to your vimrc file if it is not already there.

Don't forget the docs!

If you install with pathogen, then start vim and use
:Helptags
to let pathogen install our help files. To make sure it worked, try
:help drupal

Install using Vundle

If you use Vundle, then simply add the following line to your .vimrc:

Plugin 'https://git.drupalcode.org/project/vimrc.git', {'rtp': 'bundle/vim-plugin-for-drupal/'}

And then update your bundles by launching vim, and running :BundleInstall.

For support for things like Twig syntax highlighting and syntax checking, you'll want to add more plugins to Vundle. Look at what Drush installs for details about what plugins should be added.

Install using Plug

If you use Plug, then simply add the following line to your .vimrc:

Plug 'https://git.drupalcode.org/project/vimrc.git', { 'branch': '8.x-1.x', 'rtp': 'bundle/vim-plugin-for-drupal' }

And then update your bundles by launching vim, and running :PlugInstall.

Installation as a git submodule

If you like to keep your vimfiles folder (~/.vim or ~\vimfiles on Windows) under version control, then do this from inside your vimfiles folder:

$ git init
$ git submodule add https://git.drupalcode.org/project/vimrc.git bundle/drupalvim
$ git submodule init
$ git submodule update

Then add the following to your vimrc file:

" Make sure the infect call happens in the following order.
call pathogen#infect('~/.vim/bundle/drupalvim/bundle')
call pathogen#infect('~/vimfiles/bundle/drupalvim/bundle')
call pathogen#infect()

Run :Helptags as above.

If you want to use the drush commands defined by this project, add the line

$options['include'] = array('~/.vim/bundle/drupalvim');
$options['include'] = array('~/vimfiles/bundle/drupalvim');

to your drushrc.php file.

Basic installation

If you choose not to use pathogen, then you will have to worry about filename conflicts when you install this project and every time you upgrade it.

Where to put it

Copy the files from the bundle/vim-plugin-for-drupal/ subdirectory into your vimfiles directory. If you have downloaded these files as vimrc.tar.gz and your vimfiles directory is ~/.vim, then this should work on UNIX-like systems:

$ cd ~/.vim
$ tar xzf path/to/vimrc.tar.gz --strip-components 3 vimrc/bundle/vim-plugin-for-drupal

Note: if there are filename conflicts, then tar will silently overwrite the existing files.

When you are done, you should have the following directory structure inside your vimfiles directory:

        autoload/drupal.vim
        compiler/coder.vim
        doc/drupal.txt
        ftdetect/drupal.vim
        ftplugin/drini.vim
        ftplugin/drupal.vim
        plugin/drupal.vim
        snipmate/drupal/php.snippets
        snipmate/drupal6/php.snippets
        snipmate/drupal7/php.snippets
        syntax/drini.vim
        syntax/drupal.vim
        tagfiles/drupal6.tags
        tagfiles/drupal7.tags
        tagfiles/drupal8.tags

Don't forget the docs!

In order to install the documentation, start vim and do
:helptags ~/.vim/doc
(assuming that the path to the help file is ~/.vim/doc/drupal.txt). See add-local-help for details. To make sure it worked, try
:help drupal

Vimrc files

If you are new to vim (or have never bothered to configure it before) then you may want to use one of the supplied vimrc files. You can copy one of them to $HOME/.vimrc (or $HOME/_vimrc on Windows: see vimrc) or :source one of them from your own vimrc file. If you already have a vimrc file, then you may want to copy some settings from these files. See also :help vimrc_example.vim.

	vimrc_minimal.vim:  very basic
	vimrc_standard.vim:  This will :source vimrc_example.vim, which comes with the standard vim distribution.
	vimrc_timplunkett.vim:  This has many settings, with comments.

When the vimrc project first started, it was one file, similar to vimrc_timplunkett.vim. Now that the project contains many files, and some users are bothered by the original choices, we have moved these settings into this optional file.

Autocompletion in .info files

The drini (DRupal INI) filetype is used for .info and similar files. The syntax/drini.vim included in this project defines keywords that can be auto-completed using syntaxcomplete.vim, but this requires version 8.0 or later of that script. Version 7.0 is included in the original vim 7.3 distribution (in the autoload/ directory). As of late 2012, version 10.0 is available from http://www.vim.org/scripts/script.php?script_id=3172.

Tagbar (Exuberant ctags)

If you want to have instant access to your installed modules and personal code base, or if you want to use the Tagbar plugin, then you will need to have Exuberant ctags installed. To see whether it is already installed, run

 $ ctags --version

at a command prompt. The first line should be something like
Exuberant Ctags 5.8, Copyright (C) 1996-2009 Darren Hiebert.

Universal ctags is now supported (#2902266: Support for Universal Ctags). Universal ctags is the currently maintained implementation of ctags: it now indexes traits, Tagbar output is much improved. Until this has been sorted out in the referenced issue, you might need to call ctags with some specific options:

drush tags -v --ctags-options="--languages=php --php-kinds=cfit"

Drush integration

If you have not already installed drush, do it now. Since the 7.x-1.0-alpha4 release of the vimrc project, we recommend installing using drush. The vim-drush integration is growing, and there are plenty of other good reasons to use drush!

1. The \dv command described on our Other features page requires drush.
2. The vimrc project includes a drush command that invokes exuberant ctags to generate your own tags files.
3. You can use :Drush subcommand to run a drush command from vim and save its output in a scratch buffer.
4. Editing drush scripts and make files with vim benefits from this project almost as mch as editing Drupal modules.

Highlighting and correcting errors

In order to highlight syntax errors and violations of Drupal coding standards, install the Syntastic plugin for vim. (See the Recommended plugins page.) You will also have to install the Drupal Code Sniffer project and the CodeSniffer PHP script (phpcs). See the documentation for Drupal Code Sniffer for more installation information.

The Drupal Code Sniffer project is now part of the Coder project, and the directory names have changed. See #1839806: Update Coder and DrupalCS support for how this affects the Vimrc project.

If you want to correct errors automatically, then install and enable the Coder module. See our Other features page for how to invoke Coder from inside Vim. After installing the help files as described above, you can also read :help drupal-coder.

Gotchas

If you have previously installed another drupal_snippets project you will need to remove it as the snippets will conflict with the ones provided with this project.

Do not set g:syntastic_phpcs_conf in your vimrc file, since it will be overwritten by the ftplugin in this project. Do read the installation instructions for Coder/Drupal Code Sniffer (see above).