mj / zsh-config

Download as
Browse Code ยป

Commit 6e2c0fbd625123a04bf91f1f681c3facd40c0156

Authored by Shrikant Sharat
1 parent c3198e0aa0

Point autoenv example to my fork.

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