mj / zsh-config

Download as
Browse Code ยป

Commit ec7f137bb13f12127ced7a70736727a5724414ff

Authored by Shrikant Sharat
1 parent b6f10e7c7f

Add build status badge to README.

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