mj / zsh-config

Download as
Browse Code ยป

Commit 8f0e534f1911addcd4ae85c02fa7e0c8602d53dd

Authored by Shrikant Sharat
1 parent de8d00ed42

Added 'Show off' section to README.

Showing 1 changed file with 57 additions and 1 deletions Inline Diff

1 # Antigen 1 # Antigen
2 2
3 Antigen is a small set of functions that help you easily manage your shell (zsh) 3 Antigen is a small set of functions that help you easily manage your shell (zsh)
4 plugins, called bundles. The concept is pretty much the same as bundles in a 4 plugins, called bundles. The concept is pretty much the same as bundles in a
5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim. 5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.
6 6
7 **Please** note that antigen is currently is alpha stage and will have backwards 7 **Please** note that antigen is currently is alpha stage and will have backwards
8 incompatible changes now and then, until we have a pretty stable system we can 8 incompatible changes now and then, until we have a pretty stable system we can
9 reason about. **Please** read the commit comments of the changesets when you 9 reason about. **Please** read the commit comments of the changesets when you
10 pull a new version of antigen. 10 pull a new version of antigen.
11 11
12 # Quick Usage 12 # Show off
13
14 > Enough talk. Let's fight!
15 > -- Po, Kung-fu Panda.
16
17 You're going to experience antigen right in your open shell. No `.zshrc`
18 tweaking and reading the rest of this documentation. Kinda like an ice-cream
19 sample, if you will.
20
21 Get and load antigen.
22
23 curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh
24 source antigen.zsh
25
26 There. You now have all the antigen goodies. Let's try install some plugins. How
27 about some color to start with. Get the syntax highlighting plugin by running
28
29 antigen-bundle zsh-users/zsh-syntax-highlighting
30
31 Now let it do its thing and once its done and you're back at your prompt, try
32 and type a command. See that? Colors!
33
34 So, you do git? ruby? git and ruby? There are lots of awesome plugins over at
35 oh-my-zsh. Treat yourself to some.
36
37 antigen-bundle robbyrussell/oh-my-zsh plugins/ruby
38 antigen-bundle robbyrussell/oh-my-zsh plugins/git
39
40 There are lots of plugins out there in the wild and people are writing zsh
41 utilities as small scripts all the time. Antigen is compatible with all of them.
42 The plugins and scripts don't need any special handling to be compatible with
43 antigen.
44
45 The side effect of this is that you can tell antigen to grab just about anything
46 from anyone's `dotfiles` repo, as long as it is in a directory under any repo on
47 github.
48
49 And themes? How would you like a fancy new prompt for yourself?
50
51 antigen-theme funky
52
53 No? Not your taste? There are many themes available to you, check out the
54 oh-my-zsh's page on themes. (You can currently only install themes from
55 robbyrussell's, i.e., the canonical oh-my-zsh repo).
56
57 Note: Many of those plugins and especially themes, assume you have the core
58 library of oh-my-zsh loaded. So, if you want to experiment further, issue a
59
60 antigen-lib
61
62 and continue until you're tired. At which point you can come back to this page
63 ;)
64
65 # Usage
66
67 So, now that you're here, I'll assume you are convinced and want antigen running
68 your shell all the time. Sweet. Let's do it.
13 69
14 First, clone this repo, probably as a submodule if you have your dotfiles in a 70 First, clone this repo, probably as a submodule if you have your dotfiles in a
15 git repo, 71 git repo,
16 72
17 git clone https://github.com/sharat87/antigen.git 73 git clone https://github.com/sharat87/antigen.git
18 74
19 The usage should be very familiar to you if you use Vundle. A typical `.zshrc` 75 The usage should be very familiar to you if you use Vundle. A typical `.zshrc`
20 might look like this 76 might look like this
21 77
22 source /path-to-antigen-clone/antigen.zsh 78 source /path-to-antigen-clone/antigen.zsh
23 79
24 # Load the oh-my-zsh's library. 80 # Load the oh-my-zsh's library.
25 antigen-lib 81 antigen-lib
26 82
27 # Bundles from the default repo (robbyrussell's oh-my-zsh). 83 # Bundles from the default repo (robbyrussell's oh-my-zsh).
28 antigen-bundle git 84 antigen-bundle git
29 antigen-bundle heroku 85 antigen-bundle heroku
30 antigen-bundle pip 86 antigen-bundle pip
31 antigen-bundle lein 87 antigen-bundle lein
32 antigen-bundle command-not-found 88 antigen-bundle command-not-found
33 89
34 # Syntax highlighting bundle. 90 # Syntax highlighting bundle.
35 antigen-bundle zsh-users/zsh-syntax-highlighting 91 antigen-bundle zsh-users/zsh-syntax-highlighting
36 92
37 # Load the theme. 93 # Load the theme.
38 antigen-theme robbyrussell 94 antigen-theme robbyrussell
39 95
40 # Tell antigen that you're done. 96 # Tell antigen that you're done.
41 antigen-apply 97 antigen-apply
42 98
43 Open your zsh with this zshrc and you should see all the bundles you defined 99 Open your zsh with this zshrc and you should see all the bundles you defined
44 here, getting installed. Once its done, you are ready to roll. The complete 100 here, getting installed. Once its done, you are ready to roll. The complete
45 syntax for the `antigen-bundle` command is discussed further down on this page. 101 syntax for the `antigen-bundle` command is discussed further down on this page.
46 102
47 # Motivation 103 # Motivation
48 104
49 If you use zsh and [oh-my-zsh][], you know that having many different plugins 105 If you use zsh and [oh-my-zsh][], you know that having many different plugins
50 that are developed by many different authors in a single (sub)repo is not a very 106 that are developed by many different authors in a single (sub)repo is not a very
51 easy to maintain. There are some really fantastic plugins and utilities in 107 easy to maintain. There are some really fantastic plugins and utilities in
52 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I 108 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I
53 admire robbyrussell's efforts for reviewing and merging the gigantic number of 109 admire robbyrussell's efforts for reviewing and merging the gigantic number of
54 pull requests the project gets. It needs a better way of plugin management. 110 pull requests the project gets. It needs a better way of plugin management.
55 111
56 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like 112 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
57 there was any progress made. So, I'm trying to start this off with antigen, 113 there was any progress made. So, I'm trying to start this off with antigen,
58 hoping to better this situation. Please note that I'm by no means a zsh or any 114 hoping to better this situation. Please note that I'm by no means a zsh or any
59 shell script expert (far from it). 115 shell script expert (far from it).
60 116
61 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 117 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
62 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 118 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
63 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 119 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
64 120
65 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github 121 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github
66 repositories. You are not limited to use plugins from the oh-my-zsh repository 122 repositories. You are not limited to use plugins from the oh-my-zsh repository
67 only and you don't need to maintain your own fork and pull from upstream every 123 only and you don't need to maintain your own fork and pull from upstream every
68 now and then. 124 now and then.
69 125
70 Antigen also lets you switch the prompt theme with one command, just like that 126 Antigen also lets you switch the prompt theme with one command, just like that
71 127
72 bundle-theme candy 128 bundle-theme candy
73 129
74 and your prompt is changed, just for this session of course. 130 and your prompt is changed, just for this session of course.
75 131
76 # Commands 132 # Commands
77 133
78 ## antigen-bundle 134 ## antigen-bundle
79 135
80 This command tells antigen to install (if not already installed) and load the 136 This command tells antigen to install (if not already installed) and load the
81 given plugin. The simplest usage follows the following syntax. 137 given plugin. The simplest usage follows the following syntax.
82 138
83 antigen-bundle <plugin-name> 139 antigen-bundle <plugin-name>
84 140
85 This will install the `plugins/<name>` directory from [robbyrussell's 141 This will install the `plugins/<name>` directory from [robbyrussell's
86 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`). 142 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
87 143
88 However, the above is just syntax sugar for the extended syntax of the 144 However, the above is just syntax sugar for the extended syntax of the
89 `antigen-bundle` command. 145 `antigen-bundle` command.
90 146
91 antigen-bundle [<url> [<loc>]] 147 antigen-bundle [<url> [<loc>]]
92 148
93 where `<url>` is the repository url and it defaults to [robbyrussell's 149 where `<url>` is the repository url and it defaults to [robbyrussell's
94 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL` 150 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`
95 discussed further down). `<loc>` is the path under this repository which has the 151 discussed further down). `<loc>` is the path under this repository which has the
96 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file, 152 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,
97 but it could contain a completion file or just many `*.zsh` files to be sourced. 153 but it could contain a completion file or just many `*.zsh` files to be sourced.
98 `<loc>` defaults to `/`, which indicates the repository itself is a plugin. 154 `<loc>` defaults to `/`, which indicates the repository itself is a plugin.
99 155
100 An example invocation would be 156 An example invocation would be
101 157
102 # The following is the same as `antigen-bundle ant`. But for demonstration 158 # The following is the same as `antigen-bundle ant`. But for demonstration
103 # purposes, we use the extended syntax here. 159 # purposes, we use the extended syntax here.
104 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 160 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
105 161
106 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course, 162 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
107 github url's can be shortened. 163 github url's can be shortened.
108 164
109 antigen-bundle robbyrussell/oh-my-zsh plugins/ant 165 antigen-bundle robbyrussell/oh-my-zsh plugins/ant
110 166
111 And since this repo is the default, even that isn't necessary. But we can't 167 And since this repo is the default, even that isn't necessary. But we can't
112 specify the `loc` without giving the first argument. 168 specify the `loc` without giving the first argument.
113 169
114 For this and a few other reasons, `antigen-bundle` also supports a simple 170 For this and a few other reasons, `antigen-bundle` also supports a simple
115 keyword argument syntax, using which we can rewrite the above as 171 keyword argument syntax, using which we can rewrite the above as
116 172
117 antigen-bundle --loc=plugins/ant 173 antigen-bundle --loc=plugins/ant
118 174
119 Which picks up the default for the `url` argument, and uses the `loc` given to 175 Which picks up the default for the `url` argument, and uses the `loc` given to
120 it. 176 it.
121 177
122 *Note* that you can mix and match positional and keyword arguments. But you 178 *Note* that you can mix and match positional and keyword arguments. But you
123 can't have positional arguments after keyword arguments. 179 can't have positional arguments after keyword arguments.
124 180
125 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant 181 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant
126 182
127 And keyword arguments don't care about the order in which the arguments are 183 And keyword arguments don't care about the order in which the arguments are
128 specified. The following is perfectly valid. 184 specified. The following is perfectly valid.
129 185
130 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh 186 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
131 187
132 In addition to the above discussed arguments, `antigen-bundle` also takes a 188 In addition to the above discussed arguments, `antigen-bundle` also takes a
133 `btype` keyword-only argument, that is used internally. You shouldn't be 189 `btype` keyword-only argument, that is used internally. You shouldn't be
134 concerned with this argument, its only used internally and will probably go away 190 concerned with this argument, its only used internally and will probably go away
135 in the future. It indicates whether the bundle is a theme or a simple plugin. 191 in the future. It indicates whether the bundle is a theme or a simple plugin.
136 192
137 You can use this `antigen-bundle` command not just from your `.zshrc`, but also 193 You can use this `antigen-bundle` command not just from your `.zshrc`, but also
138 from your shell environment. This allows you to install plugins on the fly and 194 from your shell environment. This allows you to install plugins on the fly and
139 try them out. Of course if you want a bundle to be available every time you open 195 try them out. Of course if you want a bundle to be available every time you open
140 a shell, put it in your `.zshrc`. 196 a shell, put it in your `.zshrc`.
141 197
142 ## antigen-bundles 198 ## antigen-bundles
143 199
144 If you have a fair number of bundles, using the `antigen-bundle` command can 200 If you have a fair number of bundles, using the `antigen-bundle` command can
145 look cumbersome. You can use the `antigen-bundles` command to *bulk* define 201 look cumbersome. You can use the `antigen-bundles` command to *bulk* define
146 bundles instead of individual calls to `antigen-bundle`. 202 bundles instead of individual calls to `antigen-bundle`.
147 203
148 Usage is pretty straightforward. Just pipe the bundle specifications, just as 204 Usage is pretty straightforward. Just pipe the bundle specifications, just as
149 you would give to the `antigen-bundle` command, one per line, into the 205 you would give to the `antigen-bundle` command, one per line, into the
150 `antigen-bundles` command. The easiest way to do this, is using the heredoc 206 `antigen-bundles` command. The easiest way to do this, is using the heredoc
151 syntax. 207 syntax.
152 208
153 antigen-bundles <<EOF 209 antigen-bundles <<EOF
154 # Guess what to install when running an unknown command. 210 # Guess what to install when running an unknown command.
155 command-not-found 211 command-not-found
156 212
157 # The heroku tool helper plugin. 213 # The heroku tool helper plugin.
158 heroku 214 heroku
159 215
160 EOF 216 EOF
161 217
162 This is equivalent to 218 This is equivalent to
163 219
164 antigen-bundle command-not-found 220 antigen-bundle command-not-found
165 antigen-bundle heroku 221 antigen-bundle heroku
166 222
167 Of course, as you can see, from the lines piped to `antigen-bundles`, empty 223 Of course, as you can see, from the lines piped to `antigen-bundles`, empty
168 lines and those starting with a `#` are ignored. The rest are passed to 224 lines and those starting with a `#` are ignored. The rest are passed to
169 `antigen-bundle` without any quoting rules applied. They are actually `eval`-ed 225 `antigen-bundle` without any quoting rules applied. They are actually `eval`-ed
170 with the `antigen-bundle` command. See the source if you want to really 226 with the `antigen-bundle` command. See the source if you want to really
171 understand how it works. Its a very small function. 227 understand how it works. Its a very small function.
172 228
173 ## antigen-update 229 ## antigen-update
174 230
175 This is something you might not want to put in your `.zshrc`. Instead, run it 231 This is something you might not want to put in your `.zshrc`. Instead, run it
176 occasionally to update all your plugins. It doesn't take any arguments. 232 occasionally to update all your plugins. It doesn't take any arguments.
177 233
178 antigen-update 234 antigen-update
179 235
180 Please note that the updates that are downloaded are not immediately available. 236 Please note that the updates that are downloaded are not immediately available.
181 You have to open a new shell to be able to see the changes. This is a limitation 237 You have to open a new shell to be able to see the changes. This is a limitation
182 by design since reloading all the plugins *might* have some nasty side effects 238 by design since reloading all the plugins *might* have some nasty side effects
183 that may not be immediately apparent. Let's just say it can make your shell act 239 that may not be immediately apparent. Let's just say it can make your shell act
184 real quirky. 240 real quirky.
185 241
186 **Please note**: This command is not for updating *antigen* itself. Its for 242 **Please note**: This command is not for updating *antigen* itself. Its for
187 updating the bundles you are using with antigen. 243 updating the bundles you are using with antigen.
188 244
189 ## antigen-list 245 ## antigen-list
190 246
191 Use this command to list out the currently *loaded* plugins. Keep in mind that 247 Use this command to list out the currently *loaded* plugins. Keep in mind that
192 this includes any bundles installed on-the-fly. 248 this includes any bundles installed on-the-fly.
193 249
194 Takes no arguments. Gives out the repo url and the plugin's location under the 250 Takes no arguments. Gives out the repo url and the plugin's location under the
195 repo. 251 repo.
196 252
197 ## antigen-cleanup 253 ## antigen-cleanup
198 254
199 Used to clean up the clones of repos which are not used by any plugins. It takes 255 Used to clean up the clones of repos which are not used by any plugins. It takes
200 no arguments. When this is run, it lists out the repo-clones that are available 256 no arguments. When this is run, it lists out the repo-clones that are available
201 but are not used by any plugin *currently loaded*. 257 but are not used by any plugin *currently loaded*.
202 258
203 This command currently cannot run in a non-interactive mode. So it won't be very 259 This command currently cannot run in a non-interactive mode. So it won't be very
204 pleasant to use it in your `.zshrc`. 260 pleasant to use it in your `.zshrc`.
205 261
206 ## antigen-lib 262 ## antigen-lib
207 263
208 This is a shortcut to 264 This is a shortcut to
209 265
210 antigen-bundle --loc=lib 266 antigen-bundle --loc=lib
211 267
212 So, it basically installs the oh-my-zsh's library as a bundle. Please note that 268 So, it basically installs the oh-my-zsh's library as a bundle. Please note that
213 this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the oh-my-zsh repo or 269 this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the oh-my-zsh repo or
214 a fork of that repo. If you want to specify the `url` too, then you can't use 270 a fork of that repo. If you want to specify the `url` too, then you can't use
215 the `antigen-lib` short cut. You have to do that directly with the 271 the `antigen-lib` short cut. You have to do that directly with the
216 `antigen-bundle` command. 272 `antigen-bundle` command.
217 273
218 This is present only for legacy reasons and *might* (or might not) be removed in 274 This is present only for legacy reasons and *might* (or might not) be removed in
219 the future. 275 the future.
220 276
221 Use 277 Use
222 278
223 antigen-lib 279 antigen-lib
224 280
225 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no 281 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no
226 arguments. 282 arguments.
227 283
228 ## antigen-theme 284 ## antigen-theme
229 285
230 Used for switching the prompt theme. Invoke it with the name of the theme you 286 Used for switching the prompt theme. Invoke it with the name of the theme you
231 want to use. 287 want to use.
232 288
233 antigen-theme fox 289 antigen-theme fox
234 290
235 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 291 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
236 support getting themes from other repos as well in the future. 292 support getting themes from other repos as well in the future.
237 293
238 You can use this command to change your theme on the fly in your shell. Go on, 294 You can use this command to change your theme on the fly in your shell. Go on,
239 try out a few themes in your shell before you set it in your `.zshrc`. 295 try out a few themes in your shell before you set it in your `.zshrc`.
240 296
241 ## antigen-apply 297 ## antigen-apply
242 298
243 You have to add this command after defining all bundles you need, in your zshrc. 299 You have to add this command after defining all bundles you need, in your zshrc.
244 The completions defined by your bundles will be loaded at this step. 300 The completions defined by your bundles will be loaded at this step.
245 301
246 It is possible to load completions as and when a bundle is specified with the 302 It is possible to load completions as and when a bundle is specified with the
247 bundle command, in which case this command would not be necessary. But loading 303 bundle command, in which case this command would not be necessary. But loading
248 the completions is a time-consuming process and your shell will start noticeably 304 the completions is a time-consuming process and your shell will start noticeably
249 slow if you have a good number of bundle specifications. 305 slow if you have a good number of bundle specifications.
250 306
251 However, if you're a zsh expert and can suggest a way so that this would not be 307 However, if you're a zsh expert and can suggest a way so that this would not be
252 necessary, I am very interested in discussing it. Please open up an issue with 308 necessary, I am very interested in discussing it. Please open up an issue with
253 your details. Thanks. 309 your details. Thanks.
254 310
255 # Configuration 311 # Configuration
256 312
257 The following environment variables can be set to customize the behavior of 313 The following environment variables can be set to customize the behavior of
258 antigen. Make sure you set them *before* source-ing `antigen.zsh`. 314 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
259 315
260 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 316 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
261 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, 317 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
262 but you can set this to the fork url of your own fork. 318 but you can set this to the fork url of your own fork.
263 319
264 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your 320 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your
265 bundles, themes, caches and everything else antigen requires to run smoothly. 321 bundles, themes, caches and everything else antigen requires to run smoothly.
266 Defaults to `$HOME/.antigen`. 322 Defaults to `$HOME/.antigen`.
267 323
268 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables 324 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables
269 were used previously but are now removed. Please use `ADOTDIR` instead, as 325 were used previously but are now removed. Please use `ADOTDIR` instead, as
270 mentioned above. 326 mentioned above.
271 327
272 # Meta 328 # Meta
273 329
274 Project is licensed with the [MIT License][license]. To contribute, just fork, 330 Project is licensed with the [MIT License][license]. To contribute, just fork,
275 make changes and send a pull request. If its a rather long/complicated change, 331 make changes and send a pull request. If its a rather long/complicated change,
276 please consider opening an [issue][] first so we can discuss it out. 332 please consider opening an [issue][] first so we can discuss it out.
277 333
278 Any comments/suggestions/feedback welcome. Please join the discussion on the 334 Any comments/suggestions/feedback welcome. Please join the discussion on the
279 [reddit page][] of this project. Also, follow me on twitter, 335 [reddit page][] of this project. Also, follow me on twitter,
280 [@sharat87](twitter). 336 [@sharat87](twitter).
281 337
282 [Vundle]: https://github.com/gmarik/vundle 338 [Vundle]: https://github.com/gmarik/vundle
283 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 339 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
284 [issue]: https://github.com/sharat87/antigen/issues 340 [issue]: https://github.com/sharat87/antigen/issues
285 [license]: http://mit.sharats.me 341 [license]: http://mit.sharats.me
286 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ 342 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
287 [twitter]: http://twitter.com/sharat87 343 [twitter]: http://twitter.com/sharat87
288 344