mj / zsh-config

Download as
Browse Code ยป

Commit 5e26a8e26108c16aaf5c383ae64fe49ad4307c62

Authored by Shrikant Sharat
1 parent 592f1460b0

Docs on using inline plugin installation.

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

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