README.markdown

   1 # pathogen.vim
   2
   3 Manage your `'runtimepath'` with ease.  In practical terms, pathogen.vim
   4 makes it super easy to install plugins and runtime files in their own
   5 private directories.
   6
   7 **For new users, I recommend using Vim's built-in package management
   8 instead.**  `:help packages`
   9
  10 ## Installation
  11
  12 Install to `~/.vim/autoload/pathogen.vim`.
  13 Or copy and paste the following into your terminal/shell:
  14
  15     mkdir -p ~/.vim/autoload ~/.vim/bundle && \
  16     curl -LSso ~/.vim/autoload/pathogen.vim https://tpo.pe/pathogen.vim
  17
  18 If you're using Windows, change all occurrences of `~/.vim` to `~\vimfiles`.
  19
  20 ## Runtime Path Manipulation
  21
  22 Add this to your vimrc:
  23
  24     execute pathogen#infect()
  25
  26 If you're brand new to Vim and lacking a vimrc, `vim ~/.vimrc` and paste
  27 in the following super-minimal example:
  28
  29     execute pathogen#infect()
  30     syntax on
  31     filetype plugin indent on
  32
  33 Now any plugins you wish to install can be extracted to a subdirectory
  34 under `~/.vim/bundle`, and they will be added to the `'runtimepath'`.
  35 Observe:
  36
  37     cd ~/.vim/bundle && \
  38     git clone https://github.com/tpope/vim-sensible.git
  39
  40 Now [sensible.vim](https://github.com/tpope/vim-sensible) is installed.
  41 If you really want to get crazy, you could set it up as a submodule in
  42 whatever repository you keep your dot files in.  I don't like to get
  43 crazy.
  44
  45 If you don't like the directory name `bundle`, you can pass a runtime relative
  46 glob as an argument:
  47
  48     execute pathogen#infect('stuff/{}')
  49
  50 The `{}` indicates where the expansion should occur.
  51
  52 You can also pass an absolute path instead.  I keep the plugins I maintain under `~/src`, and this is how I add them:
  53
  54     execute pathogen#infect('bundle/{}', '~/src/vim/bundle/{}')
  55
  56 Normally to generate documentation, Vim expects you to run `:helptags`
  57 on each directory with documentation (e.g., `:helptags ~/.vim/doc`).
  58 Provided with pathogen.vim is a `:Helptags` command that does this on
  59 every directory in your `'runtimepath'`.  If you really want to get
  60 crazy, you could even invoke `Helptags` in your vimrc.  I don't like to
  61 get crazy.
  62
  63 Finally, pathogen.vim has a rich API that can manipulate `'runtimepath'`
  64 and other comma-delimited path options in ways most people will never
  65 need to do.  If you're one of those edge cases, look at the source.
  66 It's well documented.
  67
  68 ## Native Vim Package Management
  69
  70 Vim 8 includes support for package management in a manner similar to
  71 pathogen.vim.  If you'd like to transition to this native support,
  72 pathogen.vim can help.  Calling `pathogen#infect()` on an older version of Vim
  73 will supplement the `bundle/{}` default with `pack/{}/start/{}`, effectively
  74 backporting a subset of the new native functionality.
  75
  76 ## Runtime File Editing
  77
  78 `:Vopen`, `:Vedit`, `:Vsplit`, `:Vvsplit`, `:Vtabedit`, `:Vpedit`, and
  79 `:Vread` have all moved to [scriptease.vim][].
  80
  81 [scriptease.vim]: https://github.com/tpope/vim-scriptease
  82
  83 ## FAQ
  84
  85 > Can I put pathogen.vim in a submodule like all my other plugins?
  86
  87 Sure, stick it under `~/.vim/bundle`, and prepend the following to your
  88 vimrc:
  89
  90     runtime bundle/vim-pathogen/autoload/pathogen.vim
  91
  92 Or if your bundles are somewhere other than `~/.vim` (say, `~/src/vim`):
  93
  94     source ~/src/vim/bundle/vim-pathogen/autoload/pathogen.vim
  95
  96 > Will you accept these 14 pull requests adding a `.gitignore` for
  97 > `tags` so I don't see untracked changes in my dot files repository?
  98
  99 No, but I'll teach you how to ignore `tags` globally:
 100
 101     git config --global core.excludesfile '~/.cvsignore'
 102     echo tags >> ~/.cvsignore
 103
 104 While any filename will work, I've chosen to follow the ancient
 105 tradition of `.cvsignore` because utilities like rsync use it, too.
 106 Clever, huh?
 107
 108 > What about Vimballs?
 109
 110 If you really must use one:
 111
 112     :e name.vba
 113     :!mkdir ~/.vim/bundle/name
 114     :UseVimball ~/.vim/bundle/name
 115
 116 > Why don't my plugins load when I use Vim sessions?
 117
 118 Vim sessions default to capturing all global options, which includes the
 119 `'runtimepath'` that pathogen.vim manipulates.  This can cause other problems
 120 too, so I recommend turning that behavior off:
 121
 122     set sessionoptions-=options
 123
 124 ## Contributing
 125
 126 If your [commit message sucks](http://stopwritingramblingcommitmessages.com/),
 127 I'm not going to accept your pull request.  I've explained very politely
 128 dozens of times that
 129 [my general guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
 130 are absolute rules on my own repositories, so I may lack the energy to
 131 explain it to you yet another time.  And please, if I ask you to change
 132 something, `git commit --amend`.
 133
 134 Beyond that, don't be shy about asking before patching.  What takes you
 135 hours might take me minutes simply because I have both domain knowledge
 136 and a perverse knowledge of Vim script so vast that many would consider
 137 it a symptom of mental illness.  On the flip side, some ideas I'll
 138 reject no matter how good the implementation is.  "Send a patch" is an
 139 edge case answer in my book.
 140
 141 ## Self-Promotion
 142
 143 Like pathogen.vim?  Follow the repository on
 144 [GitHub](https://github.com/tpope/vim-pathogen) and vote for it on
 145 [vim.org](http://www.vim.org/scripts/script.php?script_id=2332).  And if
 146 you're feeling especially charitable, follow [tpope](http://tpo.pe/) on
 147 [Twitter](http://twitter.com/tpope) and
 148 [GitHub](https://github.com/tpope).
 149
 150 ## License
 151
 152 Copyright (c) Tim Pope.  Distributed under the same terms as Vim itself.
 153 See `:help license`.