mj / zsh-config

Download as
Browse Code ยป

Commit de8d00ed42d5aa3973bcd4ff3cb9d439a162be78

Authored by Shrikant Sharat
1 parent 78ea5a9f42

Use the new command naming in quick usage.

Showing 1 changed file with 10 additions and 10 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 # Quick Usage
13 13
14 First, clone this repo, probably as a submodule if you have your dotfiles in a 14 First, clone this repo, probably as a submodule if you have your dotfiles in a
15 git repo, 15 git repo,
16 16
17 git clone https://github.com/sharat87/antigen.git 17 git clone https://github.com/sharat87/antigen.git
18 18
19 The usage should be very familiar to you if you use Vundle. A typical `.zshrc` 19 The usage should be very familiar to you if you use Vundle. A typical `.zshrc`
20 might look like this 20 might look like this
21 21
22 source /path-to-antigen-clone/antigen.zsh 22 source /path-to-antigen-clone/antigen.zsh
23 23
24 # Load the oh-my-zsh's library. 24 # Load the oh-my-zsh's library.
25 bundle-lib 25 antigen-lib
26 26
27 # Bundles from the default repo (robbyrussell's oh-my-zsh). 27 # Bundles from the default repo (robbyrussell's oh-my-zsh).
28 bundle git 28 antigen-bundle git
29 bundle heroku 29 antigen-bundle heroku
30 bundle pip 30 antigen-bundle pip
31 bundle lein 31 antigen-bundle lein
32 bundle command-not-found 32 antigen-bundle command-not-found
33 33
34 # Syntax highlighting bundle. 34 # Syntax highlighting bundle.
35 bundle zsh-users/zsh-syntax-highlighting 35 antigen-bundle zsh-users/zsh-syntax-highlighting
36 36
37 # Load the theme. 37 # Load the theme.
38 bundle-theme robbyrussell 38 antigen-theme robbyrussell
39 39
40 # Tell antigen that you're done. 40 # Tell antigen that you're done.
41 bundle-apply 41 antigen-apply
42 42
43 Open your zsh with this zshrc and you should see all the bundles you defined 43 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 44 here, getting installed. Once its done, you are ready to roll. The complete
45 syntax for the `bundle` command is discussed further down on this page. 45 syntax for the `antigen-bundle` command is discussed further down on this page.
46 46
47 # Motivation 47 # Motivation
48 48
49 If you use zsh and [oh-my-zsh][], you know that having many different plugins 49 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 50 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 51 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 52 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 53 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. 54 pull requests the project gets. It needs a better way of plugin management.
55 55
56 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like 56 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, 57 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 58 hoping to better this situation. Please note that I'm by no means a zsh or any
59 shell script expert (far from it). 59 shell script expert (far from it).
60 60
61 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 61 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
62 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 62 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
63 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 63 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
64 64
65 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github 65 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 66 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 67 only and you don't need to maintain your own fork and pull from upstream every
68 now and then. 68 now and then.
69 69
70 Antigen also lets you switch the prompt theme with one command, just like that 70 Antigen also lets you switch the prompt theme with one command, just like that
71 71
72 bundle-theme candy 72 bundle-theme candy
73 73
74 and your prompt is changed, just for this session of course. 74 and your prompt is changed, just for this session of course.
75 75
76 # Commands 76 # Commands
77 77
78 ## antigen-bundle 78 ## antigen-bundle
79 79
80 This command tells antigen to install (if not already installed) and load the 80 This command tells antigen to install (if not already installed) and load the
81 given plugin. The simplest usage follows the following syntax. 81 given plugin. The simplest usage follows the following syntax.
82 82
83 antigen-bundle <plugin-name> 83 antigen-bundle <plugin-name>
84 84
85 This will install the `plugins/<name>` directory from [robbyrussell's 85 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`). 86 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
87 87
88 However, the above is just syntax sugar for the extended syntax of the 88 However, the above is just syntax sugar for the extended syntax of the
89 `antigen-bundle` command. 89 `antigen-bundle` command.
90 90
91 antigen-bundle [<url> [<loc>]] 91 antigen-bundle [<url> [<loc>]]
92 92
93 where `<url>` is the repository url and it defaults to [robbyrussell's 93 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` 94 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 95 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, 96 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. 97 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. 98 `<loc>` defaults to `/`, which indicates the repository itself is a plugin.
99 99
100 An example invocation would be 100 An example invocation would be
101 101
102 # The following is the same as `antigen-bundle ant`. But for demonstration 102 # The following is the same as `antigen-bundle ant`. But for demonstration
103 # purposes, we use the extended syntax here. 103 # purposes, we use the extended syntax here.
104 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 104 antigen-bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
105 105
106 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course, 106 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
107 github url's can be shortened. 107 github url's can be shortened.
108 108
109 antigen-bundle robbyrussell/oh-my-zsh plugins/ant 109 antigen-bundle robbyrussell/oh-my-zsh plugins/ant
110 110
111 And since this repo is the default, even that isn't necessary. But we can't 111 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. 112 specify the `loc` without giving the first argument.
113 113
114 For this and a few other reasons, `antigen-bundle` also supports a simple 114 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 115 keyword argument syntax, using which we can rewrite the above as
116 116
117 antigen-bundle --loc=plugins/ant 117 antigen-bundle --loc=plugins/ant
118 118
119 Which picks up the default for the `url` argument, and uses the `loc` given to 119 Which picks up the default for the `url` argument, and uses the `loc` given to
120 it. 120 it.
121 121
122 *Note* that you can mix and match positional and keyword arguments. But you 122 *Note* that you can mix and match positional and keyword arguments. But you
123 can't have positional arguments after keyword arguments. 123 can't have positional arguments after keyword arguments.
124 124
125 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant 125 antigen-bundle robbyrussell/oh-my-zsh --loc=plugins/ant
126 126
127 And keyword arguments don't care about the order in which the arguments are 127 And keyword arguments don't care about the order in which the arguments are
128 specified. The following is perfectly valid. 128 specified. The following is perfectly valid.
129 129
130 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh 130 antigen-bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
131 131
132 In addition to the above discussed arguments, `antigen-bundle` also takes a 132 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 133 `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 134 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. 135 in the future. It indicates whether the bundle is a theme or a simple plugin.
136 136
137 You can use this `antigen-bundle` command not just from your `.zshrc`, but also 137 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 138 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 139 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`. 140 a shell, put it in your `.zshrc`.
141 141
142 ## antigen-bundles 142 ## antigen-bundles
143 143
144 If you have a fair number of bundles, using the `antigen-bundle` command can 144 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 145 look cumbersome. You can use the `antigen-bundles` command to *bulk* define
146 bundles instead of individual calls to `antigen-bundle`. 146 bundles instead of individual calls to `antigen-bundle`.
147 147
148 Usage is pretty straightforward. Just pipe the bundle specifications, just as 148 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 149 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 150 `antigen-bundles` command. The easiest way to do this, is using the heredoc
151 syntax. 151 syntax.
152 152
153 antigen-bundles <<EOF 153 antigen-bundles <<EOF
154 # Guess what to install when running an unknown command. 154 # Guess what to install when running an unknown command.
155 command-not-found 155 command-not-found
156 156
157 # The heroku tool helper plugin. 157 # The heroku tool helper plugin.
158 heroku 158 heroku
159 159
160 EOF 160 EOF
161 161
162 This is equivalent to 162 This is equivalent to
163 163
164 antigen-bundle command-not-found 164 antigen-bundle command-not-found
165 antigen-bundle heroku 165 antigen-bundle heroku
166 166
167 Of course, as you can see, from the lines piped to `antigen-bundles`, empty 167 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 168 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 169 `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 170 with the `antigen-bundle` command. See the source if you want to really
171 understand how it works. Its a very small function. 171 understand how it works. Its a very small function.
172 172
173 ## antigen-update 173 ## antigen-update
174 174
175 This is something you might not want to put in your `.zshrc`. Instead, run it 175 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. 176 occasionally to update all your plugins. It doesn't take any arguments.
177 177
178 antigen-update 178 antigen-update
179 179
180 Please note that the updates that are downloaded are not immediately available. 180 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 181 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 182 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 183 that may not be immediately apparent. Let's just say it can make your shell act
184 real quirky. 184 real quirky.
185 185
186 **Please note**: This command is not for updating *antigen* itself. Its for 186 **Please note**: This command is not for updating *antigen* itself. Its for
187 updating the bundles you are using with antigen. 187 updating the bundles you are using with antigen.
188 188
189 ## antigen-list 189 ## antigen-list
190 190
191 Use this command to list out the currently *loaded* plugins. Keep in mind that 191 Use this command to list out the currently *loaded* plugins. Keep in mind that
192 this includes any bundles installed on-the-fly. 192 this includes any bundles installed on-the-fly.
193 193
194 Takes no arguments. Gives out the repo url and the plugin's location under the 194 Takes no arguments. Gives out the repo url and the plugin's location under the
195 repo. 195 repo.
196 196
197 ## antigen-cleanup 197 ## antigen-cleanup
198 198
199 Used to clean up the clones of repos which are not used by any plugins. It takes 199 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 200 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*. 201 but are not used by any plugin *currently loaded*.
202 202
203 This command currently cannot run in a non-interactive mode. So it won't be very 203 This command currently cannot run in a non-interactive mode. So it won't be very
204 pleasant to use it in your `.zshrc`. 204 pleasant to use it in your `.zshrc`.
205 205
206 ## antigen-lib 206 ## antigen-lib
207 207
208 This is a shortcut to 208 This is a shortcut to
209 209
210 antigen-bundle --loc=lib 210 antigen-bundle --loc=lib
211 211
212 So, it basically installs the oh-my-zsh's library as a bundle. Please note that 212 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 213 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 214 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 215 the `antigen-lib` short cut. You have to do that directly with the
216 `antigen-bundle` command. 216 `antigen-bundle` command.
217 217
218 This is present only for legacy reasons and *might* (or might not) be removed in 218 This is present only for legacy reasons and *might* (or might not) be removed in
219 the future. 219 the future.
220 220
221 Use 221 Use
222 222
223 antigen-lib 223 antigen-lib
224 224
225 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no 225 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no
226 arguments. 226 arguments.
227 227
228 ## antigen-theme 228 ## antigen-theme
229 229
230 Used for switching the prompt theme. Invoke it with the name of the theme you 230 Used for switching the prompt theme. Invoke it with the name of the theme you
231 want to use. 231 want to use.
232 232
233 antigen-theme fox 233 antigen-theme fox
234 234
235 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 235 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. 236 support getting themes from other repos as well in the future.
237 237
238 You can use this command to change your theme on the fly in your shell. Go on, 238 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`. 239 try out a few themes in your shell before you set it in your `.zshrc`.
240 240
241 ## antigen-apply 241 ## antigen-apply
242 242
243 You have to add this command after defining all bundles you need, in your zshrc. 243 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. 244 The completions defined by your bundles will be loaded at this step.
245 245
246 It is possible to load completions as and when a bundle is specified with the 246 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 247 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 248 the completions is a time-consuming process and your shell will start noticeably
249 slow if you have a good number of bundle specifications. 249 slow if you have a good number of bundle specifications.
250 250
251 However, if you're a zsh expert and can suggest a way so that this would not be 251 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 252 necessary, I am very interested in discussing it. Please open up an issue with
253 your details. Thanks. 253 your details. Thanks.
254 254
255 # Configuration 255 # Configuration
256 256
257 The following environment variables can be set to customize the behavior of 257 The following environment variables can be set to customize the behavior of
258 antigen. Make sure you set them *before* source-ing `antigen.zsh`. 258 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
259 259
260 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 260 `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, 261 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. 262 but you can set this to the fork url of your own fork.
263 263
264 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your 264 `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. 265 bundles, themes, caches and everything else antigen requires to run smoothly.
266 Defaults to `$HOME/.antigen`. 266 Defaults to `$HOME/.antigen`.
267 267
268 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables 268 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables
269 were used previously but are now removed. Please use `ADOTDIR` instead, as 269 were used previously but are now removed. Please use `ADOTDIR` instead, as
270 mentioned above. 270 mentioned above.
271 271
272 # Meta 272 # Meta
273 273
274 Project is licensed with the [MIT License][license]. To contribute, just fork, 274 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, 275 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. 276 please consider opening an [issue][] first so we can discuss it out.
277 277
278 Any comments/suggestions/feedback welcome. Please join the discussion on the 278 Any comments/suggestions/feedback welcome. Please join the discussion on the
279 [reddit page][] of this project. Also, follow me on twitter, 279 [reddit page][] of this project. Also, follow me on twitter,
280 [@sharat87](twitter). 280 [@sharat87](twitter).
281 281
282 [Vundle]: https://github.com/gmarik/vundle 282 [Vundle]: https://github.com/gmarik/vundle
283 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 283 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
284 [issue]: https://github.com/sharat87/antigen/issues 284 [issue]: https://github.com/sharat87/antigen/issues
285 [license]: http://mit.sharats.me 285 [license]: http://mit.sharats.me
286 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ 286 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
287 [twitter]: http://twitter.com/sharat87 287 [twitter]: http://twitter.com/sharat87
288 288