mj / zsh-config

Download as
Browse Code ยป

Commit e97773908d44328d6092f749c98ae65bd2b7e214

Authored by Shrikant Sharat
1 parent 0ba48e0fca

Added docs on using local paths with -bundle.

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