F/ Vim Configuration
To Get The Full Effect
F/ peops, double check, but you most likely already have the basic requirements installed on your machine.
- Homebrew -
ruby -e "$(curl -fsSL https://gist.github.com/raw/323731/install_homebrew.rb)"
- MacVim -
brew install macvim
- Homesick -
gem install homesick
- discount -
brew install discount
- ctags -
brew install ctags
MacVim is not a requirement as the majority of the files work in most *nix environments including Terminal. It's recommended to use Homebrew's package of MacVim, as it compiles MacVim and Vim at 64 bit with Ruby, Python, Perl, installs the command line link
mvim, plus a bunch of other goodness. Homesick is required for easy management of dot files with the repository. The discount executable is recommended for converting markdown files to html for previewing. The ctags executable is helpful for taglist (jumping between files) and omni completion.
To install the files and default configuration run the following:
homesick clone firstname.lastname@example.org:factorylabs/vimfiles.git cd ~/.homesick/repos/vimfiles bash install.sh homesick symlink vimfiles -f
* If you don't have commit rights use
homesick clone https://github.com/factorylabs/vimfiles.git
This will install the default configuration files/directories, submodules, and create symbolic links for bundles and snippets. Most of the heavy lifting is done by the install script.
At this point you should have a default setup ready to rock. You're going to want to tune it a bit to your environment, so go forth and "Pimp Your Ride".
Pimp Your Ride
install.sh script created a
.vimrc.local file. This stores local configurations based on the user's needs, it is loaded after the
.vimrc file. Anything created in
.vimrc.local overrides settings set in
.vimrc. This file is ignored and not checked back into the repository. It's recommended you keep a backup of this somewhere.
You'll want to tune a few settings right off the bat. Open the
.vimrc.local file (in Vim type
,evl a mnemonic is "edit vimrc local").
g:yankring_history_dirand optionally change it's path, otherwise
yankringwill save it's history in a file in your
- Optional, point
g:MarkdownPreviewUserStylesto the directory where your user specific style sheets for the markdown previewer reside. If your an F/ peop, you can clone the repository for F/ Markdown Themes and gain templates and style sheets to keep you out of MS Word.
- Set the default browser by changing
g:RefreshRunningBrowserDefault. Use "chrome", "safari", or "firefox"
- Give yourself a signature with
g:snips_authorby including your name for various snipmate snippets
- Optionally uncomment one of the
colorschemes, there are 4 included as described below, the default is
- It's recommended to uncomment the entire conditional under User GUI specific settings. We roll with the custom font MesloGM at 12px. You'll need to download and install it, otherwise roll with Monaco or something if you want to go blind. If you want to set a transparency, you'll need to enable Use experimental renderer in MacVim's preferences -> Advanced settings. The primary reason for uncommenting this conditional is, you'll find certain plug-ins need to be disabled or have certain settings applied to work across MacVim and various *nix environments.
You can apply custom key bindings in
.vimrc.local, configure plug-ins, or override default settings.
Submodule plug-ins generate
doc/tag files associated with help documents every time Vim is launched. This creates conflicts associated with pulling, updating or committing changes back to the main repository. It's necessary to clean these out before running any pulls or commits.
Updating From The F/ Repository
To update from the latest changes in the F/ repository run the following:
- Quit out of Vim
git addany updates from your environment spit out by the
git pull --rebase
Commit your changes back up to the repository.
To pull upstream changes for all of the submodules run the following:
- Quit out of Vim
git addany updates from your environment spit out by the
git pull --rebase
Commit your changes back up to the repository. F/ will run this script once a week to keep the submodules as up to date as possible.
Plug-ins are managed using pathogen. All submodule plug-ins are stored in the
bundle_storage directory and are not available to Vim until they are symlinked to the
bundle directory. The
bundle directory is ignored by the repository allowing custom configurations on a per install basis. To activate a plug-in run:
ln -s ~/path/to/vimfiles/bundle_storage/bundle-name ~/path/to/vimfiles/bundle/bundle-name
You'll need to restart Vim for the changes to take effect.
Adding New Plug-Ins As Submodules
New plug-ins need to be added to the
bundle_storage directory and should be treated as submodules. To add a new one run:
git submodule add <remote_repository> <home/.vim/bundle_storage/bundle-name> git submodule init git submodule update ln -s ~/path/to/vimfiles/bundle_storage/bundle-name ~/path/to/vimfiles/bundle/bundle-name
Test it out and if it's a keeper, add it to the repository, add it to the list below with a quick description and tell the world about it's greatness.
Vim Scripts has an enormous amount of repositories for all sorts of plug-ins. However, if the original author has their own github repository, try to clone from there instead.
- Delete the relevant line from the
- Delete the relevant section from
git rm --cached path_to_submodule(no trailing slash!!)
- Remove the directory from
- Remove the symbolic link from
- Remove any descriptions from the
The install script created initial symbolic links for the plug-ins listed below. These are primarily file type oriented plus a few must haves. You can disable any of these by removing the symbolic link, but it would be a lot cooler if you didn't.
These are the additional plug-ins included, but are not required. They are not linked to the
bundle directory out of the box. If adding any of these, make sure to read the docs on their usage and what variables/settings may be required in
- argtextobj.vim - Motion commands for manipulating function arguments **
- autocomplpop.vim - Live completion as you type, this can slow Vim down, but is useful in certain situations
- autocorrect.vim - Corrects misspellings as you type i.e. teh -> the **
- bufkill.vim - Unload, delete or wipe a buffer
- camelcasemotion - Motion commands for moving between camelCase or words_with_underscores **
- clang-complete - Use clang for completing C/C++ code.
- colorsel.vim - Interactive RGB/HSV color selector
- Command-T - Just like TextMate
- delimitMate - Automatic closing of quotes, parenthesis, brackets, etc. **
- gundo - Graph Vim's undo tree so it is actually usable
- html-autoclose.vim - Automatically closes HTML tags, doesn't play well with the delimitMate plugin
- indexed-search.vim - Adds visual cues when performing searches within a file **
- lustyjuggler - Enables a window for navigating through open buffers
- specky - Plug-in for testing Ruby code with RSpec
- tabular - Configurable, flexible, intuitive text aligning **
- tailminusf - Watch the contents of a file in real time
- vim-ragtag - Ghetto XML/HTML mappings
- vim-repeat - Enable repeating commands mapped to "." **
- vim-speeddating - Use CTRL-A/CTRL-X to increment dates, times, and more
- vim-surround - Delete, change, and add "surroundings" i.e. parentheses, quotes, and HTML tags **
** - Recommended!
By default all of the snippet files stored within
snippets_storage are symlinked into the
snippets directory. These cover most of the languages used at F/. To see the available snippets for a given file type hit
<F5>, a snippet is triggered using
language-library.snippets. Since snippets are saved in the
snippets_storage directory, you can be selective about what gets a symbolic link within the
If you are working in a project that includes jQuery, you would only have symbolic links created for
To learn more about snipmate and creating snippets, type
For a quick way to do this, you may want to create a shell script to help automate the process. You'll need to restart Vim for the snippets to take affect.
The configuration uses syntastic quite heavily, most of it is out of the box. Buffers are checked after each save.
$HOME directory. Instructions for doing this are located at the jshint-config repository. This installation will make it global to your machine. If you need a specific configuration on a per project basis, just drop a
.jshintrc file in your project directory and tweak the settings.
There is also an Objective C checker included. This uses the
gcc and requires the
cwd to have the
.xcodeproj file in it.
To learn more about syntastic and syntax checkers, type
Themes included with this configuration:
colorblind: Black background, super vibrant colors
snowblind: White background, vibrant colors
cataracts: Grey background with muted colors
bloodshot: Similar to colorblind but with muted colors
extras directory are Terminal themes to match the Vim color themes.
The color themes have been designed with similarities in the syntax settings. Jumping between multiple languages should be easy on the mind and the eyes. Be adventurous and mix it up once in a while.
Most themes use the custom MesloGM font. Download, install and live the dream.
Within Vim type
:h fcheat to view key and leader bindings for the F/ configuration
Turn Caps Lock Into The Control Key
The control key is in an awkward position and the caps lock key is basically useless. It's right there in the home row, so you might as well put it to good use.
- Open up System Preferences
- From the drop down, select
^ Controlunder the
- In the
Select Keyboarddrop down, you'll want to set it for both internal and external keyboards
- Launch MacVim from Terminal by typing
mvimand hitting enter
- Right click the logo in your dock and select
Options > Show in Finder
- Create an alias of
MacVim.appand drop it in the
/Applications/directory (this will allow it to be found by Spotlight)
- Optionally choose to keep the icon in your dock
Options > Keep in Dock
Alias MacVim's install of Vim For Terminal
Fire up your
.zshrc or wherever your aliases are and add the following:
Your path may be different depending on the latest version from homebrew.
Once you point the alias to MacVim's Vim executable, you should be able to run plug-ins and crap that depend on ruby, python and so on. While you won't get all the niceties of the gui app, you'll at least have a similar install for your Terminal as what's in MacVim.
Mouse Support For Terminal
To get full mouse support (scrolling, clicking, etc...) within Terminal Vim, install the SIMBL MouseTerm plug-in. It brings the goodness.
Working With Your Own Submodules
In order to keep your personal submodules available to forks but allow commits back to the upstream master repository from within the submodule:
- Create the repository for your bundle within git
- Then from the
vimfilesdirectory add the submodule as you would any other submodule
- Within your newly created submodule, create a remote reference to the upstream master repository
- Make changes to the submodule and push updates back to the remote upstream master
- Then whenever you pull updates to all of your submodules, you as well as everyone else should get the changes
Here is an example:
cd ~/.homesick/repos/vimfiles/ git submodule add git://github.com/username/submodule-name.vim.git home/.vim/bundle_storage/submodule-name.vim cd home/.vim/bundle_storage/submodule-name.vim/ git remote add push email@example.com:username/submodule-name.vim.git git submodule init git submodule update ln -s ~/path/to/vimfiles/bundle_storage/submodule-name.vim ~/path/to/vimfiles/bundle/submodule-name.vim
Then whenever you make changes to the submodule:
cd ~/.homesick/repos/vimfiles/home/.vim/bundle_storage/submodule-name.vim/ git push push master
This allows you to make changes directly in your submodule, see the effects and push the changes back without maintaining multiple repositories and linking them back and forth. Defunkt has a good article about working with submodules.
License and Contributions
All licensing for the Bundles/Plug-ins should be found in their respective repositories. Anything written by F/ is of course open source through MIT. While contributions are welcome, you're probably better off forking and tuning it to your own machine.
Copyright (c) 2011 by Factory Design Labs
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.