Version control vim plugins with git submodules

It’s a good idea to keep the .vim directory version-controlled along with your .vimrc. You will need to use git submodules if the directory contains plugins that are versioned from their respective git repositories.

Setup

cd to the git repo responsible for version control of the .vim directory, or if you are using a bare git repo, replace git with the repo alias in all of the following commands;

To enable submodules:

git submodule init

Installing plugins

Install a plugin using Vim 8’s native package system:

git submodule add <package-url> <desired-filepath>

# Example
git submodule add https://github.com/username/reponame.git pack/plugins/start/reponame

Removing plugins

Remove a plugin:

# Deinitialize the submodule
git submodule deinit <plugin-filepath>
# Remove the submodule
git rm -r <plugin-filepath>
# Remove the submodule's git directory
rm -rf .git/modules/<plugin-filepath>

Updating plugins:

Update an individual plugin:

git submodule update --remote --merge <plugin-filepath>

Update all plugins:

git submodule update --remote --merge

Note that new commits to plugins create uncommitted changes in the main repository. Thus, after any updates in the submodules, you need to commit the main repository as well.

Replicating the repository on a machine

Clone the repository recursively to clone plugins:

git clone --recurse-submodules https://github.com/your_username/your_reponame.git

Ignore changes in a submodule

Some plugins need to generate files that will make the working tree dirty. This can be resolved by locating the appropriate .gitmodules file and adding ignore = dirty to the responsible repo.

Git Documentation

Common issues

Error already exists in the index

Be sure you git rm the submodule. If you’ve already run rm, running git rm again will fail since the directory doesn’t exist. Create an empty directory with the module name at the location and run git rm of that directory.