mj / zsh-config

Download as
Browse Code ยป

Commit 63088f869d5a1f7e93556a5324d30bb733650628

Authored by Shrikant Sharat
1 parent 13399b89bf

Proof read README.

Showing 1 changed file with 67 additions and 47 deletions Side-by-side Diff

... ... @@ -5,9 +5,10 @@ plugins, called bundles. The concept is pretty much the same as bundles in a
5 5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.
6 6  
7 7 Please note that this is a very new project and can be considered beta at best.
8   -That said, I am using antigen full time now on my work machine. Also, please
9   -read the commit comments of the changesets when you pull a new version of
10   -antigen.
  8 +That said, I am using antigen full time now on my work machine.
  9 +
  10 +Note: Please read the commit comments of the changesets when you pull a new
  11 +version of antigen.
11 12  
12 13 ## Show off
13 14  
... ... @@ -29,14 +30,15 @@ running
29 30  
30 31 antigen-bundle zsh-users/zsh-syntax-highlighting
31 32  
32   -Now let it do its thing and once its done and you're back at your prompt, try
33   -and type a command. See that? Colors!
  33 +Now let it do its thing and once you're back at your prompt, try and type a
  34 +command. See that? Colors!
34 35  
35 36 So, you do git? ruby? git and ruby? There are lots of awesome plugins over at
36 37 oh-my-zsh. Treat yourself to some.
37 38  
38 39 antigen-bundle robbyrussell/oh-my-zsh plugins/ruby
39   - antigen-bundle robbyrussell/oh-my-zsh plugins/git
  40 + # Or for the lazy,
  41 + antigen-bundle git
40 42  
41 43 There are lots of plugins out there in the wild and people are writing zsh
42 44 utilities as small scripts all the time. Antigen is compatible with all of them.
... ... @@ -51,7 +53,7 @@ And boom! you have all the autoenv goodness. Just remember how you used to do
51 53 these before antigen, clone it, modify your bashrc to source it, load a new
52 54 terminal, all just to test it out. Duh!
53 55  
54   -The side effect of this is that you can tell antigen to grab just about anything
  56 +A subtle aspect of this is that you can tell antigen to grab just about anything
55 57 from anyone's `dotfiles` repo, as long as it is in a directory under any repo on
56 58 github.
57 59  
... ... @@ -73,7 +75,7 @@ and continue until you're tired. At which point you can come back to this page
73 75  
74 76 ## Usage
75 77  
76   -So, now that you're here, I'll assume you are convinced and want antigen running
  78 +So, now that you're here, I suppose you are convinced and want antigen running
77 79 your shell all the time. Sweet. Let's do it.
78 80  
79 81 First, clone this repo, probably as a submodule if you have your dotfiles in a
... ... @@ -112,11 +114,11 @@ syntax for the `antigen-bundle` command is discussed further down on this page.
112 114 ## Motivation
113 115  
114 116 If you use zsh and [oh-my-zsh][], you know that having many different plugins
115   -that are developed by many different authors in a single (sub)repo is not a very
  117 +that are developed by many different authors in a single (sub)repo is not very
116 118 easy to maintain. There are some really fantastic plugins and utilities in
117 119 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I
118 120 admire robbyrussell's efforts for reviewing and merging the gigantic number of
119   -pull requests the project gets. It needs a better way of plugin management.
  121 +pull requests the project gets. We need a better way of plugin management.
120 122  
121 123 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
122 124 there was any progress made. So, I'm trying to start this off with antigen,
... ... @@ -130,20 +132,23 @@ shell script expert (far from it).
130 132 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github
131 133 repositories. You are not limited to use plugins from the oh-my-zsh repository
132 134 only and you don't need to maintain your own fork and pull from upstream every
133   -now and then.
  135 +now and then. I actually encourage you to grab plugins and scripts from various
  136 +sources, straight from the authors, before they even submit it to oh-my-zsh as a
  137 +pull request.
134 138  
135 139 Antigen also lets you switch the prompt theme with one command, just like that
136 140  
137 141 bundle-theme candy
138 142  
139   -and your prompt is changed, just for this session of course.
  143 +and your prompt is changed, just for this session of course (unless you put this
  144 +line in your `.zshrc`).
