mj / zsh-config

Download as
Browse Code ยป

Commit 149b3e8f1d8b32402a68d5954f0924a3fef24e8a

Authored by Guilherme Espada
1 parent ec7f137bb1

Update the README further with more theme goodness

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

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