Commit e1bf049d88dca155ed17c6959a80f88555434168
1 parent
911cc8cb5a
Add alpha notice to README.
Showing 1 changed file with 5 additions and 0 deletions Inline Diff
README.mkd
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 | ||
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 | ||
10 | pull a new version of antigen. | ||
11 | |||
7 | # Quick Usage | 12 | # Quick Usage |
8 | 13 | ||
9 | 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 |
10 | git repo, | 15 | git repo, |
11 | 16 | ||
12 | git clone https://github.com/sharat87/antigen.git | 17 | git clone https://github.com/sharat87/antigen.git |
13 | 18 | ||
14 | 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` |
15 | might look like this | 20 | might look like this |
16 | 21 | ||
17 | source /path-to-antigen-clone/antigen.zsh | 22 | source /path-to-antigen-clone/antigen.zsh |
18 | 23 | ||
19 | # Load the oh-my-zsh's library. | 24 | # Load the oh-my-zsh's library. |
20 | bundle-lib | 25 | bundle-lib |
21 | 26 | ||
22 | # Bundles from the default repo (robbyrussell's oh-my-zsh). | 27 | # Bundles from the default repo (robbyrussell's oh-my-zsh). |
23 | bundle git | 28 | bundle git |
24 | bundle heroku | 29 | bundle heroku |
25 | bundle pip | 30 | bundle pip |
26 | bundle lein | 31 | bundle lein |
27 | bundle command-not-found | 32 | bundle command-not-found |
28 | 33 | ||
29 | # Syntax highlighting bundle. | 34 | # Syntax highlighting bundle. |
30 | bundle zsh-users/zsh-syntax-highlighting | 35 | bundle zsh-users/zsh-syntax-highlighting |
31 | 36 | ||
32 | # Load the theme. | 37 | # Load the theme. |
33 | bundle-theme robbyrussell | 38 | bundle-theme robbyrussell |
34 | 39 | ||
35 | # Tell antigen that you're done. | 40 | # Tell antigen that you're done. |
36 | bundle-apply | 41 | bundle-apply |
37 | 42 | ||
38 | Open your zsh with this zshrc and run `bundle-install` and you should be ready | 43 | Open your zsh with this zshrc and run `bundle-install` and you should be ready |
39 | to roll. The complete syntax for the `bundle` command is discussed further down | 44 | to roll. The complete syntax for the `bundle` command is discussed further down |
40 | on this page. | 45 | on this page. |
41 | 46 | ||
42 | # Motivation | 47 | # Motivation |
43 | 48 | ||
44 | 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 |
45 | 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 |
46 | 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 |
47 | 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 |
48 | admire robbyrussell's efforts for reviewing and mergine the gigantic number of | 53 | admire robbyrussell's efforts for reviewing and mergine the gigantic number of |
49 | 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. |
50 | 55 | ||
51 | 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 |
52 | 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, |
53 | 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 |
54 | shell script expert (far from it). | 59 | shell script expert (far from it). |
55 | 60 | ||
56 | [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 | 61 | [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 |
57 | [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 | 62 | [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 |
58 | [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 | 63 | [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 |
59 | 64 | ||
60 | 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 |
61 | 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 |
62 | 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 |
63 | now and then. | 68 | now and then. |
64 | 69 | ||
65 | 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 |
66 | 71 | ||
67 | bundle-theme candy | 72 | bundle-theme candy |
68 | 73 | ||
69 | and your prompt is changed, just for this session of course. | 74 | and your prompt is changed, just for this session of course. |
70 | 75 | ||
71 | # Commands | 76 | # Commands |
72 | 77 | ||
73 | ## bundle | 78 | ## bundle |
74 | 79 | ||
75 | This is the command you use to tell antigen that you want to use a plugin. The | 80 | This is the command you use to tell antigen that you want to use a plugin. The |
76 | simplest usage follows the following syntax | 81 | simplest usage follows the following syntax |
77 | 82 | ||
78 | bundle <plugin-name> | 83 | bundle <plugin-name> |
79 | 84 | ||
80 | This will add the `plugins/<name>` directory from [robbyrussell's | 85 | This will add the `plugins/<name>` directory from [robbyrussell's |
81 | 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`). |
82 | 87 | ||
83 | However, the above is just syntax sugar for the real syntax of the `bundle` | 88 | However, the above is just syntax sugar for the real syntax of the `bundle` |
84 | command. | 89 | command. |
85 | 90 | ||
86 | bundle [<url> [<loc> [<name>]]] | 91 | bundle [<url> [<loc> [<name>]]] |
87 | 92 | ||
88 | 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 |
89 | oh-my-zsh][oh-my-zsh] repo. `<loc>` is the path under this repository which has | 94 | oh-my-zsh][oh-my-zsh] repo. `<loc>` is the path under this repository which has |
90 | the zsh plugin. This is typically the directory that contains a `*.plugin.zsh` | 95 | the zsh plugin. This is typically the directory that contains a `*.plugin.zsh` |
91 | file, but it could contain a completion file too. `<loc>` defaults to `/`, which | 96 | file, but it could contain a completion file too. `<loc>` defaults to `/`, which |
92 | indicates the repository itself is a plugin. `<name>` is the name with which | 97 | indicates the repository itself is a plugin. `<name>` is the name with which |
93 | this plugin will be identified. This plugin will be installed in the bundles | 98 | this plugin will be identified. This plugin will be installed in the bundles |
94 | directory with this name used as the directory name. If the `<name>` is not | 99 | directory with this name used as the directory name. If the `<name>` is not |
95 | given, antigen tries to make an intelligent guess based on the other given | 100 | given, antigen tries to make an intelligent guess based on the other given |
96 | arguments. | 101 | arguments. |
97 | 102 | ||
98 | An example invocation would be | 103 | An example invocation would be |
99 | 104 | ||
100 | bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant | 105 | bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant |
101 | 106 | ||
102 | This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's | 107 | This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's |
103 | oh-my-zsh repo. Of course, github url's can be shortened. | 108 | oh-my-zsh repo. Of course, github url's can be shortened. |
104 | 109 | ||
105 | bundle robbyrussell/oh-my-zsh plugins/ant | 110 | bundle robbyrussell/oh-my-zsh plugins/ant |
106 | 111 | ||
107 | And since this is the default, even that isn't necessary. But we can't specify | 112 | And since this is the default, even that isn't necessary. But we can't specify |
108 | the `loc` without giving the first argument. | 113 | the `loc` without giving the first argument. |
109 | 114 | ||
110 | For this and a few other reasons, `bundle` also supports a simple keyword | 115 | For this and a few other reasons, `bundle` also supports a simple keyword |
111 | argument syntax, using which we can rewrite the above as | 116 | argument syntax, using which we can rewrite the above as |
112 | 117 | ||
113 | bundle --loc=plugins/ant | 118 | bundle --loc=plugins/ant |
114 | 119 | ||
115 | Which is the same as | 120 | Which is the same as |
116 | 121 | ||
117 | bundle ant | 122 | bundle ant |
118 | 123 | ||
119 | (In the short syntax sugar introduced at the start of this section). | 124 | (In the short syntax sugar introduced at the start of this section). |
120 | 125 | ||
121 | Note that you can mix and match positional and keyword arguments. But you can't | 126 | Note that you can mix and match positional and keyword arguments. But you can't |
122 | have positional arguments after starting keyword arguments. | 127 | have positional arguments after starting keyword arguments. |
123 | 128 | ||
124 | bundle robbyrussell/oh-my-zsh --loc=plugins/ant | 129 | bundle robbyrussell/oh-my-zsh --loc=plugins/ant |
125 | 130 | ||
126 | And keyword arguments don't care about the order in which the arguments are | 131 | And keyword arguments don't care about the order in which the arguments are |
127 | specified. The following is perfectly valid. | 132 | specified. The following is perfectly valid. |
128 | 133 | ||
129 | bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant | 134 | bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant |
130 | 135 | ||
131 | In addition to the above discussed arguments, `bundle` also takes the following | 136 | In addition to the above discussed arguments, `bundle` also takes the following |
132 | arguments but only as keyword arguments. | 137 | arguments but only as keyword arguments. |
133 | 138 | ||
134 | `load` — Set to `true` (default) or `false`. If this is set to `false`, | 139 | `load` — Set to `true` (default) or `false`. If this is set to `false`, |
135 | the plugin specified is only recorded, may be for future use. It is not loaded | 140 | the plugin specified is only recorded, may be for future use. It is not loaded |
136 | into the environment. But with `true`, the plugin is immediately sourced and | 141 | into the environment. But with `true`, the plugin is immediately sourced and |
137 | is ready to use, which is the default behavior. | 142 | is ready to use, which is the default behavior. |
138 | 143 | ||
139 | ## bundle-install | 144 | ## bundle-install |
140 | 145 | ||
141 | This is something you might not want to put in your `.zshrc`. Instead, run it to | 146 | This is something you might not want to put in your `.zshrc`. Instead, run it to |
142 | install all the recorded bundles, using the `bundle` command. It has the | 147 | install all the recorded bundles, using the `bundle` command. It has the |
143 | following syntax. | 148 | following syntax. |
144 | 149 | ||
145 | bundle-install [--update] [<plugin-spec>] | 150 | bundle-install [--update] [<plugin-spec>] |
146 | 151 | ||
147 | The optional `--update` argument can be given to update all your plugins from | 152 | The optional `--update` argument can be given to update all your plugins from |
148 | the server. By default, `bundle-install` does *not* check for updates on the | 153 | the server. By default, `bundle-install` does *not* check for updates on the |
149 | plugins. It just installs them, if there is a cached copy available and if its | 154 | plugins. It just installs them, if there is a cached copy available and if its |
150 | not already installed. | 155 | not already installed. |
151 | 156 | ||
152 | The other argument part illustrated above is the `<plugin-spec>`. Other than the | 157 | The other argument part illustrated above is the `<plugin-spec>`. Other than the |
153 | optional `--update` argument, everything else is considered as describing a | 158 | optional `--update` argument, everything else is considered as describing a |
154 | particular plugin to be installed. So, a command like | 159 | particular plugin to be installed. So, a command like |
155 | 160 | ||
156 | bundle-install <plugin-spec> | 161 | bundle-install <plugin-spec> |
157 | 162 | ||
158 | is **almost** equivalent to | 163 | is **almost** equivalent to |
159 | 164 | ||
160 | bundle <plugin-spec> | 165 | bundle <plugin-spec> |
161 | bundle-install | 166 | bundle-install |
162 | 167 | ||
163 | I say **almost** because in the former, *only* the said plugin is installed and | 168 | I say **almost** because in the former, *only* the said plugin is installed and |
164 | is usable immediately. This kind of invocation is supposed to be used directly | 169 | is usable immediately. This kind of invocation is supposed to be used directly |
165 | from the shell, not added to your `.zshrc`. The idea is to let you try out new | 170 | from the shell, not added to your `.zshrc`. The idea is to let you try out new |
166 | plugins you come across. For example, | 171 | plugins you come across. For example, |
167 | 172 | ||
168 | bundle-install lol | 173 | bundle-install lol |
169 | 174 | ||
170 | After that, you have the `lol` plugin ready to be used right there. You can try | 175 | After that, you have the `lol` plugin ready to be used right there. You can try |
171 | it out and if you like it, you can add the following to load it in every new | 176 | it out and if you like it, you can add the following to load it in every new |
172 | shell instance you open | 177 | shell instance you open |
173 | 178 | ||
174 | bundle lol | 179 | bundle lol |
175 | 180 | ||
176 | If you don't want it, the plugin will still stay installed, but won't be used. | 181 | If you don't want it, the plugin will still stay installed, but won't be used. |
177 | No harm done, but you can run `bundle-cleanup` to clean up such stray plugins | 182 | No harm done, but you can run `bundle-cleanup` to clean up such stray plugins |
178 | that you don't use. Documentation for that command further down. | 183 | that you don't use. Documentation for that command further down. |
179 | 184 | ||
180 | **Note** that the `<plugin-spec>` can be made of multiple number of arguments, | 185 | **Note** that the `<plugin-spec>` can be made of multiple number of arguments, |
181 | just like the `bundle` command can take multiple number of arguments to | 186 | just like the `bundle` command can take multiple number of arguments to |
182 | correctly describe the plugin. | 187 | correctly describe the plugin. |
183 | 188 | ||
184 | ## bundle-install! | 189 | ## bundle-install! |
185 | 190 | ||
186 | This is the same as running | 191 | This is the same as running |
187 | 192 | ||
188 | bundle-install --update | 193 | bundle-install --update |
189 | 194 | ||
190 | That is, it installs the recorded plugins, and updates them to the latest | 195 | That is, it installs the recorded plugins, and updates them to the latest |
191 | available versions. | 196 | available versions. |
192 | 197 | ||
193 | ## bundle-list | 198 | ## bundle-list |
194 | 199 | ||
195 | Use this command to list out the currently recorded plugins. *Note* that the | 200 | Use this command to list out the currently recorded plugins. *Note* that the |
196 | plugins listed by this command are not necessarily installed. They are just the | 201 | plugins listed by this command are not necessarily installed. They are just the |
197 | ones that have be recorded, probably with the `bundle` command. | 202 | ones that have be recorded, probably with the `bundle` command. |
198 | 203 | ||
199 | If you have done any on-spot temporary installation of some plugins with | 204 | If you have done any on-spot temporary installation of some plugins with |
200 | `bundle-install`, they will *not* be listed in the output of this command. | 205 | `bundle-install`, they will *not* be listed in the output of this command. |
201 | Record them with the `bundle` command for them to be listed in the output of | 206 | Record them with the `bundle` command for them to be listed in the output of |
202 | this command. | 207 | this command. |
203 | 208 | ||
204 | ## bundle-cleanup | 209 | ## bundle-cleanup |
205 | 210 | ||
206 | Used to clean up unused bundles. It takes no arguments. When this is run, it | 211 | Used to clean up unused bundles. It takes no arguments. When this is run, it |
207 | lists out the plugins that are installed but are not recorded with a `bundle` | 212 | lists out the plugins that are installed but are not recorded with a `bundle` |
208 | command, and will ask you if you want to delete them. | 213 | command, and will ask you if you want to delete them. |
209 | 214 | ||
210 | This command currently cannot run in a non-interactive mode. So it won't be very | 215 | This command currently cannot run in a non-interactive mode. So it won't be very |
211 | pleasant to use it in your `.zshrc`. | 216 | pleasant to use it in your `.zshrc`. |
212 | 217 | ||
213 | ## bundle-lib | 218 | ## bundle-lib |
214 | 219 | ||
215 | This currently exists only to make is possible to use oh-my-zsh's library, since | 220 | This currently exists only to make is possible to use oh-my-zsh's library, since |
216 | its organisation is different from that of plugins. If you want to load | 221 | its organisation is different from that of plugins. If you want to load |
217 | oh-my-zsh's library, which you very likely do, put a | 222 | oh-my-zsh's library, which you very likely do, put a |
218 | 223 | ||
219 | bundle-lib | 224 | bundle-lib |
220 | 225 | ||
221 | in your `.zshrc`, before any `bundle` declarations. It takes no arguments. | 226 | in your `.zshrc`, before any `bundle` declarations. It takes no arguments. |
222 | 227 | ||
223 | ## bundle-theme | 228 | ## bundle-theme |
224 | 229 | ||
225 | 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 |
226 | want to use. | 231 | want to use. |
227 | 232 | ||
228 | bundle-theme fox | 233 | bundle-theme fox |
229 | 234 | ||
230 | 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 |
231 | support getting themes from other repos as well in the future. | 236 | support getting themes from other repos as well in the future. |
232 | 237 | ||
233 | ## bundle-apply | 238 | ## bundle-apply |
234 | 239 | ||
235 | You have to add this command after defining all bundles you need, in your zshrc. | 240 | You have to add this command after defining all bundles you need, in your zshrc. |
236 | The completions defined by your bundles will be loaded at this step. | 241 | The completions defined by your bundles will be loaded at this step. |
237 | 242 | ||
238 | It is possible to load completions as and when a bundle is specified with the | 243 | It is possible to load completions as and when a bundle is specified with the |
239 | bundle command, in which case this command would not be necessary. But loading | 244 | bundle command, in which case this command would not be necessary. But loading |
240 | the completions is a time-consuming process and your shell will start noticeably | 245 | the completions is a time-consuming process and your shell will start noticeably |
241 | slow if you have a good number of bundle specifications. | 246 | slow if you have a good number of bundle specifications. |
242 | 247 | ||
243 | However, if you're a zsh expert and can suggest a way so that this would not be | 248 | However, if you're a zsh expert and can suggest a way so that this would not be |
244 | necessary, I am very interested in discussing it. Please open up an issue with | 249 | necessary, I am very interested in discussing it. Please open up an issue with |
245 | your details. Thanks. | 250 | your details. Thanks. |
246 | 251 | ||
247 | # Configuration | 252 | # Configuration |
248 | 253 | ||
249 | The following environment variables can be set to customize the behavior of | 254 | The following environment variables can be set to customize the behavior of |
250 | antigen. Make sure you set them *before* sourceing `antigen.zsh`. | 255 | antigen. Make sure you set them *before* sourceing `antigen.zsh`. |
251 | 256 | ||
252 | `ANTIGEN_DEFAULT_REPO_URL` — This is the default repository url that is | 257 | `ANTIGEN_DEFAULT_REPO_URL` — This is the default repository url that is |
253 | used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, | 258 | used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, |
254 | but you can set this to the fork url of your own fork. | 259 | but you can set this to the fork url of your own fork. |
255 | 260 | ||
256 | `ADOTDIR` — This directory is used to store all the repo clones, your | 261 | `ADOTDIR` — This directory is used to store all the repo clones, your |
257 | bundles, themes, caches and everything else antigen requires to run smoothly. | 262 | bundles, themes, caches and everything else antigen requires to run smoothly. |
258 | Defaults to `$HOME/.antigen`. | 263 | Defaults to `$HOME/.antigen`. |
259 | 264 | ||
260 | **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` — These variables | 265 | **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` — These variables |
261 | were used previously but are now removed. Please use `ADOTDIR` instead, as | 266 | were used previously but are now removed. Please use `ADOTDIR` instead, as |
262 | mentioned above. | 267 | mentioned above. |
263 | 268 | ||
264 | # Meta | 269 | # Meta |
265 | 270 | ||
266 | Please note that I built this over night and should be considered very alpha. | 271 | Please note that I built this over night and should be considered very alpha. |
267 | However, I am using it full time now on my work machine. | 272 | However, I am using it full time now on my work machine. |
268 | 273 | ||
269 | Project is licensed with the MIT License. To contribute, just fork, make changes | 274 | Project is licensed with the MIT License. To contribute, just fork, make changes |
270 | and send a pull request. If its a rather long/complicated change, please | 275 | and send a pull request. If its a rather long/complicated change, please |
271 | consider opening an [issue][] first so we can discuss it out. | 276 | consider opening an [issue][] first so we can discuss it out. |
272 | 277 | ||
273 | Any comments/suggestions/feedback welcome. Please join the discussion on the | 278 | Any comments/suggestions/feedback welcome. Please join the discussion on the |
274 | [reddit page][] of this project. | 279 | [reddit page][] of this project. |
275 | 280 | ||
276 | [Vundle]: https://github.com/gmarik/vundle | 281 | [Vundle]: https://github.com/gmarik/vundle |
277 | [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh | 282 | [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh |
278 | [issue]: https://github.com/sharat87/antigen/issues | 283 | [issue]: https://github.com/sharat87/antigen/issues |
279 | [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ | 284 | [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ |
280 | 285 |