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.

To enable submodules:

git submodule init

Installing plugins

To install plugins using Vim 8's native package system run:

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

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

Removing plugins

To remove reponame:

cd ~/.vim
git submodule deinit pack/plugins/start/reponame
git rm -r pack/plugins/start/reponame
rm -r .git/modules/pack/plugins/start/reponame

Updating plugins:

To update an individual plugin:

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

To 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.