mj / zsh-config

Download as
Browse Code ยป

Commit 290edb0058c11cc0c901b9c5813f610e1bc55147

Authored by Shrikant Sharat
1 parent 5fc03fbc8b

Fix link to github issues page. 

The link should point to the project under zsh-users organization and not under the sharat87 user.

Showing 1 changed file with 1 additions and 1 deletions Inline Diff

1 # Antigen 1 # Antigen
2 2
3 Antigen is a small set of functions that help you easily manage your shell (zsh) 3 Antigen is a small set of functions that help you easily manage your shell (zsh)
4 plugins, called bundles. The concept is pretty much the same as bundles in a 4 plugins, called bundles. The concept is pretty much the same as bundles in a
5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim. 5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.
6 6
7 Please note that this is a very new project and can be considered beta at best. 7 Please note that this is a very new project and can be considered beta at best.
8 That said, I am using antigen full time now on my work machine. 8 That said, I am using antigen full time now on my work machine.
9 9
10 Note: Please read the commit comments of the changesets when you pull a new 10 Note: Please read the commit comments of the changesets when you pull a new
11 version of antigen. 11 version of antigen.
12 12
13 ## Show off 13 ## Show off
14 14
15 > Enough talk. Let's fight! 15 > Enough talk. Let's fight!
16 > -- Po, Kung-fu Panda. 16 > -- Po, Kung-fu Panda.
17 17
18 You're going to experience antigen right in your open shell. No `.zshrc` 18 You're going to experience antigen right in your open shell. No `.zshrc`
19 tweaking and reading the rest of this documentation. Kinda like an ice-cream 19 tweaking and reading the rest of this documentation. Kinda like an ice-cream
20 sample, if you will. 20 sample, if you will.
21 21
22 Get and load antigen. 22 Get and load antigen.
23 23
24 curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh 24 curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh
25 source antigen.zsh 25 source antigen.zsh
26 26
27 There. You now have all the antigen goodies. Let's try install some plugins. How 27 There. You now have all the antigen goodies. Let's try install some plugins. How
28 about some color to start with. Get the [syntax highlighting plugin][] by 28 about some color to start with. Get the [syntax highlighting plugin][] by
29 running 29 running
30 30
31 antigen-bundle zsh-users/zsh-syntax-highlighting 31 antigen-bundle zsh-users/zsh-syntax-highlighting
32 32
33 Now let it do its thing and once you're back at your prompt, try and type a 33 Now let it do its thing and once you're back at your prompt, try and type a
34 command. See that? Colors! 34 command. See that? Colors!
35 35
36 So, you do git? ruby? git and ruby? There are lots of awesome plugins over at 36 So, you do git? ruby? git and ruby? There are lots of awesome plugins over at
37 oh-my-zsh. Treat yourself to some. 37 oh-my-zsh. Treat yourself to some.
38 38
39 antigen-bundle robbyrussell/oh-my-zsh plugins/ruby 39 antigen-bundle robbyrussell/oh-my-zsh plugins/ruby
40 # Or for the lazy, 40 # Or for the lazy,
41 antigen-bundle git 41 antigen-bundle git
42 42
43 There are lots of plugins out there in the wild and people are writing zsh 43 There are lots of plugins out there in the wild and people are writing zsh
44 utilities as small scripts all the time. Antigen is compatible with all of them. 44 utilities as small scripts all the time. Antigen is compatible with all of them.
45 The plugins and scripts don't need any special handling to be compatible with 45 The plugins and scripts don't need any special handling to be compatible with
46 antigen. 46 antigen.
47 47
48 Another example, [kennethreitz's autoenv][autoenv]. Just a bundle command away. 48 Another example, [kennethreitz's autoenv][autoenv]. Just a bundle command away.
49 49
50 antigen-bundle kennethreitz/autoenv 50 antigen-bundle kennethreitz/autoenv
51 51
52 And boom! you have all the autoenv goodness. Just remember how you used to do 52 And boom! you have all the autoenv goodness. Just remember how you used to do
53 these before antigen, clone it, modify your bashrc to source it, load a new 53 these before antigen, clone it, modify your bashrc to source it, load a new
54 terminal, all just to test it out. Duh! 54 terminal, all just to test it out. Duh!
55 55
56 A subtle aspect of this is that you can tell antigen to grab just about anything 56 A subtle aspect of this is that you can tell antigen to grab just about anything
57 from anyone's `dotfiles` repo, as long as it is in a directory under any repo on 57 from anyone's `dotfiles` repo, as long as it is in a directory under any repo on
58 github. 58 github.
59 59
60 And themes? How would you like a fancy new prompt for yourself? 60 And themes? How would you like a fancy new prompt for yourself?
61 61
62 antigen-theme funky 62 antigen-theme funky
63 63
64 No? Not your taste? There are many themes available to you, check out the 64 No? Not your taste? There are many themes available to you, check out the
65 oh-my-zsh's [page on themes][]. (You can currently only install themes from 65 oh-my-zsh's [page on themes][]. (You can currently only install themes from
66 robbyrussell's, i.e., the canonical oh-my-zsh repo). 66 robbyrussell's, i.e., the canonical oh-my-zsh repo).
67 67
68 Note: Many of those plugins and especially themes, assume you have the core 68 Note: Many of those plugins and especially themes, assume you have the core
69 library of oh-my-zsh loaded. So, if you want to experiment further, issue a 69 library of oh-my-zsh loaded. So, if you want to experiment further, issue a
70 70
71 antigen-lib 71 antigen-lib
72 72
73 and continue until you're tired. At which point you can come back to this page 73 and continue until you're tired. At which point you can come back to this page
74 ;) 74 ;)
75 75
76 ## Usage 76 ## Usage
77 77
78 So, now that you're here, I suppose you are convinced and want antigen running 78 So, now that you're here, I suppose you are convinced and want antigen running
79 your shell all the time. Sweet. Let's do it. 79 your shell all the time. Sweet. Let's do it.
80 80
81 First, clone this repo, probably as a submodule if you have your dotfiles in a 81 First, clone this repo, probably as a submodule if you have your dotfiles in a
82 git repo, 82 git repo,
83 83
84 git clone https://github.com/zsh-users/antigen.git 84 git clone https://github.com/zsh-users/antigen.git
85 85
86 The usage should be very familiar to you if you use Vundle. A typical `.zshrc` 86 The usage should be very familiar to you if you use Vundle. A typical `.zshrc`
87 might look like this 87 might look like this
88 88
89 source /path-to-antigen-clone/antigen.zsh 89 source /path-to-antigen-clone/antigen.zsh
90 90
91 # Load the oh-my-zsh's library. 91 # Load the oh-my-zsh's library.
92 antigen-lib 92 antigen-lib
93 93
94 # Bundles from the default repo (robbyrussell's oh-my-zsh). 94 # Bundles from the default repo (robbyrussell's oh-my-zsh).
95 antigen-bundle git 95 antigen-bundle git
96 antigen-bundle heroku 96 antigen-bundle heroku
97 antigen-bundle pip 97 antigen-bundle pip
98 antigen-bundle lein 98 antigen-bundle lein
99 antigen-bundle command-not-found 99 antigen-bundle command-not-found
100 100
101 # Syntax highlighting bundle. 101 # Syntax highlighting bundle.
102 antigen-bundle zsh-users/zsh-syntax-highlighting 102 antigen-bundle zsh-users/zsh-syntax-highlighting
103 103
104 # Load the theme. 104 # Load the theme.
105 antigen-theme robbyrussell 105 antigen-theme robbyrussell
106 106
107 # Tell antigen that you're done. 107 # Tell antigen that you're done.
108 antigen-apply 108 antigen-apply
109 109
110 Open your zsh with this zshrc and you should see all the bundles you defined 110 Open your zsh with this zshrc and you should see all the bundles you defined
111 here, getting installed. Once its done, you are ready to roll. The complete 111 here, getting installed. Once its done, you are ready to roll. The complete
112 syntax for the `antigen-bundle` command is discussed further down on this page. 112 syntax for the `antigen-bundle` command is discussed further down on this page.
113 113
114 ## Motivation 114 ## Motivation
115 115
116 If you use zsh and [oh-my-zsh][], you know that having many different plugins 116 If you use zsh and [oh-my-zsh][], you know that having many different plugins
117 that are developed by many different authors in a single (sub)repo is not very 117 that are developed by many different authors in a single (sub)repo is not very
118 easy to maintain. There are some really fantastic plugins and utilities in 118 easy to maintain. There are some really fantastic plugins and utilities in
119 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I 119 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I
120 admire robbyrussell's efforts for reviewing and merging the gigantic number of 120 admire robbyrussell's efforts for reviewing and merging the gigantic number of
121 pull requests the project gets. We need a better way of plugin management. 121 pull requests the project gets. We need a better way of plugin management.
122 122
123 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like 123 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
124 there was any progress made. So, I'm trying to start this off with antigen, 124 there was any progress made. So, I'm trying to start this off with antigen,
125 hoping to better this situation. Please note that I'm by no means a zsh or any 125 hoping to better this situation. Please note that I'm by no means a zsh or any
126 shell script expert (far from it). 126 shell script expert (far from it).
127 127
128 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 128 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
129 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 129 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
130 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 130 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
131 131
132 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github 132 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github
133 repositories. You are not limited to use plugins from the oh-my-zsh repository 133 repositories. You are not limited to use plugins from the oh-my-zsh repository
134 only and you don't need to maintain your own fork and pull from upstream every 134 only and you don't need to maintain your own fork and pull from upstream every
135 now and then. I actually encourage you to grab plugins and scripts from various 135 now and then. I actually encourage you to grab plugins and scripts from various
136 sources, straight from the authors, before they even submit it to oh-my-zsh as a 136 sources, straight from the authors, before they even submit it to oh-my-zsh as a
137 pull request. 137 pull request.
138 138
139 Antigen also lets you switch the prompt theme with one command, just like that 139 Antigen also lets you switch the prompt theme with one command, just like that
140 140
141 bundle-theme candy 141 bundle-theme candy
142 142
143 and your prompt is changed, just for this session of course (unless you put this 143 and your prompt is changed, just for this session of course (unless you put this
144 line in your `.zshrc`). 144 line in your `.zshrc`).
145 145
146 ## Commands 146 ## Commands
147 147
148 The following are the commands provided by antigen. Note that the `-` in the 148 The following are the commands provided by antigen. Note that the `-` in the
149 following commands can be replaced with a space. You can write `antigen-bundle 149 following commands can be replaced with a space. You can write `antigen-bundle
150 ...` as `antigen bundle ...` and get away with it. For more details see the help 150 ...` as `antigen bundle ...` and get away with it. For more details see the help
151 on `antigen` command further down in this section. 151 on `antigen` command further down in this section.
152 152
153 ### antigen-bundle 153 ### antigen-bundle
154 154
155 This command tells antigen to install (if not already installed) and load the 155 This command tells antigen to install (if not already installed) and load the
156 given plugin. The simplest usage follows the following syntax. 156 given plugin. The simplest usage follows the following syntax.
157 157
158 antigen-bundle <plugin-name> 158 antigen-bundle <plugin-name>
159 159
160 This will install and load the `plugins/<name>` directory from [robbyrussell's 160 This will install and load the `plugins/<name>` directory from [robbyrussell's
161 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`). 161 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
162 162
163 However, the above is just syntax sugar for the extended syntax of the 163 However, the above is just syntax sugar for the extended syntax of the
164 `antigen-bundle` command. 164 `antigen-bundle` command.
165 165
166 antigen-bundle [<url> [<loc>]] 166 antigen-bundle [<url> [<loc>]]
167 167
168 where `<url>` is the repository url and it defaults to [robbyrussell's 168 where `<url>` is the repository url and it defaults to [robbyrussell's
169 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL` 169 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`
170 discussed further down). `<loc>` is the path under this repository which has the 170 discussed further down). `<loc>` is the path under this repository which has the
171 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file, 171 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,
172 but it could contain a completion file or just many `*.zsh` files to be sourced. 172 but it could contain a completion file or just many `*.zsh` files to be sourced.
173 `<loc>` defaults to `/`, which indicates the repository itself is a plugin. 173 `<loc>` defaults to `/`, which indicates the repository itself is a plugin.
174 174
175 An example invocation would be 175 An example invocation would be
176 176
177 # The following is the same as `antigen-bundle ant`. But for demonstration 177 # The following is the same as `antigen-bundle ant`. But for demonstration
178 # purposes, we use the extended syntax here. 178 # purposes, we use the extended syntax here.
179 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 179 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
180 180
181 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course, 181 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
182 github url's can be shortened. 182 github url's can be shortened.
183 183
184 antigen-bundle robbyrussell/oh-my-zsh plugins/ant 184 antigen-bundle robbyrussell/oh-my-zsh plugins/ant
185 185
186 And since this repo is the default, even that isn't necessary. But we can't 186 And since this repo is the default, even that isn't necessary. But we can't
187 specify the `loc` without giving the first argument. 187 specify the `loc` without giving the first argument.
188 188
189 For this and a few other reasons, `antigen-bundle` also supports a simple 189 For this and a few other reasons, `antigen-bundle` also supports a simple
190 keyword argument syntax, using which we can rewrite the above as 190 keyword argument syntax, using which we can rewrite the above as
191 191
192 antigen-bundle --loc=plugins/ant 192 antigen-bundle --loc=plugins/ant
193 193
194 Which picks up the default for the `url` argument, and uses the `loc` given to 194 Which picks up the default for the `url` argument, and uses the `loc` given to
195 it. 195 it.
196 196
197 *Note* that you can mix and match positional and keyword arguments. But you 197 *Note* that you can mix and match positional and keyword arguments. But you
198 can't have positional arguments after keyword arguments. 198 can't have positional arguments after keyword arguments.
199 199
200 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant 200 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant
201 201
202 And keyword arguments don't care about the order in which the arguments are 202 And keyword arguments don't care about the order in which the arguments are
203 specified. The following is perfectly valid. 203 specified. The following is perfectly valid.
204 204
205 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh 205 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
206 206
207 You can also specify a local directory on your file system as a bundle. In this 207 You can also specify a local directory on your file system as a bundle. In this
208 case, make sure the path you give is the absolute path (i.e., starts with a 208 case, make sure the path you give is the absolute path (i.e., starts with a
209 `/`). Relative paths are not supported. If the repo you gave is a local 209 `/`). Relative paths are not supported. If the repo you gave is a local
210 directory path, then it is not necessary that this path is a git repo. Please 210 directory path, then it is not necessary that this path is a git repo. Please
211 refer to the notes on `--no-local-clone` below. 211 refer to the notes on `--no-local-clone` below.
212 212
213 This command can also be used from your shell environment. This allows you to 213 This command can also be used from your shell environment. This allows you to
214 install plugins on the fly and try them out. Of course if you want a bundle to 214 install plugins on the fly and try them out. Of course if you want a bundle to
215 be available every time you open a shell, put it in your `.zshrc`. 215 be available every time you open a shell, put it in your `.zshrc`.
216 216
217 Other keyword-only arguments accepted: 217 Other keyword-only arguments accepted:
218 218
219 `--branch={git-branch-name}` &mdash; Specify the branch of the git repo to be 219 `--branch={git-branch-name}` &mdash; Specify the branch of the git repo to be
220 used for this bundle (without the braces of course). The default is whatever 220 used for this bundle (without the braces of course). The default is whatever
221 branch the clone comes with, which is usually `master`. For example, 221 branch the clone comes with, which is usually `master`. For example,
222 222
223 antigen-bundle github-user/repo --branch=develop 223 antigen-bundle github-user/repo --branch=develop
224 224
225 This will get the plugin as in the branch `develop`. 225 This will get the plugin as in the branch `develop`.
226 226
227 Note that if you specify two plugins to be loaded from the same git repo, but 227 Note that if you specify two plugins to be loaded from the same git repo, but
228 different branches, then two separate clones of this repo will be maintained. 228 different branches, then two separate clones of this repo will be maintained.
229 This is a small implementation detail and shouldn't influence you in any way. 229 This is a small implementation detail and shouldn't influence you in any way.
230 230
231 `--no-local-clone` &mdash; This command can be useful if you are developing a 231 `--no-local-clone` &mdash; This command can be useful if you are developing a
232 plugin and already have a clone on your local file system. If this argument is 232 plugin and already have a clone on your local file system. If this argument is
233 not given, even if the given repo url is a local path, a clone is made in the 233 not given, even if the given repo url is a local path, a clone is made in the
234 `$ADOTDIR/repos`, and the plugin is loaded from that clone. But, if you give 234 `$ADOTDIR/repos`, and the plugin is loaded from that clone. But, if you give
235 this argument, the plugin is sourced straight from the repo location, without 235 this argument, the plugin is sourced straight from the repo location, without
236 creating a clone. For example, 236 creating a clone. For example,
237 237
238 antigen-bundle /absolute/path/to/the/plugin --no-local-clone 238 antigen-bundle /absolute/path/to/the/plugin --no-local-clone
239 239
240 Note that if the repo url is *not* an absolute local path or a branch has been 240 Note that if the repo url is *not* an absolute local path or a branch has been
241 specified with the `--branch` option, this argument has no effect. That is, 241 specified with the `--branch` option, this argument has no effect. That is,
242 for this option to have any affect, the repo url must be an absolute local path 242 for this option to have any affect, the repo url must be an absolute local path
243 and no `--branch` should be specified. 243 and no `--branch` should be specified.
244 244
245 Also, if the local path given as the url is not a git repo, then this 245 Also, if the local path given as the url is not a git repo, then this
246 argument is forced as it doesn't makes sense to *clone* something that's not a 246 argument is forced as it doesn't makes sense to *clone* something that's not a
247 git repo. This property can be used to load any utility scripts you have in your 247 git repo. This property can be used to load any utility scripts you have in your
248 dotfiles repo. For example, 248 dotfiles repo. For example,
249 249
250 antigen-bundle $HOME/dotfiles/oh-my-zsh/custom 250 antigen-bundle $HOME/dotfiles/oh-my-zsh/custom
251 251
252 In addition to the above discussed arguments, `antigen-bundle` also takes a 252 In addition to the above discussed arguments, `antigen-bundle` also takes a
253 `btype` keyword-only argument, that is used internally. You shouldn't be 253 `btype` keyword-only argument, that is used internally. You shouldn't be
254 concerned with this argument, its only used internally and will probably go away 254 concerned with this argument, its only used internally and will probably go away
255 in the future. It indicates whether the bundle is a theme or a simple plugin. 255 in the future. It indicates whether the bundle is a theme or a simple plugin.
256 256
257 ### antigen-bundles 257 ### antigen-bundles
258 258
259 If you have a fair number of bundles, using the `antigen-bundle` command can 259 If you have a fair number of bundles, using the `antigen-bundle` command can
260 look cumbersome. You can use the `antigen-bundles` command to *bulk* define 260 look cumbersome. You can use the `antigen-bundles` command to *bulk* define
261 bundles instead of individual calls to `antigen-bundle`. 261 bundles instead of individual calls to `antigen-bundle`.
262 262
263 Usage is pretty straightforward. Just pipe the bundle specifications, just as 263 Usage is pretty straightforward. Just pipe the bundle specifications, just as
264 you would give to the `antigen-bundle` command, one per line, into the 264 you would give to the `antigen-bundle` command, one per line, into the
265 `antigen-bundles` command. The easiest way to do this, is using the heredoc 265 `antigen-bundles` command. The easiest way to do this, is using the heredoc
266 syntax. 266 syntax.
267 267
268 antigen-bundles <<EOBUNDLES 268 antigen-bundles <<EOBUNDLES
269 # Guess what to install when running an unknown command. 269 # Guess what to install when running an unknown command.
270 command-not-found 270 command-not-found
271 271
272 # The heroku tool helper plugin. 272 # The heroku tool helper plugin.
273 heroku 273 heroku
274 274
275 EOBUNDLES 275 EOBUNDLES
276 276
277 This is equivalent to 277 This is equivalent to
278 278
279 antigen-bundle command-not-found 279 antigen-bundle command-not-found
280 antigen-bundle heroku 280 antigen-bundle heroku
281 281
282 Of course, as you can see, from the lines piped to `antigen-bundles`, empty 282 Of course, as you can see, from the lines piped to `antigen-bundles`, empty
283 lines and those starting with a `#` are ignored. The rest are passed to 283 lines and those starting with a `#` are ignored. The rest are passed to
284 `antigen-bundle` without any quoting rules applied. They are actually `eval`-ed 284 `antigen-bundle` without any quoting rules applied. They are actually `eval`-ed
285 with the `antigen-bundle` command. See the source if you want to really 285 with the `antigen-bundle` command. See the source if you want to really
286 understand how it works. Its a very small function. 286 understand how it works. Its a very small function.
287 287
288 ### antigen-update 288 ### antigen-update
289 289
290 This is something you might not want to put in your `.zshrc`. Instead, run it 290 This is something you might not want to put in your `.zshrc`. Instead, run it
291 occasionally to update all your plugins. It doesn't take any arguments. 291 occasionally to update all your plugins. It doesn't take any arguments.
292 292
293 antigen-update 293 antigen-update
294 294
295 Please note that the updates that are downloaded are not immediately available. 295 Please note that the updates that are downloaded are not immediately available.
296 You have to open a new shell to be able to see the changes. This is a limitation 296 You have to open a new shell to be able to see the changes. This is a limitation
297 by design since reloading all the plugins *might* have some nasty side effects 297 by design since reloading all the plugins *might* have some nasty side effects
298 that may not be immediately apparent. Let's just say it can make your shell act 298 that may not be immediately apparent. Let's just say it can make your shell act
299 real quirky. 299 real quirky.
300 300
301 **Please note**: This command is not for updating *antigen* itself. Its for 301 **Please note**: This command is not for updating *antigen* itself. Its for
302 updating the bundles you are using with antigen. 302 updating the bundles you are using with antigen.
303 303
304 ### antigen-list 304 ### antigen-list
305 305
306 Use this command to list out the currently *loaded* plugins. Keep in mind that 306 Use this command to list out the currently *loaded* plugins. Keep in mind that
307 this includes any bundles installed on-the-fly. 307 this includes any bundles installed on-the-fly.
308 308
309 Takes no arguments. Gives out four entries per line of output, denoting the 309 Takes no arguments. Gives out four entries per line of output, denoting the
310 following fields of each bundle. 310 following fields of each bundle.
311 311
312 <repo-url> <loc> <btype> <has-local-clone?> 312 <repo-url> <loc> <btype> <has-local-clone?>
313 313
314 The `btype` field is an internal detail, that specifies if the bundle is a 314 The `btype` field is an internal detail, that specifies if the bundle is a
315 `plugin` or a `theme`. 315 `plugin` or a `theme`.
316 316
317 The final field is `true` or `false` reflecting whether there is a local clone 317 The final field is `true` or `false` reflecting whether there is a local clone
318 for this bundle. 318 for this bundle.
319 319
320 ### antigen-cleanup 320 ### antigen-cleanup
321 321
322 Used to clean up the clones of repos which are not used by any plugins currently 322 Used to clean up the clones of repos which are not used by any plugins currently
323 loaded. It takes no arguments. When run, it lists out the repo-clones that are 323 loaded. It takes no arguments. When run, it lists out the repo-clones that are
324 available but are not used by any plugin *currently loaded*. 324 available but are not used by any plugin *currently loaded*.
325 325
326 This command, by default asks for confirmation before deleting the unused 326 This command, by default asks for confirmation before deleting the unused
327 clones. If the `--force` argument is given, then this confirmation is not asked. 327 clones. If the `--force` argument is given, then this confirmation is not asked.
328 It straight away deletes all the unused clones. This option makes this command 328 It straight away deletes all the unused clones. This option makes this command
329 usable in a non-interactive fashion. 329 usable in a non-interactive fashion.
330 330
331 ### antigen-lib 331 ### antigen-lib
332 332
333 This is a shortcut to 333 This is a shortcut to
334 334
335 antigen-bundle --loc=lib 335 antigen-bundle --loc=lib
336 336
337 So, it basically installs the oh-my-zsh's library as a bundle. 337 So, it basically installs the oh-my-zsh's library as a bundle.
338 338
339 Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the 339 Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the
340 oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too, 340 oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too,
341 then you can't use the `antigen-lib` short cut. You have to do that directly 341 then you can't use the `antigen-lib` short cut. You have to do that directly
342 with the `antigen-bundle` command. 342 with the `antigen-bundle` command.
343 343
344 This is present only for legacy reasons and *might* (or might not) be removed in 344 This is present only for legacy reasons and *might* (or might not) be removed in
345 the future. 345 the future.
346 346
347 Use 347 Use
348 348
349 antigen-lib 349 antigen-lib
350 350
351 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no 351 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no
352 arguments. 352 arguments.
353 353
354 ### antigen-theme 354 ### antigen-theme
355 355
356 Used for switching the prompt theme. Invoke it with the name of the theme you 356 Used for switching the prompt theme. Invoke it with the name of the theme you
357 want to use. 357 want to use.
358 358
359 antigen-theme fox 359 antigen-theme fox
360 360
361 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 361 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
362 support getting themes from other repos as well in the future. 362 support getting themes from other repos as well in the future.
363 363
364 You can use this command to change your theme on the fly in your shell. Go on, 364 You can use this command to change your theme on the fly in your shell. Go on,
365 try out a few themes in your shell before you set it in your `.zshrc`. 365 try out a few themes in your shell before you set it in your `.zshrc`.
366 366
367 **Note**: Some themes use functions that are loaded by `antigen-lib`. So, to 367 **Note**: Some themes use functions that are loaded by `antigen-lib`. So, to
368 avoid any trouble, run `antigen-lib` if you haven't already before experimenting 368 avoid any trouble, run `antigen-lib` if you haven't already before experimenting
369 with themes. If you have `antigen-lib` in your `.zshrc`, you're covered. 369 with themes. If you have `antigen-lib` in your `.zshrc`, you're covered.
370 370
371 ### antigen-apply 371 ### antigen-apply
372 372
373 You have to add this command after defining all bundles you need, in your zshrc. 373 You have to add this command after defining all bundles you need, in your zshrc.
374 The completions defined by your bundles will be loaded at this step. 374 The completions defined by your bundles will be loaded at this step.
375 375
376 It is possible to load completions as and when a bundle is specified with the 376 It is possible to load completions as and when a bundle is specified with the
377 bundle command, in which case this command would not be necessary. But loading 377 bundle command, in which case this command would not be necessary. But loading
378 the completions is a time-consuming process, so if the completions were loaded 378 the completions is a time-consuming process, so if the completions were loaded
379 at every call to `antigen-bundle`, your shell will start noticeably slow when 379 at every call to `antigen-bundle`, your shell will start noticeably slow when
380 you have a good number of bundle specifications. 380 you have a good number of bundle specifications.
381 381
382 However, if you can suggest a way so that this would not be necessary, I am very 382 However, if you can suggest a way so that this would not be necessary, I am very
383 interested in discussing it. Please open up an issue with your details. Thanks. 383 interested in discussing it. Please open up an issue with your details. Thanks.
384 384
385 ### antigen-help 385 ### antigen-help
386 386
387 This exists so that there can be some help right in the command line. Currently 387 This exists so that there can be some help right in the command line. Currently
388 it doesn't provide much help other than redirecting you to the project page for 388 it doesn't provide much help other than redirecting you to the project page for
389 documentation. It is intended to provide more meaning and sub-command specific 389 documentation. It is intended to provide more meaning and sub-command specific
390 help in the future. 390 help in the future.
391 391
392 I could use some help here as I'm not that good at writing documentation that 392 I could use some help here as I'm not that good at writing documentation that
393 looks good as output on the command line. 393 looks good as output on the command line.
394 394
395 ### antigen 395 ### antigen
396 396
397 This is a parent command that mainly exists for convenience. This exists so the 397 This is a parent command that mainly exists for convenience. This exists so the
398 following two can be the same. 398 following two can be the same.
399 399
400 antigen-list 400 antigen-list
401 antigen list 401 antigen list
402 402
403 and 403 and
404 404
405 antigen-help 405 antigen-help
406 antigen help 406 antigen help
407 407
408 Because of this, we can create aliases like 408 Because of this, we can create aliases like
409 409
410 alias a=antigen 410 alias a=antigen
411 alias an=antigen 411 alias an=antigen
412 412
413 and run the antigen commands without making them look annoyingly long. 413 and run the antigen commands without making them look annoyingly long.
414 414
415 a bundle ruby 415 a bundle ruby
416 a theme candy 416 a theme candy
417 a list 417 a list
418 418
419 And even... 419 And even...
420 420
421 an update 421 an update
422 422
423 ## Configuration 423 ## Configuration
424 424
425 The following environment variables can be set to customize the behavior of 425 The following environment variables can be set to customize the behavior of
426 antigen. Make sure you set them *before* source-ing `antigen.zsh`. 426 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
427 427
428 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 428 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
429 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, 429 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
430 but you can set this to the fork url of your own fork. 430 but you can set this to the fork url of your own fork.
431 431
432 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your 432 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your
433 bundles, themes, caches and everything else antigen requires to run smoothly. 433 bundles, themes, caches and everything else antigen requires to run smoothly.
434 Defaults to `$HOME/.antigen`. 434 Defaults to `$HOME/.antigen`.
435 435
436 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables 436 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables
437 were used previously but are now removed. Please use `ADOTDIR` instead, as 437 were used previously but are now removed. Please use `ADOTDIR` instead, as
438 mentioned above. 438 mentioned above.
439 439
440 ## Running the tests 440 ## Running the tests
441 441
442 All the tests are in the `tests` folder and are run using the [cram][] test 442 All the tests are in the `tests` folder and are run using the [cram][] test
443 system. Once you have cram installed, you can run the tests as 443 system. Once you have cram installed, you can run the tests as
444 444
445 make 445 make
446 446
447 or 447 or
448 448
449 make tests 449 make tests
450 450
451 If you are making a feature addition, I'd really appreciate if you can add a 451 If you are making a feature addition, I'd really appreciate if you can add a
452 test for your feature. Even if you can add a test for an existing feature, that 452 test for your feature. Even if you can add a test for an existing feature, that
453 would be great as the tests are currently seriously lagging behind the full 453 would be great as the tests are currently seriously lagging behind the full
454 functionality of antigen. 454 functionality of antigen.
455 455
456 ## Notes on writing plugins 456 ## Notes on writing plugins
457 457
458 If you are just going to write a single `.sh` file with the goodness you want to 458 If you are just going to write a single `.sh` file with the goodness you want to
459 create, just forget about this and go do that. Antigen will work just fine with 459 create, just forget about this and go do that. Antigen will work just fine with
460 such a plugin. 460 such a plugin.
461 461
462 If you want to know how antigen loads the plugins, do continue. 462 If you want to know how antigen loads the plugins, do continue.
463 463
464 Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If 464 Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If
465 present, it will source *only* this script. Nothing else is sourced. 465 present, it will source *only* this script. Nothing else is sourced.
466 466
467 Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are 467 Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are
468 sourced. The order in which they are sourced is not currently defined. Please 468 sourced. The order in which they are sourced is not currently defined. Please
469 don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts. 469 don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.
470 470
471 If no `*.zsh` files are present, it finally looks for any `*.sh` files and 471 If no `*.zsh` files are present, it finally looks for any `*.sh` files and
472 sources *all* of them. Again, the order in which they are sourced in not 472 sources *all* of them. Again, the order in which they are sourced in not
473 currently defined. 473 currently defined.
474 474
475 No matter which (or none) of the above happen to be sourced, this plugin 475 No matter which (or none) of the above happen to be sourced, this plugin
476 directory is added to the zsh's function path (`$fpath`) so that any completions 476 directory is added to the zsh's function path (`$fpath`) so that any completions
477 in it are loaded. 477 in it are loaded.
478 478
479 One exception to this rule is that if this plugin is a theme. In which case the 479 One exception to this rule is that if this plugin is a theme. In which case the
480 theme script is just sourced and nothing else is done. Not even adding to 480 theme script is just sourced and nothing else is done. Not even adding to
481 `$fpath`. 481 `$fpath`.
482 482
483 ## Meta 483 ## Meta
484 484
485 ### Helping out 485 ### Helping out
486 486
487 Antigen is licensed with the [MIT License][license]. To contribute, just fork, 487 Antigen is licensed with the [MIT License][license]. To contribute, just fork,
488 make changes and send a pull request. If its a rather long/complicated change, 488 make changes and send a pull request. If its a rather long/complicated change,
489 please consider opening an [issue][] first so we can discuss it out. 489 please consider opening an [issue][] first so we can discuss it out.
490 490
491 ### Feedback please 491 ### Feedback please
492 492
493 Any comments/suggestions/feedback welcome. Please join the discussion on the 493 Any comments/suggestions/feedback welcome. Please join the discussion on the
494 [reddit page][] of this project. Also, follow me on twitter, 494 [reddit page][] of this project. Also, follow me on twitter,
495 [@sharat87][twitter]. 495 [@sharat87][twitter].
496 496
497 [Vundle]: https://github.com/gmarik/vundle 497 [Vundle]: https://github.com/gmarik/vundle
498 [page on themes]: https://github.com/robbyrussell/oh-my-zsh/wiki/Themes 498 [page on themes]: https://github.com/robbyrussell/oh-my-zsh/wiki/Themes
499 [syntax highlighting plugin]: https://github.com/zsh-users/zsh-syntax-highlighting 499 [syntax highlighting plugin]: https://github.com/zsh-users/zsh-syntax-highlighting
500 [autoenv]: https://github.com/kennethreitz/autoenv 500 [autoenv]: https://github.com/kennethreitz/autoenv
501 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 501 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
502 [cram]: https://bitheap.org/cram/ 502 [cram]: https://bitheap.org/cram/
503 [issue]: https://github.com/sharat87/antigen/issues 503 [issue]: https://github.com/zsh-users/antigen/issues
504 [license]: http://mit.sharats.me 504 [license]: http://mit.sharats.me
505 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ 505 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
506 [twitter]: http://twitter.com/sharat87 506 [twitter]: http://twitter.com/sharat87
507 507