The git repository at github.com/xolox/vim-misc contains Vim scripts that are used by most of the Vim plug-ins I’ve written yet don’t really belong with any single one of the plug-ins. Basically it’s an extended standard library of Vim script functions that I wrote during the development of my Vim plug-ins.
The miscellaneous scripts are bundled with each of my plug-ins using git merges, so that a repository checkout of a plug-in contains everything that’s needed to get started. This means the git repository of the miscellaneous scripts is only used to track changes in a central, public place.
Here’s how I merge the miscellaneous scripts into a Vim plug-in repository:
Let git know about the
vim-misc repository by adding the remote GitHub repository:
git remote add -f vim-misc https://github.com/xolox/vim-misc.git
Merge the two directory trees without clobbering the
.gitignore files, thanks to the selected merge strategy and options:
git checkout master git merge --no-commit -s recursive -X ours vim-misc/master git commit -m "Merge vim-misc repository as overlay"
While steps 1 and 2 need to be done only once for a given repository, the following commands are needed every time I want to pull and merge the latest changes:
git checkout master git fetch vim-misc master git merge --no-commit -s recursive -X ours vim-misc/master git commit -m "Merged changes to miscellaneous scripts"
I came up with this solution after multiple years of back and forth between Vim Online users, the GitHub crowd and my own sanity:
When I started publishing my first Vim plug-ins (in June 2010) I would prepare ZIP archives for Vim Online using makefiles. The makefiles would make sure the miscellaneous scripts were included in the uploaded distributions. This had two disadvantages: It lost git history and the repositories on GitHub were not usable out of the box, so I got complaints from GitHub (Pathogen) users.
My second attempt to solve the problem used git submodules which seemed like the ideal solution until I actually started using them in March 2011: Submodules are not initialized during a normal
git clone, you need to use
git clone --recursive instead but Vim plug-in managers like Pathogen and Vundle don’t do this (at least they didn’t when I tried) so people would end up with broken checkouts.
After finding out that git submodules were not going to solve my problems I searched for other inclusion strategies supported by git. After a while I came upon the subtree merge strategy which I started using in May 2011 and stuck with for more than two years (because it generally worked fine and seemed quite robust).
In April 2013 the flat layout of the repository started bothering me because it broke my personal workflow, so I changed it to the proper directory layout of a Vim plug-in. Why did it break my workflow? Because I couldn’t get my vim-reload plug-in to properly reload miscellaneous scripts without nasty hacks. Note to self: Dropbox does not respect symbolic links and Vim doesn’t like them either (E746).
Regardless of the inclusion strategies discussed above, my current scheme has a flaw: If more than one of my plug-ins are installed in a Vim profile using Pathogen or Vundle, the miscellaneous autoload scripts will all be loaded from the subdirectory of one single plug-in.
This means that when I break compatibility in the miscellaneous scripts, I have to make sure to merge the changes into all of my plug-ins. Even then, if a user has more than one of my plug-ins installed but updates only one of them, the other plug-ins (that are not yet up to date) can break (because of the backwards incompatible change).
xolox#misc#compat#check() function makes sure that incompatibilities are detected early so that the user knows which plug-in to update if incompatibilities arise.
If you have questions, bug reports, suggestions, etc. the author can be contacted at email@example.com. The latest version is available at http://peterodding.com/code/vim/misc and http://github.com/xolox/vim-misc.
This software is licensed under the MIT license.
© 2013 Peter Odding <firstname.lastname@example.org>.
Last updated Sun Apr 28 22:10:40 UTC 2013.