mj / zsh-config

Download as
Browse Code ยป

Commit 7e0aca7cecb0d58c36a949d5b052beb01d82c60c

Authored by Shrikant Sharat
1 parent 1abf1faf67

Add notes about bundle's new short syntax. 

The `bundle` command got some new super short syntax sugar. Notes about it in
the README.

Showing 1 changed file with 19 additions and 5 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 --loc=plugins/git 23 bundle git
24 bundle --loc=plugins/heroku 24 bundle heroku
25 bundle --loc=plugins/pip 25 bundle pip
26 bundle --loc=plugins/lein 26 bundle lein
27 bundle --loc=plugins/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 Open your zsh with this zshrc and run `bundle-install` and you should be ready 35 Open your zsh with this zshrc and run `bundle-install` and you should be ready
36 to roll. The complete syntax for the `bundle` command is discussed further down 36 to roll. The complete syntax for the `bundle` command is discussed further down
37 on this page. 37 on this page.
38 38
39 # Motivation 39 # Motivation
40 40
41 If you use zsh and [oh-my-zsh][], you know that having many different plugins 41 If you use zsh and [oh-my-zsh][], you know that having many different plugins
42 that are developed by many different authors in a single (sub)repo is not a very 42 that are developed by many different authors in a single (sub)repo is not a very
43 easy to maintain. There are some really fantastic plugins and utilities in 43 easy to maintain. There are some really fantastic plugins and utilities in
44 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I 44 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I
45 admire robbyrussell's efforts for reviewing and mergine the gigantic number of 45 admire robbyrussell's efforts for reviewing and mergine the gigantic number of
46 pull requests the project gets. It needs a better way of plugin management. 46 pull requests the project gets. It needs a better way of plugin management.
47 47
48 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like 48 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
49 there was any progress made. So, I'm trying to start this off with antigen, 49 there was any progress made. So, I'm trying to start this off with antigen,
50 hoping to better this situation. Please note that I'm by no means a zsh or any 50 hoping to better this situation. Please note that I'm by no means a zsh or any
51 shell script expert (far from it). 51 shell script expert (far from it).
52 52
53 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 53 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
54 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 54 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
55 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 55 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
56 56
57 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github 57 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github
58 repositories. You are not limited to use plugins from the oh-my-zsh repository 58 repositories. You are not limited to use plugins from the oh-my-zsh repository
59 only and you don't need to maintain your own fork and pull from upstream every 59 only and you don't need to maintain your own fork and pull from upstream every
60 now and then. 60 now and then.
61 61
62 Antigen also lets you switch the prompt theme with one command, just like that 62 Antigen also lets you switch the prompt theme with one command, just like that
63 63
64 bundle-theme candy 64 bundle-theme candy
65 65
66 and your prompt is changed, just for this session of course. 66 and your prompt is changed, just for this session of course.
67 67
68 # Commands 68 # Commands
69 69
70 ## bundle 70 ## bundle
71 71
72 This is the command you use to tell antigen that you want to use a plugin. The 72 This is the command you use to tell antigen that you want to use a plugin. The
73 simplest usage follows the following syntax 73 simplest usage follows the following syntax
74 74
75 bundle <plugin-name>
76
77 This will add the `plugins/<name>` directory from [robbyrussell's
78 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
79
80 However, the above is just syntax sugar for the real syntax of the `bundle`
81 command.
82
75 bundle [<url> [<loc> [<name>]]] 83 bundle [<url> [<loc> [<name>]]]
76 84
77 where `<url>` is the repository url and it defaults to [robbyrussell's 85 where `<url>` is the repository url and it defaults to [robbyrussell's
78 oh-my-zsh][oh-my-zsh] repo. `<loc>` is the path under this repository which has 86 oh-my-zsh][oh-my-zsh] repo. `<loc>` is the path under this repository which has
79 the zsh plugin. This is typically the directory that contains a `*.plugin.zsh` 87 the zsh plugin. This is typically the directory that contains a `*.plugin.zsh`
80 file, but it could contain a completion file too. `<loc>` defaults to `/`, which 88 file, but it could contain a completion file too. `<loc>` defaults to `/`, which
81 indicates the repository itself is a plugin. `<name>` is the name with which 89 indicates the repository itself is a plugin. `<name>` is the name with which
82 this plugin will be identified. This plugin will be installed in the bundles 90 this plugin will be identified. This plugin will be installed in the bundles
83 directory with this name used as the directory name. If the `<name>` is not 91 directory with this name used as the directory name. If the `<name>` is not
84 given, antigen tries to make an intelligent guess based on the other given 92 given, antigen tries to make an intelligent guess based on the other given
85 arguments. 93 arguments.
86 94
87 An example invocation would be 95 An example invocation would be
88 96
89 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 97 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
90 98
91 This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's 99 This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's
92 oh-my-zsh repo. Of course, github url's can be shortened. 100 oh-my-zsh repo. Of course, github url's can be shortened.
93 101
94 bundle robbyrussell/oh-my-zsh plugins/ant 102 bundle robbyrussell/oh-my-zsh plugins/ant
95 103
96 And since this is the default, even that isn't necessary. But we can't specify 104 And since this is the default, even that isn't necessary. But we can't specify
97 the `loc` without giving the first argument. 105 the `loc` without giving the first argument.
98 106
99 For this and a few other reasons, `bundle` also supports a simple keyword 107 For this and a few other reasons, `bundle` also supports a simple keyword
100 argument syntax, using which we can rewrite the above as 108 argument syntax, using which we can rewrite the above as
101 109
102 bundle --loc=plugins/ant 110 bundle --loc=plugins/ant
103 111
112 Which is the same as
113
114 bundle ant
115
116 (In the short syntax sugar introduced at the start of this section).
117
104 Note that you can mix and match positional and keyword arguments. But you can't 118 Note that you can mix and match positional and keyword arguments. But you can't
105 have positional arguments after starting keyword arguments. 119 have positional arguments after starting keyword arguments.
106 120
107 bundle robbyrussell/oh-my-zsh --loc=plugins/ant 121 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
108 122
109 And keyword arguments don't care about the order in which the arguments are 123 And keyword arguments don't care about the order in which the arguments are
110 specified. The following is perfectly valid. 124 specified. The following is perfectly valid.
111 125
112 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant 126 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant
113 127
114 In addition to the above discussed arguments, `bundle` also takes the following 128 In addition to the above discussed arguments, `bundle` also takes the following
115 arguments but only as keyword arguments. 129 arguments but only as keyword arguments.
116 130
117 `load` &mdash; Set to `true` (default) or `false`. If this is set to `false`, 131 `load` &mdash; Set to `true` (default) or `false`. If this is set to `false`,
118 the plugin specified is only recorded, may be for future use. It is not loaded 132 the plugin specified is only recorded, may be for future use. It is not loaded
119 into the environment. But with `true`, the plugin is immediately sourced and 133 into the environment. But with `true`, the plugin is immediately sourced and
120 is ready to use, which is the default behavior. 134 is ready to use, which is the default behavior.
121 135
122 ## bundle-install 136 ## bundle-install
123 137
124 This is something you might not want to put in your `.zshrc`. Instead, run it to 138 This is something you might not want to put in your `.zshrc`. Instead, run it to
125 install all the recorded bundles, using the `bundle` command. It has the 139 install all the recorded bundles, using the `bundle` command. It has the
126 following syntax. 140 following syntax.
127 141
128 bundle-install [--update] 142 bundle-install [--update]
129 143
130 The optional `--update` argument can be given to update all your plugins from 144 The optional `--update` argument can be given to update all your plugins from
131 the server. By default, `bundle-install` does *not* check for updates on the 145 the server. By default, `bundle-install` does *not* check for updates on the
132 plugins. It just installs them, if there is a cached copy available and if its 146 plugins. It just installs them, if there is a cached copy available and if its
133 not already installed. 147 not already installed.
134 148
135 ## bundle-install! 149 ## bundle-install!
136 150
137 This is the same as running 151 This is the same as running
138 152
139 bundle-install --update 153 bundle-install --update
140 154
141 That is, it installs the recorded plugins, and updates them to the latest 155 That is, it installs the recorded plugins, and updates them to the latest
142 available versions. 156 available versions.
143 157
144 ## bundle-cleanup 158 ## bundle-cleanup
145 159
146 Used to clean up unused bundles. It takes no arguments. When this is run, it 160 Used to clean up unused bundles. It takes no arguments. When this is run, it
147 lists out the plugins that are installed but are not recorded with a `bundle` 161 lists out the plugins that are installed but are not recorded with a `bundle`
148 command, and will ask you if you want to delete them. 162 command, and will ask you if you want to delete them.
149 163
150 This command currently cannot run in a non-interactive mode. So it won't be very 164 This command currently cannot run in a non-interactive mode. So it won't be very
151 pleasant to use it in your `.zshrc`. 165 pleasant to use it in your `.zshrc`.
152 166
153 ## bundle-lib 167 ## bundle-lib
154 168
155 This currently exists only to make is possible to use oh-my-zsh's library, since 169 This currently exists only to make is possible to use oh-my-zsh's library, since
156 its organisation is different from that of plugins. If you want to load 170 its organisation is different from that of plugins. If you want to load
157 oh-my-zsh's library, which you very likely do, put a 171 oh-my-zsh's library, which you very likely do, put a
158 172
159 bundle-lib 173 bundle-lib
160 174
161 in your `.zshrc`, before any `bundle` declarations. It takes no arguments. 175 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
162 176
163 ## bundle-theme 177 ## bundle-theme
164 178
165 Used for switching the prompt theme. Invoke it with the name of the theme you 179 Used for switching the prompt theme. Invoke it with the name of the theme you
166 want to use. 180 want to use.
167 181
168 bundle-theme fox 182 bundle-theme fox
169 183
170 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 184 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will
171 support getting themes from other repos as well in the future. 185 support getting themes from other repos as well in the future.
172 186
173 # Configuration 187 # Configuration
174 188
175 The following environment variables can be set to customize the behavior of 189 The following environment variables can be set to customize the behavior of
176 antigen. Make sure you set them *before* sourceing `antigen.zsh`. 190 antigen. Make sure you set them *before* sourceing `antigen.zsh`.
177 191
178 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 192 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
179 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo, 193 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
180 but you can set this to the fork url of your own fork. 194 but you can set this to the fork url of your own fork.
181 195
182 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached. 196 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached.
183 Defaults to `$HOME/.antigen/cache` 197 Defaults to `$HOME/.antigen/cache`
184 198
185 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced 199 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced
186 from. Defaults to `$HOME/.antigen/bundles` 200 from. Defaults to `$HOME/.antigen/bundles`
187 201
188 # Meta 202 # Meta
189 203
190 Please note that I built this over night and should be considered very alpha. 204 Please note that I built this over night and should be considered very alpha.
191 However, I am using it full time now on my work machine. 205 However, I am using it full time now on my work machine.
192 206
193 Project is licensed with the MIT License. To contribute, just fork, make changes 207 Project is licensed with the MIT License. To contribute, just fork, make changes
194 and send a pull request. If its a rather long/complicated change, please 208 and send a pull request. If its a rather long/complicated change, please
195 consider opening an [issue][] first so we can discuss it out. 209 consider opening an [issue][] first so we can discuss it out.
196 210
197 Any comments/suggestions/feedback welcome. Please join the discussion on the 211 Any comments/suggestions/feedback welcome. Please join the discussion on the
198 [reddit page][] of this project. 212 [reddit page][] of this project.
199 213
200 [Vundle]: https://github.com/gmarik/vundle 214 [Vundle]: https://github.com/gmarik/vundle
201 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 215 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
202 [issue]: https://github.com/sharat87/antigen/issues 216 [issue]: https://github.com/sharat87/antigen/issues
203 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/ 217 [reddit page]: http://www.reddit.com/r/commandline/comments/u4f26/antigen_a_plugin_manager_for_zsh_shell/
204 218