mj / zsh-config

Download as
Browse Code ยป

Commit e0d9cfa43f610a385a46ee28fc97f581bee88bc7

Authored by Shrikant Sharat
1 parent c0632ccd53

Typo in command in README. Fix #45.

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