mj / zsh-config

Download as
Browse Code ยป

Commit 3bc0eccade2579bcc700da2eaf2b7df7d42354e2

Authored by Shrikant Sharat
1 parent 5ea1d90872

Typo.

Showing 1 changed file with 1 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] [<plugin-spec>] 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 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 153 optional `--update` argument, everything else is considered as describing a
154 particular plugin to be installed. So, a command like 154 particular plugin to be installed. So, a command like
155 155
156 bundle-install <plugin-spec> 156 bundle-install <plugin-spec>
157 157
158 is **almost** equivalent to 158 is **almost** equivalent to
159 159
160 bundle <plugin-spec> 160 bundle <plugin-spec>
161 bundle-install 161 bundle-install
162 162
163 I says **almost** because in the former, *only* the said plugin is installed and 163 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 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 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, 166 plugins you come across. For example,
167 167
168 bundle-install lol 168 bundle-install lol
169 169
170 After that, you have the `lol` plugin ready to be used right there. You can try 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 171 it out and if you like it, you can add the following to load it in every new
172 shell instance you open 172 shell instance you open
173 173
174 bundle lol 174 bundle lol
175 175
176 If you don't want it, the plugin will still stay installed, but won't be used. 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 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. 178 that you don't use. Documentation for that command further down.
179 179
180 **Note** that the `<plugin-spec>` can be made of multiple number of arguments, 180 **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 181 just like the `bundle` command can take multiple number of arguments to
182 correctly describe the plugin. 182 correctly describe the plugin.
183 183
184 ## bundle-install! 184 ## bundle-install!
185 185
186 This is the same as running 186 This is the same as running
187 187
188 bundle-install --update 188 bundle-install --update
189 189
190 That is, it installs the recorded plugins, and updates them to the latest 190 That is, it installs the recorded plugins, and updates them to the latest
191 available versions. 191 available versions.
192 192
193 ## bundle-cleanup 193 ## bundle-cleanup
194 194
195 Used to clean up unused bundles. It takes no arguments. When this is run, it 195 Used to clean up unused bundles. It takes no arguments. When this is run, it
196 lists out the plugins that are installed but are not recorded with a `bundle` 196 lists out the plugins that are installed but are not recorded with a `bundle`
197 command, and will ask you if you want to delete them. 197 command, and will ask you if you want to delete them.
198 198
199 This command currently cannot run in a non-interactive mode. So it won't be very 199 This command currently cannot run in a non-interactive mode. So it won't be very
200 pleasant to use it in your `.zshrc`. 200 pleasant to use it in your `.zshrc`.
201 201
202 ## bundle-lib 202 ## bundle-lib
203 203
204 This currently exists only to make is possible to use oh-my-zsh's library, since 204 This currently exists only to make is possible to use oh-my-zsh's library, since
205 its organisation is different from that of plugins. If you want to load 205 its organisation is different from that of plugins. If you want to load
206 oh-my-zsh's library, which you very likely do, put a 206 oh-my-zsh's library, which you very likely do, put a
207 207
208 bundle-lib 208 bundle-lib
209 209
210 in your `.zshrc`, before any `bundle` declarations. It takes no arguments. 210 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
211 211
212 ## bundle-theme 212 ## bundle-theme
213 213
214 Used for switching the prompt theme. Invoke it with the name of the theme you 214 Used for switching the prompt theme. Invoke it with the name of the theme you
215 want to use. 215 want to use.
216 216
217 bundle-theme fox 217 bundle-theme fox
218 218
219 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 219 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
220 support getting themes from other repos as well in the future. 220 support getting themes from other repos as well in the future.
221 221
222 ## bundle-apply 222 ## bundle-apply
223 223
224 You have to add this command after defining all bundles you need, in your zshrc. 224 You have to add this command after defining all bundles you need, in your zshrc.
225 The completions defined by your bundles will be loaded at this step. 225 The completions defined by your bundles will be loaded at this step.
226 226
227 It is possible to load completions as and when a bundle is specified with the 227 It is possible to load completions as and when a bundle is specified with the
228 bundle command, in which case this command would not be necessary. But loading 228 bundle command, in which case this command would not be necessary. But loading
229 the completions is a time-consuming process and your shell will start noticeably 229 the completions is a time-consuming process and your shell will start noticeably
230 slow if you have a good number of bundle specifications. 230 slow if you have a good number of bundle specifications.
231 231
232 However, if you're a zsh expert and can suggest a way so that this would not be 232 However, if you're a zsh expert and can suggest a way so that this would not be
233 necessary, I am very interested in discussing it. Please open up an issue with 233 necessary, I am very interested in discussing it. Please open up an issue with
234 your details. Thanks. 234 your details. Thanks.
235 235
236 # Configuration 236 # Configuration
237 237
238 The following environment variables can be set to customize the behavior of 238 The following environment variables can be set to customize the behavior of
239 antigen. Make sure you set them *before* sourceing `antigen.zsh`. 239 antigen. Make sure you set them *before* sourceing `antigen.zsh`.
240 240
241 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 241 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
242 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, 242 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
243 but you can set this to the fork url of your own fork. 243 but you can set this to the fork url of your own fork.
244 244
245 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached. 245 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached.
246 Defaults to `$HOME/.antigen/cache` 246 Defaults to `$HOME/.antigen/cache`
247 247
248 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced 248 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced
249 from. Defaults to `$HOME/.antigen/bundles` 249 from. Defaults to `$HOME/.antigen/bundles`
250 250
251 # Meta 251 # Meta
252 252
253 Please note that I built this over night and should be considered very alpha. 253 Please note that I built this over night and should be considered very alpha.
254 However, I am using it full time now on my work machine. 254 However, I am using it full time now on my work machine.
255 255
256 Project is licensed with the MIT License. To contribute, just fork, make changes 256 Project is licensed with the MIT License. To contribute, just fork, make changes
257 and send a pull request. If its a rather long/complicated change, please 257 and send a pull request. If its a rather long/complicated change, please
258 consider opening an [issue][] first so we can discuss it out. 258 consider opening an [issue][] first so we can discuss it out.
259 259
260 Any comments/suggestions/feedback welcome. Please join the discussion on the 260 Any comments/suggestions/feedback welcome. Please join the discussion on the
261 [reddit page][] of this project. 261 [reddit page][] of this project.
262 262
263 [Vundle]: https://github.com/gmarik/vundle 263 [Vundle]: https://github.com/gmarik/vundle
264 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 264 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
265 [issue]: https://github.com/sharat87/antigen/issues 265 [issue]: https://github.com/sharat87/antigen/issues
266 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ 266 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
267 267