mj / zsh-config

Download as
Browse Code ยป

Commit 09665a0b5f1e3a80e4a21a19de0cc0b09a04c02e

Authored by Guilherme Espada
1 parent 149b3e8f1d

Add more info into the readme

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