140 145  
141 146 ## Commands
142 147  
143 148 The following are the commands provided by antigen. Note that the `-` in the
144   -following commands is kind of optional. You can write `antigen-bundle ...` as
145   -`antigen bundle` and get away with it. For more details see the help on
146   -`antigen` command further down in this section.
  149 +following commands can be replaced with a space. You can write `antigen-bundle
  150 +...` as `antigen bundle ...` and get away with it. For more details see the help
  151 +on `antigen` command further down in this section.
147 152  
148 153 ### antigen-bundle
149 154  
... ... @@ -152,7 +157,7 @@ given plugin. The simplest usage follows the following syntax.
152 157  
153 158 antigen-bundle <plugin-name>
154 159  
155   -This will install the `plugins/<name>` directory from [robbyrussell's
  160 +This will install and load the `plugins/<name>` directory from [robbyrussell's
156 161 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
157 162  
158 163 However, the above is just syntax sugar for the extended syntax of the
... ... @@ -205,15 +210,9 @@ case, make sure the path you give is the absolute path (i.e., starts with a
205 210 directory path, then it is not necessary that this path is a git repo. Please
206 211 refer to the notes on `--no-local-clone` below.
207 212  
208   -In addition to the above discussed arguments, `antigen-bundle` also takes a
209   -`btype` keyword-only argument, that is used internally. You shouldn't be
210   -concerned with this argument, its only used internally and will probably go away
211   -in the future. It indicates whether the bundle is a theme or a simple plugin.
212   -
213   -You can use this `antigen-bundle` command not just from your `.zshrc`, but also
214   -from your shell environment. This allows you to install plugins on the fly and
215   -try them out. Of course if you want a bundle to be available every time you open
216   -a shell, put it in your `.zshrc`.
  213 +This command can also be used from your shell environment. This allows you to
  214 +install plugins on the fly and try them out. Of course if you want a bundle to
  215 +be available every time you open a shell, put it in your `.zshrc`.
217 216  
218 217 Other keyword-only arguments accepted:
219 218  
... ... @@ -250,6 +249,11 @@ dotfiles repo. For example,
250 249  
251 250 antigen-bundle $HOME/dotfiles/oh-my-zsh/custom
252 251  
  252 +In addition to the above discussed arguments, `antigen-bundle` also takes a
  253 +`btype` keyword-only argument, that is used internally. You shouldn't be
  254 +concerned with this argument, its only used internally and will probably go away
  255 +in the future. It indicates whether the bundle is a theme or a simple plugin.
  256 +
253 257 ### antigen-bundles
254 258  
255 259 If you have a fair number of bundles, using the `antigen-bundle` command can
... ... @@ -261,14 +265,14 @@ you would give to the `antigen-bundle` command, one per line, into the
261 265 `antigen-bundles` command. The easiest way to do this, is using the heredoc
262 266 syntax.
263 267  
264   - antigen-bundles <<EOF
  268 + antigen-bundles <<EOBUNDLES
265 269 # Guess what to install when running an unknown command.
266 270 command-not-found
267 271  
268 272 # The heroku tool helper plugin.
269 273 heroku
270 274  
271   - EOF
  275 + EOBUNDLES
272 276  
273 277 This is equivalent to
274 278  
... ... @@ -302,14 +306,22 @@ updating the bundles you are using with antigen.
302 306 Use this command to list out the currently *loaded* plugins. Keep in mind that
303 307 this includes any bundles installed on-the-fly.
304 308  
305   -Takes no arguments. Gives out the repo url and the plugin's location under the
306   -repo.
  309 +Takes no arguments. Gives out four entries per line of output, denoting the
  310 +following fields of each bundle.
  311 +
  312 + <repo-url> <loc> <btype> <has-local-clone?>
  313 +
  314 +The `btype` field is an internal detail, that specifies if the bundle is a
  315 +`plugin` or a `theme`.
  316 +
  317 +The final field is `true` or `false` reflecting whether there is a local clone
  318 +for this bundle.
307 319  
308 320 ### antigen-cleanup
309 321  
310   -Used to clean up the clones of repos which are not used by any plugins. It takes
311   -no arguments. When this is run, it lists out the repo-clones that are available
312   -but are not used by any plugin *currently loaded*.
  322 +Used to clean up the clones of repos which are not used by any plugins currently
  323 +loaded. It takes no arguments. When run, it lists out the repo-clones that are
  324 +available but are not used by any plugin *currently loaded*.
313 325  
314 326 This command, by default asks for confirmation before deleting the unused
315 327 clones. If the `--force` argument is given, then this confirmation is not asked.
... ... @@ -322,11 +334,12 @@ This is a shortcut to
322 334  
323 335 antigen-bundle --loc=lib
324 336  
325   -So, it basically installs the oh-my-zsh's library as a bundle. Please note that
326   -this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the oh-my-zsh repo or
327   -a fork of that repo. If you want to specify the `url` too, then you can't use
328   -the `antigen-lib` short cut. You have to do that directly with the
329   -`antigen-bundle` command.
  337 +So, it basically installs the oh-my-zsh's library as a bundle.
  338 +
  339 +Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the
  340 +oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too,
  341 +then you can't use the `antigen-lib` short cut. You have to do that directly
  342 +with the `antigen-bundle` command.
330 343  
331 344 This is present only for legacy reasons and *might* (or might not) be removed in
332 345 the future.
... ... @@ -351,6 +364,10 @@ support getting themes from other repos as well in the future.
351 364 You can use this command to change your theme on the fly in your shell. Go on,
352 365 try out a few themes in your shell before you set it in your `.zshrc`.
353 366  
  367 +**Note**: Some themes use functions that are loaded by `antigen-lib`. So, to
  368 +avoid any trouble, run `antigen-lib` if you haven't already before experimenting
  369 +with themes. If you have `antigen-lib` in your `.zshrc`, you're covered.
  370 +
354 371 ### antigen-apply
355 372  
356 373 You have to add this command after defining all bundles you need, in your zshrc.
... ... @@ -358,12 +375,12 @@ The completions defined by your bundles will be loaded at this step.
358 375  
359 376 It is possible to load completions as and when a bundle is specified with the
360 377 bundle command, in which case this command would not be necessary. But loading
361   -the completions is a time-consuming process and your shell will start noticeably
362   -slow if you have a good number of bundle specifications.
  378 +the completions is a time-consuming process, so if the completions were loaded
  379 +at every call to `antigen-bundle`, your shell will start noticeably slow when
  380 +you have a good number of bundle specifications.
363 381  
364   -However, if you're a zsh expert and can suggest a way so that this would not be
365   -necessary, I am very interested in discussing it. Please open up an issue with
366   -your details. Thanks.
  382 +However, if you can suggest a way so that this would not be necessary, I am very
  383 +interested in discussing it. Please open up an issue with your details. Thanks.
367 384  
368 385 ### antigen-help
369 386  
... ... @@ -377,8 +394,8 @@ looks good as output on the command line.
377 394  
378 395 ### antigen
379 396  
380   -This is a parent command that mainly exists for convenience. The idea is the
381   -following two are the same.
  397 +This is a parent command that mainly exists for convenience. This exists so the
  398 +following two can be the same.
382 399  
383 400 antigen-list
384 401 antigen list
... ... @@ -439,7 +456,7 @@ functionality of antigen.
439 456 ## Notes on writing plugins
440 457  
441 458 If you are just going to write a single `.sh` file with the goodness you want to
442   -create, just forget about this and go do that. Antigen will work just find with
  459 +create, just forget about this and go do that. Antigen will work just fine with
443 460 such a plugin.
444 461  
445 462 If you want to know how antigen loads the plugins, do continue.
... ... @@ -457,8 +474,11 @@ currently defined.
457 474  
458 475 No matter which (or none) of the above happen to be sourced, this plugin
459 476 directory is added to the zsh's function path (`$fpath`) so that any completions
460   -in it are loaded. One exception to this rule is that if this plugin is a prompt
461   -theme. In which case the theme script is just sourced and nothing else is done.
  477 +in it are loaded.
  478 +
  479 +One exception to this rule is that if this plugin is a theme. In which case the
  480 +theme script is just sourced and nothing else is done. Not even adding to
  481 +`$fpath`.
462 482  
463 483 ## Meta
464 484