]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/README.markdown
Add license
[rbdr/dotfiles] / vim / README.markdown
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