mj / zsh-config

Download as
Browse Code ยป

Commit 7ba3548fdf71c196d664d0f8299903d05d7b3d4f

Authored by Shrikant Sharat
1 parent 968db06718

Updated README with the new functionality.

Showing 1 changed file with 74 additions and 106 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 run `bundle-install` and you should be ready 43 Open your zsh with this zshrc and you should see all the bundles you defined
44 to roll. The complete syntax for the `bundle` command is discussed further down 44 here, getting installed. Once its done, you are ready to roll. The complete
45 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 mergine 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 ## bundle 78 ## bundle
79 79
80 This is the command you use to tell antigen that you want to use a plugin. The 80 This command tells antigen to install (if not already installed) and load the
81 simplest usage follows the following syntax 81 given plugin. The simplest usage follows the following syntax.
82 82
83 bundle <plugin-name> 83 bundle <plugin-name>
84 84
85 This will add 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 real syntax of the `bundle` 88 However, the above is just syntax sugar for the extended syntax of the `bundle`
89 command. 89 command.
90 90
91 bundle [<url> [<loc> [<name>]]] 91 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. `<loc>` is the path under this repository which has 94 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`
95 the zsh plugin. This is typically the directory that contains a `*.plugin.zsh` 95 discussed further down). `<loc>` is the path under this repository which has the
96 file, but it could contain a completion file too. `<loc>` defaults to `/`, which 96 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,
97 indicates the repository itself is a plugin. `<name>` is the name with which 97 but it could contain a completion file or just many `*.zsh` files to be sourced.
98 this plugin will be identified. This plugin will be installed in the bundles 98 `<loc>` defaults to `/`, which indicates the repository itself is a plugin.
99 directory with this name used as the directory name. If the `<name>` is not
100 given, antigen tries to make an intelligent guess based on the other given
101 arguments.
102 99
103 An example invocation would be 100 An example invocation would be
104 101
102 # The following is the same as `bundle ant`. But for demonstration purposes,
103 # we use the extended syntax here.
105 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 104 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
106 105
107 This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's 106 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
108 oh-my-zsh repo. Of course, github url's can be shortened. 107 github url's can be shortened.
109 108
110 bundle robbyrussell/oh-my-zsh plugins/ant 109 bundle robbyrussell/oh-my-zsh plugins/ant
111 110
112 And since this is the default, even that isn't necessary. But we can't specify 111 And since this repo is the default, even that isn't necessary. But we can't
113 the `loc` without giving the first argument. 112 specify the `loc` without giving the first argument.
114 113
115 For this and a few other reasons, `bundle` also supports a simple keyword 114 For this and a few other reasons, `bundle` also supports a simple keyword
116 argument syntax, using which we can rewrite the above as 115 argument syntax, using which we can rewrite the above as
117 116
118 bundle --loc=plugins/ant 117 bundle --loc=plugins/ant
119 118
120 Which is the same as 119 Which picks up the default for the `url` argument, and uses the `loc` given to
120 it.
121 121
122 bundle ant 122 *Note* that you can mix and match positional and keyword arguments. But you
123 123 can't have positional arguments after keyword arguments.
124 (In the short syntax sugar introduced at the start of this section).
125
126 Note that you can mix and match positional and keyword arguments. But you can't
127 have positional arguments after starting keyword arguments.
128 124
129 bundle robbyrussell/oh-my-zsh --loc=plugins/ant 125 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
130 126
131 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
132 specified. The following is perfectly valid. 128 specified. The following is perfectly valid.
133 129
134 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant 130 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
135
136 In addition to the above discussed arguments, `bundle` also takes the following
137 arguments but only as keyword arguments.
138
139 `load` &mdash; Set to `true` (default) or `false`. If this is set to `false`,
140 the plugin specified is only recorded, may be for future use. It is not loaded
141 into the environment. But with `true`, the plugin is immediately sourced and
142 is ready to use, which is the default behavior.
143
144 ## bundle-install
145
146 This is something you might not want to put in your `.zshrc`. Instead, run it to
147 install all the recorded bundles, using the `bundle` command. It has the
148 following syntax.
149
150 bundle-install [--update] [<plugin-spec>]
151
152 The optional `--update` argument can be given to update all your plugins from
153 the server. By default, `bundle-install` does *not* check for updates on the
154 plugins. It just installs them, if there is a cached copy available and if its
155 not already installed.
156
157 The other argument part illustrated above is the `<plugin-spec>`. Other than the
158 optional `--update` argument, everything else is considered as describing a
159 particular plugin to be installed. So, a command like
160
161 bundle-install <plugin-spec>
162
163 is **almost** equivalent to
164
165 bundle <plugin-spec>
166 bundle-install
167 131
168 I say **almost** because in the former, *only* the said plugin is installed and 132 In addition to the above discussed arguments, `bundle` also takes a `btype`
169 is usable immediately. This kind of invocation is supposed to be used directly 133 keyword-only argument, that is used internally. You shouldn't be concerned with
170 from the shell, not added to your `.zshrc`. The idea is to let you try out new 134 this argument, its only used internally and will probably go away in the future.
171 plugins you come across. For example, 135 It indicates whether the bundle is a theme or a simple plugin.
172 136
173 bundle-install lol 137 You can use this `bundle` command not just from your `.zshrc`, but also from
138 your shell environment. This allows you to install plugins on the fly and try
139 them out. Of course if you want a bundle to be available every time you open a
140 shell, put it in your `.zshrc`.
174 141
175 After that, you have the `lol` plugin ready to be used right there. You can try 142 ## bundle-update
176 it out and if you like it, you can add the following to load it in every new
177 shell instance you open
178 143
179 bundle lol 144 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.
180 146
181 If you don't want it, the plugin will still stay installed, but won't be used. 147 bundle-update
182 No harm done, but you can run `bundle-cleanup` to clean up such stray plugins
183 that you don't use. Documentation for that command further down.
184 148
185 **Note** that the `<plugin-spec>` can be made of multiple number of arguments, 149 Please note that the updates that are downloaded are not immediately available.
186 just like the `bundle` command can take multiple number of arguments to 150 You have to open a new shell to be able to see the changes. This is a limitation
187 correctly describe the plugin. 151 by design since reloading all the plugins *might* have some nasty side effects
188 152 that may not be immediately apparent. Let's just say it can make your shell act
189 ## bundle-install! 153 real quirky.
190
191 This is the same as running
192
193 bundle-install --update
194
195 That is, it installs the recorded plugins, and updates them to the latest
196 available versions.
197 154
198 ## bundle-list 155 ## bundle-list
199 156
200 Use this command to list out the currently recorded plugins. *Note* that the 157 Use this command to list out the currently *loaded* plugins. Keep in mind that
201 plugins listed by this command are not necessarily installed. They are just the 158 this includes any bundles installed on-the-fly.
202 ones that have be recorded, probably with the `bundle` command.
203 159
204 If you have done any on-spot temporary installation of some plugins with 160 Takes no arguments. Gives out the repo url and the plugin's location under the
205 `bundle-install`, they will *not* be listed in the output of this command. 161 repo.
206 Record them with the `bundle` command for them to be listed in the output of
207 this command.
208 162
209 ## bundle-cleanup 163 ## bundle-cleanup
210 164
211 Used to clean up unused bundles. It takes no arguments. When this is run, it 165 Used to clean up the clones of repos which are not used by any plugins. It takes
212 lists out the plugins that are installed but are not recorded with a `bundle` 166 no arguments. When this is run, it lists out the repo-clones that are available
213 command, and will ask you if you want to delete them. 167 but are not used by any plugin *currently loaded*.
214 168
215 This command currently cannot run in a non-interactive mode. So it won't be very 169 This command currently cannot run in a non-interactive mode. So it won't be very
216 pleasant to use it in your `.zshrc`. 170 pleasant to use it in your `.zshrc`.
217 171
218 ## bundle-lib 172 ## bundle-lib
219 173
220 This currently exists only to make is possible to use oh-my-zsh's library, since 174 This is a shortcut to
221 its organisation is different from that of plugins. If you want to load 175
222 oh-my-zsh's library, which you very likely do, put a 176 bundle --loc=lib
177
178 So, it basically installs the oh-my-zsh's library as a bundle. Please note that
179 this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the oh-my-zsh repo or
180 a fork of that repo. If you want to specify the `url` too, then you can't use
181 the `bundle-lib` short cut. You have to do that directly with the `bundle`
182 command.
183
184 This is present only for legacy reasons and *might* (or might not) be removed in
185 the future.
186
187 Use
223 188
224 bundle-lib 189 bundle-lib
225 190
226 in your `.zshrc`, before any `bundle` declarations. It takes no arguments. 191 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
227 192
228 ## bundle-theme 193 ## bundle-theme
229 194
230 Used for switching the prompt theme. Invoke it with the name of the theme you 195 Used for switching the prompt theme. Invoke it with the name of the theme you
231 want to use. 196 want to use.
232 197
233 bundle-theme fox 198 bundle-theme fox
234 199
235 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 200 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
236 support getting themes from other repos as well in the future. 201 support getting themes from other repos as well in the future.
237 202
203 You can use this command to change your theme on the fly in your shell. Go on,
204 try out a few themes in your shell before you set it in your `.zshrc`.
205
238 ## bundle-apply 206 ## bundle-apply
239 207
240 You have to add this command after defining all bundles you need, in your zshrc. 208 You have to add this command after defining all bundles you need, in your zshrc.
241 The completions defined by your bundles will be loaded at this step. 209 The completions defined by your bundles will be loaded at this step.
242 210
243 It is possible to load completions as and when a bundle is specified with the 211 It is possible to load completions as and when a bundle is specified with the
244 bundle command, in which case this command would not be necessary. But loading 212 bundle command, in which case this command would not be necessary. But loading
245 the completions is a time-consuming process and your shell will start noticeably 213 the completions is a time-consuming process and your shell will start noticeably
246 slow if you have a good number of bundle specifications. 214 slow if you have a good number of bundle specifications.
247 215
248 However, if you're a zsh expert and can suggest a way so that this would not be 216 However, if you're a zsh expert and can suggest a way so that this would not be
249 necessary, I am very interested in discussing it. Please open up an issue with 217 necessary, I am very interested in discussing it. Please open up an issue with
250 your details. Thanks. 218 your details. Thanks.
251 219
252 # Configuration 220 # Configuration
253 221
254 The following environment variables can be set to customize the behavior of 222 The following environment variables can be set to customize the behavior of
255 antigen. Make sure you set them *before* sourceing `antigen.zsh`. 223 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
256 224
257 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 225 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
258 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, 226 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
259 but you can set this to the fork url of your own fork. 227 but you can set this to the fork url of your own fork.
260 228
261 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your 229 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your
262 bundles, themes, caches and everything else antigen requires to run smoothly. 230 bundles, themes, caches and everything else antigen requires to run smoothly.
263 Defaults to `$HOME/.antigen`. 231 Defaults to `$HOME/.antigen`.
264 232