spf13-vim installs and updates by piping a URL into a shell

Both the install and the update execute whatever the URL serves now

The installation line for Linux, other Unix systems and Mac is a fetch piped into a shell:

    curl https://j.mp/spf13-vim3 -L > spf13-vim.sh && sh spf13-vim.sh

A variant for a bash-compatible shell writes the script to standard input instead of a file. What both forms share is that the thing executed is whatever that short URL returns at that moment.

Then look at the update command, which is described as the simplest and safest way to update:

    curl https://j.mp/spf13-vim3 -L -o - | sh

Same URL, same absence of a version, same immediate execution. So every update re-runs a script you have not seen, and there is no release tag, no checksum and no artefact you can download and inspect first. The project publishes no GitHub releases, which is consistent with a distribution whose delivery mechanism is a bootstrap script rather than packaged versions.

The manual path is the alternative if you want to see what happens: clone the repository, pull, and run the bundle commands from inside Vim. Read the script before you pipe it, and prefer the manual path if the URL is not something you control.

The installer rewrites your vim configuration and keeps a backup

One sentence tells you what happens to what you already have: the installer will install spf13-vim and backup your existing vim configuration. The same paragraph notes that if you are upgrading from a version before 3.0, this is also the recommended path.

So the installer is not additive. It takes over the configuration files, which is the point, since the whole premise is that one configuration file should replace hand-assembled defaults. It also means that if you had a working setup before, you now have a backup file and a new set of files to reconcile.

That reconciliation is what the local files are for, and the design is consistent about it. Three filenames are named for the purpose: ~/.vimrc.local for your own settings, ~/.gvimrc.local for the graphical variant, and ~/.vimrc.before.local for customisations that need to load before the distributed configuration rather than after it. A fourth, ~/.vimrc.bundles.local, covers the bundle list. The example given is a single line appending a colour scheme choice to the local file.

The practical rule follows directly. Anything you add by editing the distributed vimrc is at risk on the next update, while anything in a local file is designed to survive.

The stated Vim minimum is not enough for the bundled plugins

The requirements section states that to make all the plugins work, specifically neocomplete, you need Vim with Lua. The platform installation section separately states the requirement as Git 1.7 or later and Vim 7.3 or later.

Those two statements are not quite compatible, and the gap is worth noticing.

A version number does not tell you whether a given build has Lua support. A machine satisfying the 7.3+ requirement can be running a build without it. In that case the distribution installs and most of it works, and one advertised plugin does not.

So check Lua support on your actual Vim build rather than trusting the version floor, particularly if neocomplete is one of the reasons you wanted a bundled completion setup. The same reasoning applies to any plugin in the set: the requirement named in the README is the one that is easy to miss, not necessarily the only one.

The Windows path is a chain of manual steps ending in Administrator Mode

The claim that it works on Windows, Linux and Mac without modifications does not survive contact with the Windows instructions, which are the longest part of the front page.

There is a fast route, through Chocolatey: choco install spf13-vim, which also installs Vim itself. Everything else is the manual route, and it runs to six steps. Install Vim, then add a directory to your environment path, which the instructions help you find by opening Vim and echoing $VIMRUNTIME. Install msysgit and confirm it with git --version. Set up curl, which is bundled with msysgit but has to be made runnable from the command prompt, which the instructions solve by having you create a curl.cmd file containing a specific batch script, credited as copied from the Vundle readme, and copy it into the Git cmd directory. Confirm curl works. Then download spf13-vim-windows-install.cmd and run it.

And the last instruction is the one that catches people out: run that file in Administrator Mode if you want the symlinks to be created successfully.

Without it, the README warns, the symlinks may not be created successfully. This is where the cross platform claim costs the most.

Two Windows installers ship, one of them for Windows XP

The repository contains spf13-vim-windows-install.cmd and, beside it, spf13-vim-windows-xp-install.cmd.

An XP-era installer still being carried is a small thing, but it dates the Windows story precisely. The surrounding documentation reinforces that dating: the example output for locating Vim shows a Program Files (x86) path with a vim74 folder, the sample msysgit version string is 1.7.4 from the msysgit era, and the sample curl output shows version 7.21.1 linked against OpenSSL 0.9.8k.

Those version numbers in the documentation are illustrations rather than requirements, and nobody should install that old curl to follow them. Read them as evidence of when the instructions were written rather than as targets.

The practical consequence is about expectations. Someone arriving at these instructions today on a current Windows machine is reading documentation written for a much older one, and the parts that still hold are the parts that do not depend on those versions, which is essentially the Chocolatey route and the curl.cmd workaround.

If the manual route fails on a modern machine, the version mismatch in the docs is a reasonable first suspicion.

The three local files are the only edits guaranteed to survive

The customisation story is the part of this distribution that works the way it advertises, and it is worth understanding precisely because everything else flows from it.

The distributed configuration is a single file described as suited to programming, extremely well organised, folding into sections with each section labelled and each option commented. It fixes a specific list of irritations: one configuration usable across Windows, Mac and Linux; swap and backup files kept in a central location rather than scattered through your directories; common typos such as :W and :Q corrected; formatting settings; and interface options including omnicomplete, line numbers, syntax highlighting and an improved ruler and status line.

Your own changes belong in the local layer. Write to ~/.vimrc.local or ~/.gvimrc.local for settings that apply after the distribution loads, write to ~/.vimrc.before.local for settings that must apply before, and keep your bundle overrides in ~/.vimrc.bundles.local. The before file exists for customisations that must load before the spf13-vim .vimrc.

Adopt that convention on day one and updates become uneventful.

The manual update path can leave broken symlinks behind

The manual update sequence is three commands:

    cd $HOME/to/spf13-vim/
    git pull
    vim +BundleInstall! +BundleClean +q

It is presented as the alternative to rerunning the installer, and it does something the installer does for you. The paragraph immediately after it says that if anything has changed with the structure of the configuration, you will need to create the appropriate symlinks.

So the manual path has a manual step with no detection and no error. If a future commit moves a directory and expects a symlink pointing at it, the pull succeeds, the bundle commands succeed, and you are left with a configuration that resolves some paths and silently fails on others.

This is the real trade between the two update routes. The automated route handles structural changes but re-executes a fetched script. The manual route lets you see every step but hands you symlink maintenance with no way to know whether you need it.

Whichever you pick, read the output rather than assuming it finished.

Editorial conclusion

spf13-vim is worth trying if you want a batteries-included Vim setup that behaves the same on every machine, and you are starting from a clean configuration rather than an opinionated one you have already tuned. Three things to decide first. Read the installer before running it, since the install path executes a fetched script with no pin or checksum. Put your own settings in the local files rather than editing the distributed vimrc, because the local files are the README's documented place for customisations. And check your Vim has Lua support if you want neocomplete, which the stated minimum version number does not guarantee.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. spf13/spf13-vim on GitHub