| 1 | # Janus: Carlhuda's vim Distribution |
| 2 | |
| 3 | This is a basic distribution of vim plugins and tools intended to be run |
| 4 | on top of the latest MacVIM snapshot. |
| 5 | |
| 6 | We (Carl and Yehuda) both use this distribution for our own use, and |
| 7 | welcome patches and contributions to help make it an effective way to |
| 8 | get started with vim and then use it productively for years to come. |
| 9 | |
| 10 | At present, we are still learning to use vim ourselves, so you should |
| 11 | anticipate a period of rapid development while we get a handle on the |
| 12 | best tools for the job. So far, we have mostly integrated existing |
| 13 | plugins and tools, and we anticipate to continue doing so while also |
| 14 | writing our own plugins as appropriate. |
| 15 | |
| 16 | In general, you can expect that the tools we use work well together and |
| 17 | that we have given careful thought to the experience of using MacVIM |
| 18 | with the tools in question. If you run into an issue using it, please |
| 19 | report an issue to the issue tracker. |
| 20 | |
| 21 | ## Pre-requisites |
| 22 | |
| 23 | Janus is built primarily for [MacVim](http://code.google.com/p/macvim/) on OSX. |
| 24 | Download it [here](https://github.com/b4winckler/macvim/downloads). |
| 25 | |
| 26 | Alternatively, you can use Janus with the bundled console `vim` installation on |
| 27 | OSX (via Terminal), or with any other `vim` or `gvim` installation. |
| 28 | |
| 29 | Linux users can install `gvim` for an experience identical to MacVim. |
| 30 | On Debian/Ubuntu, simply `apt-get install vim-gnome`. For remote |
| 31 | servers, install console vim with `apt-get install vim-nox`. |
| 32 | |
| 33 | On a fresh Ubuntu install you also have to install the packages `rake` and `ruby-dev` |
| 34 | before running the install script and `exuberant-ctags` for ctags |
| 35 | support. |
| 36 | |
| 37 | ## Installation |
| 38 | |
| 39 | 0. `for i in ~/.vim ~/.vimrc ~/.gvimrc; do [ -e $i ] && mv $i $i.old; |
| 40 | done` |
| 41 | 1. `git clone git://github.com/carlhuda/janus.git ~/.vim` |
| 42 | 2. `cd ~/.vim` |
| 43 | 3. `rake` |
| 44 | |
| 45 | or |
| 46 | |
| 47 | `curl https://raw.github.com/carlhuda/janus/master/bootstrap.sh -o - | sh` |
| 48 | |
| 49 | ## Customization |
| 50 | |
| 51 | Create `~/.vimrc.local` and `~/.gvimrc.local` for any local |
| 52 | customizations. |
| 53 | |
| 54 | For example, to override the default color schemes: |
| 55 | |
| 56 | echo color desert > ~/.vimrc.local |
| 57 | echo color molokai > ~/.gvimrc.local |
| 58 | |
| 59 | If you want to add additional Vim plugins you can do so by adding a |
| 60 | `~/.janus.rake` like so: |
| 61 | |
| 62 | vim_plugin_task "zencoding", "git://github.com/mattn/zencoding-vim.git" |
| 63 | vim_plugin_task "minibufexpl", "git://github.com/fholgado/minibufexpl.vim.git" |
| 64 | |
| 65 | If you do not wish to use one of the plugins Janus provides out of the |
| 66 | box you can have it skipped using the `skip_vim_plugin` method in |
| 67 | `~/.janus.rake`: |
| 68 | |
| 69 | skip_vim_plugin "color-sampler" |
| 70 | |
| 71 | **Note**: Skipping the plugin will only apply to installation. It won't |
| 72 | remove configurations or mappings Janus might have added for it. |
| 73 | |
| 74 | ## Updating to the latest version |
| 75 | |
| 76 | To update to the latest version of the distribution, just run `rake` |
| 77 | again inside your `~/.vim` directory. |
| 78 | |
| 79 | # Intro to VIM |
| 80 | |
| 81 | Here's some tips if you've never used VIM before: |
| 82 | |
| 83 | ## Tutorials |
| 84 | |
| 85 | * Type `vimtutor` into a shell to go through a brief interactive |
| 86 | tutorial inside VIM. |
| 87 | * Read the slides at [VIM: Walking Without Crutches](http://walking-without-crutches.heroku.com/#1). |
| 88 | * Watch the screencasts at [vimcasts.org](http://vimcasts.org/) |
| 89 | * Watch Derek Wyatt's energetic tutorial videos at [his site](http://www.derekwyatt.org/vim/vim-tutorial-videos/) |
| 90 | * Read wycats' perspective on learning vim at |
| 91 | [Everyone who tried to convince me to use vim was wrong](http://yehudakatz.com/2010/07/29/everyone-who-tried-to-convince-me-to-use-vim-was-wrong/) |
| 92 | * Read this and other answers to a question about vim at StackOverflow: |
| 93 | [Your problem with Vim is that you don't grok vi](http://stackoverflow.com/questions/1218390/what-is-your-most-productive-shortcut-with-vim/1220118#1220118) |
| 94 | |
| 95 | ## Modes |
| 96 | |
| 97 | * VIM has two modes: |
| 98 | * insert mode- stuff you type is added to the buffer |
| 99 | * normal mode- keys you hit are interpretted as commands |
| 100 | * To enter insert mode, hit `i` |
| 101 | * To exit insert mode, hit `<ESC>` |
| 102 | |
| 103 | ## Useful commands |
| 104 | |
| 105 | * Use `:q` to exit vim |
| 106 | * Certain commands are prefixed with a `<Leader>` key, which maps to `\` |
| 107 | by default. Use `let mapleader = ","` to change this. |
| 108 | * Keyboard [cheat sheet](http://walking-without-crutches.heroku.com/image/images/vi-vim-cheat-sheet.png). |
| 109 | |
| 110 | # Features |
| 111 | |
| 112 | This vim distribution includes a number of packages built by others. |
| 113 | |
| 114 | ## Base Customizations |
| 115 | |
| 116 | Janus ships with a number of basic customizations for vim: |
| 117 | |
| 118 | * Line numbers |
| 119 | * Ruler (line and column numbers) |
| 120 | * No wrap (turn off per-buffer via set :wrap) |
| 121 | * Soft 2-space tabs, and default hard tabs to 2 spaces |
| 122 | * Show tailing whitespace as `.` |
| 123 | * Make searching highlighted, incremental, and case insensitive unless a |
| 124 | capital letter is used |
| 125 | * Always show a status line |
| 126 | * Allow backspacing over everything (identations, eol, and start |
| 127 | characters) in insert mode |
| 128 | * `<Leader>e` expands to `:e {directory of current file}/` (open in the |
| 129 | current buffer) |
| 130 | * `<Leader>tr` expands to `:te {directory of current file}/` (open in a |
| 131 | new MacVIM tab) |
| 132 | * `<C-P>` inserts the directory of the current file into a command |
| 133 | |
| 134 | ## "Project Drawer" aka [NERDTree](http://github.com/wycats/nerdtree) |
| 135 | |
| 136 | NERDTree is a file explorer plugin that provides "project drawer" |
| 137 | functionality to your vim projects. You can learn more about it with |
| 138 | :help NERDTree. |
| 139 | |
| 140 | **Customizations**: Janus adds a number of customizations to the core |
| 141 | NERDTree: |
| 142 | |
| 143 | * Use `<Leader>n` to toggle NERDTree |
| 144 | * Ignore `*.rbc` and `*~` files |
| 145 | * Automatically activate NERDTree when MacVIM opens and make the |
| 146 | original buffer the active one |
| 147 | * Provide alternative :e, :cd, :rm and :touch abbreviations which also |
| 148 | refresh NERDTree when done (when NERDTree is open) |
| 149 | * When opening vim with vim /path, open the left NERDTree to that |
| 150 | directory, set the vim pwd, and clear the right buffer |
| 151 | * Disallow `:e`ing files into the NERDTree buffer |
| 152 | * In general, assume that there is a single NERDTree buffer on the left |
| 153 | and one or more editing buffers on the right |
| 154 | |
| 155 | ## [Ack.vim](http://github.com/mileszs/ack.vim) |
| 156 | |
| 157 | |
| 158 | Ack.vim uses ack to search inside the current directory for a pattern. |
| 159 | You can learn more about it with :help Ack |
| 160 | |
| 161 | **Customizations**: Janus rebinds command-shift-f (`<D-F>`) to bring up |
| 162 | `:Ack `. |
| 163 | |
| 164 | ## [Align](http://github.com/tsaleh/vim-align) |
| 165 | |
| 166 | Align lets you align statements on their equal signs, make comment |
| 167 | boxes, align comments, align declarations, etc. |
| 168 | |
| 169 | * `:5,10Align =>` to align lines 5-10 on `=>`'s |
| 170 | |
| 171 | ## [Command-T](https://wincent.com/products/command-t) |
| 172 | |
| 173 | Command-T provides a mechanism for searching for a file inside the |
| 174 | current working directory. It behaves similarly to command-t in |
| 175 | Textmate. |
| 176 | |
| 177 | **Customizations**: Janus rebinds command-t (`<D-t>`) to bring up this |
| 178 | plugin. It defaults to `<Leader>t`. |
| 179 | |
| 180 | ## [ConqueTerm](http://code.google.com/p/conque/) |
| 181 | |
| 182 | ConqueTerm embeds a basic terminal inside a vim buffer. The terminal has |
| 183 | an insert mode in which you can type commands, tab complete and use the |
| 184 | terminal like normal. You can also escape out of insert mode to use |
| 185 | other vim commands on the buffer, like yank and paste. |
| 186 | |
| 187 | **Customizations**: Janus binds command-e (`<D-e>`) to bring up |
| 188 | `:ConqueTerm bash --login` in the current buffer. |
| 189 | |
| 190 | **Note**: To get colors working, you might have to `export TERM=xterm` |
| 191 | and use `ls -G` or `gls --color` |
| 192 | |
| 193 | ## [indent\_object](http://github.com/michaeljsmith/vim-indent-object) |
| 194 | |
| 195 | Indent object creates a "text object" that is relative to the current |
| 196 | ident. Text objects work inside of visual mode, and with `c` (change), |
| 197 | `d` (delete) and `y` (yank). For instance, try going into a method in |
| 198 | normal mode, and type `v ii`. Then repeat `ii`. |
| 199 | |
| 200 | **Note**: indent\_object seems a bit busted. It would also be nice if |
| 201 | there was a text object for Ruby `class` and `def` blocks. |
| 202 | |
| 203 | ## [surround](http://github.com/tpope/vim-surround) |
| 204 | |
| 205 | Surround allows you to modify "surroundings" around the current text. |
| 206 | For instance, if the cursor was inside `"foo bar"`, you could type |
| 207 | `cs"'` to convert the text to `'foo bar'`. |
| 208 | |
| 209 | There's a lot more; check it out at `:help surround` |
| 210 | |
| 211 | ## [NERDCommenter](http://github.com/ddollar/nerdcommenter) |
| 212 | |
| 213 | NERDCommenter allows you to wrangle your code comments, regardless of |
| 214 | filetype. View `:help NERDCommenter` for all the details. |
| 215 | |
| 216 | **Customizations**: Janus binds command-/ (`<D-/>`) to toggle comments. |
| 217 | |
| 218 | ## [SuperTab](http://github.com/ervandew/supertab) |
| 219 | |
| 220 | In insert mode, start typing something and hit `<TAB>` to tab-complete |
| 221 | based on the current context. |
| 222 | |
| 223 | ## ctags |
| 224 | |
| 225 | Janus includes the [TagList](http://github.com/vim-scripts/taglist.vim) |
| 226 | plugin, which binds `:Tlist` to an overview panel that lists all ctags |
| 227 | for easy navigation. |
| 228 | |
| 229 | **Customizations**: Janus binds `<Leader>rt` to the ctags command to |
| 230 | update tags. |
| 231 | |
| 232 | **Note**: For full language support, run `brew install ctags` to install |
| 233 | exuberant-ctags. |
| 234 | |
| 235 | **Tip**: Check out `:help ctags` for information about VIM's built-in |
| 236 | ctag support. Tag navigation creates a stack which can traversed via |
| 237 | `Ctrl-]` (to find the source of a token) and `Ctrl-T` (to jump back up |
| 238 | one level). |
| 239 | |
| 240 | ## Git Support ([Fugitive](http://github.com/tpope/vim-fugitive)) |
| 241 | |
| 242 | Fugitive adds pervasive git support to git directories in vim. For more |
| 243 | information, use `:help fugitive` |
| 244 | |
| 245 | Use `:Gstatus` to view `git status` and type `-` on any file to stage or |
| 246 | unstage it. Type `p` on a file to enter `git add -p` and stage specific |
| 247 | hunks in the file. |
| 248 | |
| 249 | Use `:Gdiff` on an open file to see what changes have been made to that |
| 250 | file |
| 251 | |
| 252 | ## [Gist-vim](http://github.com/mattn/gist-vim) |
| 253 | |
| 254 | Nice [gist integration](https://github.com/mattn/gist-vim) by mattn. |
| 255 | Requires exporting your `GITHUB_TOKEN` and `GITHUB_USER` as environment |
| 256 | variables or setup your [GitHub token config](http://help.github.com/git-email-settings/). |
| 257 | |
| 258 | Try `:Gist`, `:Gist -p` and visual blocks. |
| 259 | |
| 260 | ## [ZoomWin](http://github.com/vim-scripts/ZoomWin) |
| 261 | |
| 262 | When working with split windows, ZoomWin lets you zoom into a window and |
| 263 | out again using `Ctrl-W o` |
| 264 | |
| 265 | **Customizations**: Janus binds `<Leader><Leader>` to `:ZoomWin` |
| 266 | |
| 267 | ## Additional Syntaxes |
| 268 | |
| 269 | Janus ships with a few additional syntaxes: |
| 270 | |
| 271 | * Markdown (bound to \*.markdown, \*.md, and \*.mk) |
| 272 | * Mustache (bound to \*.mustache) |
| 273 | * Arduino (bound to \*.pde) |
| 274 | * Haml (bound to \*.haml) |
| 275 | * Sass (bound to \*.sass) |
| 276 | * SCSS (bound to \*.scss) |
| 277 | * An improved JavaScript syntax (bound to \*.js) |
| 278 | * Map Gemfile, Rakefile, Vagrantfile and Thorfile to Ruby |
| 279 | * Git commits (set your `EDITOR` to `mvim -f`) |
| 280 | |
| 281 | ## Color schemes |
| 282 | |
| 283 | Janus includes the vim color sampler pack, which includes [over 100 |
| 284 | popular color themes](http://www.vi-improved.org/color_sampler_pack/): |
| 285 | |
| 286 | * jellybeans |
| 287 | * matrix |
| 288 | * railscasts2 |
| 289 | * tango |
| 290 | * vibrantink |
| 291 | * vividchalk |
| 292 | * wombat |
| 293 | * xoria256 |
| 294 | |
| 295 | Use `:color vibrantink` to switch to a color scheme. |
| 296 | |
| 297 | Janus also has a few customized versions of popular themes: |
| 298 | |
| 299 | * jellybeans+ |
| 300 | * molokai |
| 301 | * railscasts+ |
| 302 | * vwilight |
| 303 | |