mj / zsh-config

Download as
Browse Code ยป

Commit 3c698aac006d5f8457de17bcda6930bd4685fbc6

Authored by Shrikant Sharat
1 parent b84833b4c7

Add information on cloning the repo.

Showing 1 changed file with 6 additions and 1 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
10 git repo,
11
12 git clone https://github.com/sharat87/antigen.git
13
9 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`
10 might look like this 15 might look like this
11 16
12 source ~/labs/antigen/antigen.zsh 17 source /path-to-antigen-clone/antigen.zsh
13 18
14 # Load the oh-my-zsh's library. 19 # Load the oh-my-zsh's library.
15 bundle-lib 20 bundle-lib
16 21
17 # Bundles from the default repo (robbyrussell's oh-my-zsh). 22 # Bundles from the default repo (robbyrussell's oh-my-zsh).
18 bundle --loc=plugins/git 23 bundle --loc=plugins/git
19 bundle --loc=plugins/heroku 24 bundle --loc=plugins/heroku
20 bundle --loc=plugins/pip 25 bundle --loc=plugins/pip
21 bundle --loc=plugins/lein 26 bundle --loc=plugins/lein
22 bundle --loc=plugins/command-not-found 27 bundle --loc=plugins/command-not-found
23 28
24 # Syntax highlighting bundle. 29 # Syntax highlighting bundle.
25 bundle zsh-users/zsh-syntax-highlighting 30 bundle zsh-users/zsh-syntax-highlighting
26 31
27 # Load the theme. 32 # Load the theme.
28 bundle-theme robbyrussell 33 bundle-theme robbyrussell
29 34
30 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
31 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
32 on this page. 37 on this page.
33 38
34 # Motivation 39 # Motivation
35 40
36 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
37 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
38 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
39 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
40 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
41 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.
42 47
43 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
44 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,
45 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
46 shell script expert (far from it). 51 shell script expert (far from it).
47 52
48 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465 53 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
49 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377 54 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
50 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014 55 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
51 56
52 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
53 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
54 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
55 now and then. 60 now and then.
56 61
57 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
58 63
59 bundle-theme candy 64 bundle-theme candy
60 65
61 and your prompt is changed, just for this session of course. 66 and your prompt is changed, just for this session of course.
62 67
63 # Commands 68 # Commands
64 69
65 ## bundle 70 ## bundle
66 71
67 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
68 simplest usage follows the following syntax 73 simplest usage follows the following syntax
69 74
70 bundle [<url> [<loc> [<name>]]] 75 bundle [<url> [<loc> [<name>]]]
71 76
72 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
73 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
74 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`
75 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
76 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
77 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
78 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
79 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
80 arguments. 85 arguments.
81 86
82 An example invocation would be 87 An example invocation would be
83 88
84 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant 89 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
85 90
86 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
87 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.
88 93
89 bundle robbyrussell/oh-my-zsh plugins/ant 94 bundle robbyrussell/oh-my-zsh plugins/ant
90 95
91 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
92 the `loc` without giving the first argument. 97 the `loc` without giving the first argument.
93 98
94 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
95 argument syntax, using which we can rewrite the above as 100 argument syntax, using which we can rewrite the above as
96 101
97 bundle --loc=plugins/ant 102 bundle --loc=plugins/ant
98 103
99 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
100 have positional arguments after starting keyword arguments. 105 have positional arguments after starting keyword arguments.
101 106
102 bundle robbyrussell/oh-my-zsh --loc=plugins/ant 107 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
103 108
104 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
105 specified. The following is perfectly valid. 110 specified. The following is perfectly valid.
106 111
107 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant 112 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant
108 113
109 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
110 arguments but only as keyword arguments. 115 arguments but only as keyword arguments.
111 116
112 `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`,
113 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
114 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
115 is ready to use, which is the default behavior. 120 is ready to use, which is the default behavior.
116 121
117 ## bundle-install 122 ## bundle-install
118 123
119 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
120 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
121 following syntax. 126 following syntax.
122 127
123 bundle-install [--update] 128 bundle-install [--update]
124 129
125 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
126 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
127 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
128 not already installed. 133 not already installed.
129 134
130 ## bundle-install! 135 ## bundle-install!
131 136
132 This is the same as running 137 This is the same as running
133 138
134 bundle-install --update 139 bundle-install --update
135 140
136 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
137 available versions. 142 available versions.
138 143
139 ## bundle-cleanup 144 ## bundle-cleanup
140 145
141 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
142 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`
143 command, and will ask you if you want to delete them. 148 command, and will ask you if you want to delete them.
144 149
145 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
146 pleasant to use it in your `.zshrc`. 151 pleasant to use it in your `.zshrc`.
147 152
148 ## bundle-lib 153 ## bundle-lib
149 154
150 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
151 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
152 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
153 158
154 bundle-lib 159 bundle-lib
155 160
156 in your `.zshrc`, before any `bundle` declarations. It takes no arguments. 161 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
157 162
158 ## bundle-theme 163 ## bundle-theme
159 164
160 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
161 want to use. 166 want to use.
162 167
163 bundle-theme fox 168 bundle-theme fox
164 169
165 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
166 support getting themes from other repos as well in the future. 171 support getting themes from other repos as well in the future.
167 172
168 # Configuration 173 # Configuration
169 174
170 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
171 antigen. Make sure you set them *before* sourceing `antigen.zsh`. 176 antigen. Make sure you set them *before* sourceing `antigen.zsh`.
172 177
173 `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
174 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,
175 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.
176 181
177 `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.
178 Defaults to `$HOME/.antigen/cache` 183 Defaults to `$HOME/.antigen/cache`
179 184
180 `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
181 from. Defaults to `$HOME/.antigen/bundles` 186 from. Defaults to `$HOME/.antigen/bundles`
182 187
183 # Meta 188 # Meta
184 189
185 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.
186 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.
187 192
188 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
189 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
190 consider opening an [issue][] first so we can discuss it out. 195 consider opening an [issue][] first so we can discuss it out.
191 196
192 [Vundle]: https://github.com/gmarik/vundle 197 [Vundle]: https://github.com/gmarik/vundle
193 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh 198 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
194 [issue]: https://github.com/sharat87/antigen/issues 199 [issue]: https://github.com/sharat87/antigen/issues
195 200