mj / zsh-config

Download as
Browse Code ยป

Commit 78ea5a9f42b7fd8c5e8eebedfaef418fa2f003d4

Authored by Shrikant Sharat
1 parent 2fe4683b32

Add notes on antigen-bundles command to README.

Showing 1 changed file with 31 additions and 0 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 bundle-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 bundle git
29 bundle heroku 29 bundle heroku
30 bundle pip 30 bundle pip
31 bundle lein 31 bundle lein
32 bundle command-not-found 32 bundle command-not-found
33 33
34 # Syntax highlighting bundle. 34 # Syntax highlighting bundle.
35 bundle zsh-users/zsh-syntax-highlighting 35 bundle zsh-users/zsh-syntax-highlighting
36 36
37 # Load the theme. 37 # Load the theme.
38 bundle-theme robbyrussell 38 bundle-theme robbyrussell
39 39
40 # Tell antigen that you're done. 40 # Tell antigen that you're done.
41 bundle-apply 41 bundle-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 `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
143
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
146 bundles instead of individual calls to `antigen-bundle`.
147
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
150 `antigen-bundles` command. The easiest way to do this, is using the heredoc
151 syntax.
152
153 antigen-bundles <<EOF
154 # Guess what to install when running an unknown command.
155 command-not-found
156
157 # The heroku tool helper plugin.
158 heroku
159
160 EOF
161
162 This is equivalent to
163
164 antigen-bundle command-not-found
165 antigen-bundle heroku
166
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
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
171 understand how it works. Its a very small function.
172
142 ## antigen-update 173 ## antigen-update
143 174
144 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
145 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.
146 177
147 antigen-update 178 antigen-update
148 179
149 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.
150 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
151 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
152 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
153 real quirky. 184 real quirky.
154 185
155 **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
156 updating the bundles you are using with antigen. 187 updating the bundles you are using with antigen.
157 188
158 ## antigen-list 189 ## antigen-list
159 190
160 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
161 this includes any bundles installed on-the-fly. 192 this includes any bundles installed on-the-fly.
162 193
163 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
164 repo. 195 repo.
165 196
166 ## antigen-cleanup 197 ## antigen-cleanup
167 198
168 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
169 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
170 but are not used by any plugin *currently loaded*. 201 but are not used by any plugin *currently loaded*.
171 202
172 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
173 pleasant to use it in your `.zshrc`. 204 pleasant to use it in your `.zshrc`.
174 205
175 ## antigen-lib 206 ## antigen-lib
176 207
177 This is a shortcut to 208 This is a shortcut to
178 209
179 antigen-bundle --loc=lib 210 antigen-bundle --loc=lib
180 211
181 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
182 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
183 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
184 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
185 `antigen-bundle` command. 216 `antigen-bundle` command.
186 217
187 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
188 the future. 219 the future.
189 220
190 Use 221 Use
191 222
192 antigen-lib 223 antigen-lib
193 224
194 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no 225 in your `.zshrc`, before any `antigen-bundle` declarations. It takes no
195 arguments. 226 arguments.
196 227
197 ## antigen-theme 228 ## antigen-theme
198 229
199 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
200 want to use. 231 want to use.
201 232
202 antigen-theme fox 233 antigen-theme fox
203 234
204 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
205 support getting themes from other repos as well in the future. 236 support getting themes from other repos as well in the future.
206 237
207 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,
208 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`.
209 240
210 ## antigen-apply 241 ## antigen-apply
211 242
212 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.
213 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.
214 245
215 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
216 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
217 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
218 slow if you have a good number of bundle specifications. 249 slow if you have a good number of bundle specifications.
219 250
220 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
221 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
222 your details. Thanks. 253 your details. Thanks.
223 254
224 # Configuration 255 # Configuration
225 256
226 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
227 antigen. Make sure you set them *before* source-ing `antigen.zsh`. 258 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
228 259
229 `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
230 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,
231 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.
232 263
233 `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
234 bundles, themes, caches and everything else antigen requires to run smoothly. 265 bundles, themes, caches and everything else antigen requires to run smoothly.
235 Defaults to `$HOME/.antigen`. 266 Defaults to `$HOME/.antigen`.
236 267
237 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables 268 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables
238 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
239 mentioned above. 270 mentioned above.
240 271
241 # Meta 272 # Meta
242 273
243 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,
244 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,
245 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.
246 277
247 Any comments/suggestions/feedback welcome. Please join the discussion on the 278 Any comments/suggestions/feedback welcome. Please join the discussion on the
248 [reddit page][] of this project. Also, follow me on twitter, 279 [reddit page][] of this project. Also, follow me on twitter,
249 [@sharat87](twitter). 280 [@sharat87](twitter).
250 281
251 [Vundle]: https://github.com/gmarik/vundle 282 [Vundle]: https://github.com/gmarik/vundle
252 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 283 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
253 [issue]: https://github.com/sharat87/antigen/issues 284 [issue]: https://github.com/sharat87/antigen/issues
254 [license]: http://mit.sharats.me 285 [license]: http://mit.sharats.me
255 [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/
256 [twitter]: http://twitter.com/sharat87 287 [twitter]: http://twitter.com/sharat87
257 288