Commit e1bf049d88dca155ed17c6959a80f88555434168

Authored by Shrikant Sharat
1 parent 911cc8cb5a

Add alpha notice to README.

Showing 1 changed file with 5 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
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` &mdash; Set to `true` (default) or `false`. If this is set to `false`, 139 `load` &mdash; 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` &mdash; This is the default repository url that is 257 `ANTIGEN_DEFAULT_REPO_URL` &mdash; 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` &mdash; This directory is used to store all the repo clones, your 261 `ADOTDIR` &mdash; 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` &mdash; These variables 265 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; 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