mj / zsh-config

Download as
Browse Code ยป

Commit 5c124ed5a53087b557a6a080a342e552932b916d

Authored by Shrikant Sharat
1 parent 3c698aac00

Add link to project's reddit page.

Showing 1 changed file with 4 additions and 0 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 --loc=plugins/git
24 bundle --loc=plugins/heroku 24 bundle --loc=plugins/heroku
25 bundle --loc=plugins/pip 25 bundle --loc=plugins/pip
26 bundle --loc=plugins/lein 26 bundle --loc=plugins/lein
27 bundle --loc=plugins/command-not-found 27 bundle --loc=plugins/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 [<url> [<loc> [<name>]]] 75 bundle [<url> [<loc> [<name>]]]
76 76
77 where `<url>` is the repository url and it defaults to [robbyrussell's 77 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 78 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` 79 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 80 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 81 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 82 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 83 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 84 given, antigen tries to make an intelligent guess based on the other given
85 arguments. 85 arguments.
86 86
87 An example invocation would be 87 An example invocation would be
88 88
89 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 89 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
90 90
91 This would install the ant plugin (with `<name>` as `ant`) from robbyrussell's 91 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. 92 oh-my-zsh repo. Of course, github url's can be shortened.
93 93
94 bundle robbyrussell/oh-my-zsh plugins/ant 94 bundle robbyrussell/oh-my-zsh plugins/ant
95 95
96 And since this is the default, even that isn't necessary. But we can't specify 96 And since this is the default, even that isn't necessary. But we can't specify
97 the `loc` without giving the first argument. 97 the `loc` without giving the first argument.
98 98
99 For this and a few other reasons, `bundle` also supports a simple keyword 99 For this and a few other reasons, `bundle` also supports a simple keyword
100 argument syntax, using which we can rewrite the above as 100 argument syntax, using which we can rewrite the above as
101 101
102 bundle --loc=plugins/ant 102 bundle --loc=plugins/ant
103 103
104 Note that you can mix and match positional and keyword arguments. But you can't 104 Note that you can mix and match positional and keyword arguments. But you can't
105 have positional arguments after starting keyword arguments. 105 have positional arguments after starting keyword arguments.
106 106
107 bundle robbyrussell/oh-my-zsh --loc=plugins/ant 107 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
108 108
109 And keyword arguments don't care about the order in which the arguments are 109 And keyword arguments don't care about the order in which the arguments are
110 specified. The following is perfectly valid. 110 specified. The following is perfectly valid.
111 111
112 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant 112 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant
113 113
114 In addition to the above discussed arguments, `bundle` also takes the following 114 In addition to the above discussed arguments, `bundle` also takes the following
115 arguments but only as keyword arguments. 115 arguments but only as keyword arguments.
116 116
117 `load` &mdash; Set to `true` (default) or `false`. If this is set to `false`, 117 `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 118 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 119 into the environment. But with `true`, the plugin is immediately sourced and
120 is ready to use, which is the default behavior. 120 is ready to use, which is the default behavior.
121 121
122 ## bundle-install 122 ## bundle-install
123 123
124 This is something you might not want to put in your `.zshrc`. Instead, run it to 124 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 125 install all the recorded bundles, using the `bundle` command. It has the
126 following syntax. 126 following syntax.
127 127
128 bundle-install [--update] 128 bundle-install [--update]
129 129
130 The optional `--update` argument can be given to update all your plugins from 130 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 131 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 132 plugins. It just installs them, if there is a cached copy available and if its
133 not already installed. 133 not already installed.
134 134
135 ## bundle-install! 135 ## bundle-install!
136 136
137 This is the same as running 137 This is the same as running
138 138
139 bundle-install --update 139 bundle-install --update
140 140
141 That is, it installs the recorded plugins, and updates them to the latest 141 That is, it installs the recorded plugins, and updates them to the latest
142 available versions. 142 available versions.
143 143
144 ## bundle-cleanup 144 ## bundle-cleanup
145 145
146 Used to clean up unused bundles. It takes no arguments. When this is run, it 146 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` 147 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. 148 command, and will ask you if you want to delete them.
149 149
150 This command currently cannot run in a non-interactive mode. So it won't be very 150 This command currently cannot run in a non-interactive mode. So it won't be very
151 pleasant to use it in your `.zshrc`. 151 pleasant to use it in your `.zshrc`.
152 152
153 ## bundle-lib 153 ## bundle-lib
154 154
155 This currently exists only to make is possible to use oh-my-zsh's library, since 155 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 156 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 157 oh-my-zsh's library, which you very likely do, put a
158 158
159 bundle-lib 159 bundle-lib
160 160
161 in your `.zshrc`, before any `bundle` declarations. It takes no arguments. 161 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
162 162
163 ## bundle-theme 163 ## bundle-theme
164 164
165 Used for switching the prompt theme. Invoke it with the name of the theme you 165 Used for switching the prompt theme. Invoke it with the name of the theme you
166 want to use. 166 want to use.
167 167
168 bundle-theme fox 168 bundle-theme fox
169 169
170 Currently, themes are pulled from robbyrussell's oh-my-zsh repo, but it will 170 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. 171 support getting themes from other repos as well in the future.
172 172
173 # Configuration 173 # Configuration
174 174
175 The following environment variables can be set to customize the behavior of 175 The following environment variables can be set to customize the behavior of
176 antigen. Make sure you set them *before* sourceing `antigen.zsh`. 176 antigen. Make sure you set them *before* sourceing `antigen.zsh`.
177 177
178 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is 178 `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, 179 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. 180 but you can set this to the fork url of your own fork.
181 181
182 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached. 182 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached.
183 Defaults to `$HOME/.antigen/cache` 183 Defaults to `$HOME/.antigen/cache`
184 184
185 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced 185 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced
186 from. Defaults to `$HOME/.antigen/bundles` 186 from. Defaults to `$HOME/.antigen/bundles`
187 187
188 # Meta 188 # Meta
189 189
190 Please note that I built this over night and should be considered very alpha. 190 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. 191 However, I am using it full time now on my work machine.
192 192
193 Project is licensed with the MIT License. To contribute, just fork, make changes 193 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 194 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. 195 consider opening an [issue][] first so we can discuss it out.
196 196
197 Any comments/suggestions/feedback welcome. Please join the discussion on the
198 [reddit page][] of this project.
199
197 [Vundle]: https://github.com/gmarik/vundle 200 [Vundle]: https://github.com/gmarik/vundle
198 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 201 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
199 [issue]: https://github.com/sharat87/antigen/issues 202 [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/
200 204