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 Side-by-side Diff

... ... @@ -40,9 +40,9 @@ might look like this
40 40 # Tell antigen that you're done.
41 41 bundle-apply
42 42  
43   -Open your zsh with this zshrc and run `bundle-install` and you should be ready
44   -to roll. The complete syntax for the `bundle` command is discussed further down
45   -on this page.
  43 +Open your zsh with this zshrc and you should see all the bundles you defined
  44 +here, getting installed. Once its done, you are ready to roll. The complete
  45 +syntax for the `bundle` command is discussed further down on this page.
46 46  
47 47 # Motivation
48 48  
... ... @@ -50,7 +50,7 @@ If you use zsh and [oh-my-zsh][], you know that having many different plugins
50 50 that are developed by many different authors in a single (sub)repo is not a very
51 51 easy to maintain. There are some really fantastic plugins and utilities in
52 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 54 pull requests the project gets. It needs a better way of plugin management.
55 55  
56 56 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
... ... @@ -77,149 +77,114 @@ and your prompt is changed, just for this session of course.
77 77  
78 78 ## bundle
79 79  
80   -This is the command you use to tell antigen that you want to use a plugin. The
81   -simplest usage follows the following syntax
  80 +This command tells antigen to install (if not already installed) and load the
  81 +given plugin. The simplest usage follows the following syntax.
82 82  
83 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 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 89 command.
90 90  
91   - bundle [<url> [<loc> [<name>]]]
  91 + bundle [<url> [<loc>]]
92 92  
93 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
95   -the zsh plugin. This is typically the directory that contains a `*.plugin.zsh`
96   -file, but it could contain a completion file too. `<loc>` defaults to `/`, which
97   -indicates the repository itself is a plugin. `<name>` is the name with which
98   -this plugin will be identified. This plugin will be installed in the bundles
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.
  94 +oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`
  95 +discussed further down). `<loc>` is the path under this repository which has the
  96 +zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,
  97 +but it could contain a completion file or just many `*.zsh` files to be sourced.
  98 +`<loc>` defaults to `/`, which indicates the repository itself is a plugin.
102 99  
103 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 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
108   -oh-my-zsh repo. Of course, github url's can be shortened.
  106 +This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
  107 +github url's can be shortened.
109 108  
110 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
113   -the `loc` without giving the first argument.
  111 +And since this repo is the default, even that isn't necessary. But we can't
  112 +specify the `loc` without giving the first argument.
114 113  
115 114 For this and a few other reasons, `bundle` also supports a simple keyword
116 115 argument syntax, using which we can rewrite the above as
117 116  
118 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
123   -
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.
  122 +*Note* that you can mix and match positional and keyword arguments. But you
  123 +can't have positional arguments after keyword arguments.
128 124  
129 125 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
130 126  
131 127 And keyword arguments don't care about the order in which the arguments are
132 128 specified. The following is perfectly valid.
133 129  
134   - bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant
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
  130 + bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
167 131  
168   -I say **almost** because in the former, *only* the said plugin is installed and
169   -is usable immediately. This kind of invocation is supposed to be used directly
170   -from the shell, not added to your `.zshrc`. The idea is to let you try out new
171   -plugins you come across. For example,
  132 +In addition to the above discussed arguments, `bundle` also takes a `btype`
  133 +keyword-only argument, that is used internally. You shouldn't be concerned with
  134 +this argument, its only used internally and will probably go away in the future.
  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
176   -it out and if you like it, you can add the following to load it in every new
177   -shell instance you open
  142 +## bundle-update
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.
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.
  147 + bundle-update
184 148  
185   -**Note** that the `<plugin-spec>` can be made of multiple number of arguments,
186   -just like the `bundle` command can take multiple number of arguments to
187   -correctly describe the plugin.
188   -
189   -## bundle-install!
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.
  149 +Please note that the updates that are downloaded are not immediately available.
  150 +You have to open a new shell to be able to see the changes. This is a limitation
  151 +by design since reloading all the plugins *might* have some nasty side effects
  152 +that may not be immediately apparent. Let's just say it can make your shell act
  153 +real quirky.
197 154  
198 155 ## bundle-list
199 156  
200   -Use this command to list out the currently recorded plugins. *Note* that the
201   -plugins listed by this command are not necessarily installed. They are just the
202   -ones that have be recorded, probably with the `bundle` command.
  157 +Use this command to list out the currently *loaded* plugins. Keep in mind that
  158 +this includes any bundles installed on-the-fly.
203 159  
204   -If you have done any on-spot temporary installation of some plugins with
205   -`bundle-install`, they will *not* be listed in the output of this command.
206   -Record them with the `bundle` command for them to be listed in the output of
207   -this command.
  160 +Takes no arguments. Gives out the repo url and the plugin's location under the
  161 +repo.
208 162  
209 163 ## bundle-cleanup
210 164  
211   -Used to clean up unused bundles. It takes no arguments. When this is run, it
212   -lists out the plugins that are installed but are not recorded with a `bundle`
213   -command, and will ask you if you want to delete them.
  165 +Used to clean up the clones of repos which are not used by any plugins. It takes
  166 +no arguments. When this is run, it lists out the repo-clones that are available
  167 +but are not used by any plugin *currently loaded*.
214 168  
215 169 This command currently cannot run in a non-interactive mode. So it won't be very
216 170 pleasant to use it in your `.zshrc`.
217 171  
218 172 ## bundle-lib
219 173  
220   -This currently exists only to make is possible to use oh-my-zsh's library, since
221   -its organisation is different from that of plugins. If you want to load
222   -oh-my-zsh's library, which you very likely do, put a
  174 +This is a shortcut to
  175 +
  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 189 bundle-lib
225 190  
... ... @@ -235,6 +200,9 @@ want to use.
235 200 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
236 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 206 ## bundle-apply
239 207  
240 208 You have to add this command after defining all bundles you need, in your zshrc.
... ... @@ -252,7 +220,7 @@ your details. Thanks.
252 220 # Configuration
253 221  
254 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 225 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
258 226 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
... ... @@ -268,17 +236,17 @@ mentioned above.
268 236  
269 237 # Meta
270 238  
271   -Please note that I built this over night and should be considered very alpha.
272   -However, I am using it full time now on my work machine.
273   -
274   -Project is licensed with the MIT License. To contribute, just fork, make changes
275   -and send a pull request. If its a rather long/complicated change, please
276   -consider opening an [issue][] first so we can discuss it out.
  239 +Project is licensed with the [MIT License][license]. To contribute, just fork,
  240 +make changes and send a pull request. If its a rather long/complicated change,
  241 +please consider opening an [issue][] first so we can discuss it out.
277 242  
278 243 Any comments/suggestions/feedback welcome. Please join the discussion on the
279   -[reddit page][] of this project.
  244 +[reddit page][] of this project. Also, follow me on twitter,
  245 +[@sharat87](twitter).
280 246  
281 247 [Vundle]: https://github.com/gmarik/vundle
282 248 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
283 249 [issue]: https://github.com/sharat87/antigen/issues
  250 +[license]: http://mit.sharats.me
284 251 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
  252 +[twitter]: http://twitter.com/sharat87