|
| 1 | +pathogen.vim |
| 2 | +============ |
| 3 | + |
| 4 | +Manage your `'runtimepath'` with ease. In practical terms, pathogen.vim |
| 5 | +makes it super easy to install plugins and runtime files in their own |
| 6 | +private directories. |
| 7 | + |
| 8 | +Installation |
| 9 | +------------ |
| 10 | + |
| 11 | +Install to `~/.vim/autoload/pathogen.vim`. Or copy and paste: |
| 12 | + |
| 13 | + mkdir -p ~/.vim/autoload ~/.vim/bundle; \ |
| 14 | + curl -so ~/.vim/autoload/pathogen.vim \ |
| 15 | + https://raw.githubusercontent.com/tpope/vim-pathogen/HEAD/autoload/pathogen.vim |
| 16 | + |
| 17 | +If you don't have `curl`, use `wget -O -` instead. |
| 18 | + |
| 19 | +By the way, if you're using Windows, change all occurrences of `~/.vim` |
| 20 | +to `~\vimfiles`. |
| 21 | + |
| 22 | +Runtime Path Manipulation |
| 23 | +------------------------- |
| 24 | + |
| 25 | +Add this to your vimrc: |
| 26 | + |
| 27 | + call pathogen#infect() |
| 28 | + |
| 29 | +If you're brand new to Vim and lacking a vimrc, `vim ~/.vimrc` and paste |
| 30 | +in the following super-minimal example: |
| 31 | + |
| 32 | + call pathogen#infect() |
| 33 | + syntax on |
| 34 | + filetype plugin indent on |
| 35 | + |
| 36 | +Now any plugins you wish to install can be extracted to a subdirectory |
| 37 | +under `~/.vim/bundle`, and they will be added to the `'runtimepath'`. |
| 38 | +Observe: |
| 39 | + |
| 40 | + cd ~/.vim/bundle |
| 41 | + git clone git://github.com/tpope/vim-fugitive.git |
| 42 | + |
| 43 | +Now [fugitive.vim](https://github.com/tpope/vim-fugitive) is installed. |
| 44 | +If you really want to get crazy, you could set it up as a submodule in |
| 45 | +whatever repository you keep your dot files in. I don't like to get |
| 46 | +crazy. |
| 47 | + |
| 48 | +If you don't like the directory name `bundle`, you can pass a different |
| 49 | +name as an argument: |
| 50 | + |
| 51 | + call pathogen#infect('stuff') |
| 52 | + |
| 53 | +You can also pass an entire path instead. I keep the plugins I maintain |
| 54 | +under `~/src`, and this is how I add them: |
| 55 | + |
| 56 | + call pathogen#infect('~/src/vim/bundle') |
| 57 | + |
| 58 | +Normally to generate documentation, Vim expects you to run `:helptags` |
| 59 | +on each directory with documentation (e.g., `:helptags ~/.vim/doc`). |
| 60 | +Provided with pathogen.vim is a `:Helptags` command that does this on |
| 61 | +every directory in your `'runtimepath'`. If you really want to get |
| 62 | +crazy, you could even invoke `Helptags` in your vimrc. I don't like to |
| 63 | +get crazy. |
| 64 | + |
| 65 | +Finally, pathogen.vim has a rich API that can manipulate `'runtimepath'` |
| 66 | +and other comma-delimited path options in ways most people will never |
| 67 | +need to do. If you're one of those edge cases, look at the source. |
| 68 | +It's well documented. |
| 69 | + |
| 70 | +Runtime File Editing |
| 71 | +-------------------- |
| 72 | + |
| 73 | +As a guy who writes a lot of Vim script, I edit a lot of runtime files. |
| 74 | +For example, when editing PDF files like I do every day, I might notice |
| 75 | +something weird in the syntax highlighting and want to have a look: |
| 76 | + |
| 77 | + :sp $VIMRUNTIME/syntax/pdf.vim |
| 78 | + |
| 79 | +Even the best case scenario with tab complete is painful: |
| 80 | + |
| 81 | + :sp $VIMR<Tab>/synt<Tab>/pd<Tab> |
| 82 | + |
| 83 | +The picture is even bleaker if the file in question sits in a |
| 84 | +bundle. Enter the V family of commands. The V stands for Vimruntime |
| 85 | +(work with me here). |
| 86 | + |
| 87 | + :Vsp s/pd<Tab> |
| 88 | + |
| 89 | +As you can see, not only does it eliminate the need to qualify the |
| 90 | +runtime path being targeted, the tab completion is friendlier, allowing |
| 91 | +you to expand multiple components at once. Here's me editing |
| 92 | +pathogen.vim itself: |
| 93 | + |
| 94 | + :Ve a/pat<Tab> |
| 95 | + |
| 96 | +In the event of duplicate files, you can give a count to disambiguate. |
| 97 | +Here's the full list of commands: |
| 98 | + |
| 99 | +* `:Vedit` |
| 100 | +* `:Vsplit` |
| 101 | +* `:Vvsplit` |
| 102 | +* `:Vtabedit` |
| 103 | +* `:Vpedit` |
| 104 | +* `:Vread` |
| 105 | + |
| 106 | +All but `:Vedit` automatically `:lcd` to the target's runtime path. To |
| 107 | +suppress that behavior, use a `!`, and to `:lcd` with `:Vedit`, use |
| 108 | +`:Vopen` instead. |
| 109 | + |
| 110 | +FAQ |
| 111 | +--- |
| 112 | + |
| 113 | +> Can I put pathogen.vim in a submodule like all my other plugins? |
| 114 | +
|
| 115 | +Sure, stick it under `~/.vim/bundle`, and prepend the following to your |
| 116 | +vimrc: |
| 117 | + |
| 118 | + runtime bundle/vim-pathogen/autoload/pathogen.vim |
| 119 | + |
| 120 | +Or if your bundles are somewhere other than `~/.vim` (say, `~/src/vim`): |
| 121 | + |
| 122 | + source ~/src/vim/bundle/vim-pathogen/autoload/pathogen.vim |
| 123 | + |
| 124 | +> Will you accept these 14 pull requests adding a `.gitignore` for |
| 125 | +> `tags` so I don't see untracked changes in my dot files repository? |
| 126 | +
|
| 127 | +No, but I'll teach you how to ignore `tags` globally: |
| 128 | + |
| 129 | + git config --global core.excludesfile '~/.cvsignore' |
| 130 | + echo tags >> ~/.cvsignore |
| 131 | + |
| 132 | +While any filename will work, I've chosen to follow the ancient |
| 133 | +tradition of `.cvsignore` because utilities like rsync use it, too. |
| 134 | +Clever, huh? |
| 135 | + |
| 136 | +> What about Vimballs? |
| 137 | +
|
| 138 | +If you really must use one: |
| 139 | + |
| 140 | + :e name.vba |
| 141 | + :!mkdir ~/.vim/bundle/name |
| 142 | + :UseVimball ~/.vim/bundle/name |
| 143 | + |
| 144 | +Contributing |
| 145 | +------------ |
| 146 | + |
| 147 | +If your [commit message sucks](http://stopwritingramblingcommitmessages.com/), |
| 148 | +I'm not going to accept your pull request. I've explained very politely |
| 149 | +dozens of times that |
| 150 | +[my general guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) |
| 151 | +are absolute rules on my own repositories, so I may lack the energy to |
| 152 | +explain it to you yet another time. And please, if I ask you to change |
| 153 | +something, `git commit --amend`. |
| 154 | + |
| 155 | +Beyond that, don't be shy about asking before patching. What takes you |
| 156 | +hours might take me minutes simply because I have both domain knowledge |
| 157 | +and a perverse knowledge of Vim script so vast that many would consider |
| 158 | +it a symptom of mental illness. On the flip side, some ideas I'll |
| 159 | +reject no matter how good the implementation is. "Send a patch" is an |
| 160 | +edge case answer in my book. |
| 161 | + |
| 162 | +Self-Promotion |
| 163 | +-------------- |
| 164 | + |
| 165 | +Like pathogen.vim? Follow the repository on |
| 166 | +[GitHub](https://github.com/tpope/vim-pathogen) and vote for it on |
| 167 | +[vim.org](http://www.vim.org/scripts/script.php?script_id=2332). And if |
| 168 | +you're feeling especially charitable, follow [tpope](http://tpo.pe/) on |
| 169 | +[Twitter](http://twitter.com/tpope) and |
| 170 | +[GitHub](https://github.com/tpope). |
| 171 | + |
| 172 | +License |
| 173 | +------- |
| 174 | + |
| 175 | +Copyright (c) Tim Pope. Distributed under the same terms as Vim itself. |
| 176 | +See `:help license`. |
0 commit comments