mj / zsh-config

Download as
Browse Code ยป

Commit b84833b4c7e71bdfbead84f65b4cb345a10cd91c

Authored by Shrikant Sharat
1 parent 1d001ec5f6

Add readme.

Showing 1 changed file with 194 additions and 0 deletions Inline Diff

File was created 1 # Antigen
2
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
5 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.
6
7 # Quick Usage
8
9 The usage should be very familiar to you if you use Vundle. A typical `.zshrc`
10 might look like this
11
12 source ~/labs/antigen/antigen.zsh
13
14 # Load the oh-my-zsh's library.
15 bundle-lib
16
17 # Bundles from the default repo (robbyrussell's oh-my-zsh).
18 bundle --loc=plugins/git
19 bundle --loc=plugins/heroku
20 bundle --loc=plugins/pip
21 bundle --loc=plugins/lein
22 bundle --loc=plugins/command-not-found
23
24 # Syntax highlighting bundle.
25 bundle zsh-users/zsh-syntax-highlighting
26
27 # Load the theme.
28 bundle-theme robbyrussell
29
30 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
32 on this page.
33
34 # Motivation
35
36 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
38 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
40 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.
42
43 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,
45 hoping to better this situation. Please note that I'm by no means a zsh or any
46 shell script expert (far from it).
47
48 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
49 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
50 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
51
52 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
54 only and you don't need to maintain your own fork and pull from upstream every
55 now and then.
56
57 Antigen also lets you switch the prompt theme with one command, just like that
58
59 bundle-theme candy
60
61 and your prompt is changed, just for this session of course.
62
63 # Commands
64
65 ## bundle
66
67 This is the command you use to tell antigen that you want to use a plugin. The
68 simplest usage follows the following syntax
69
70 bundle [<url> [<loc> [<name>]]]
71
72 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
74 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
76 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
78 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
80 arguments.
81
82 An example invocation would be
83
84 bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
85
86 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.
88
89 bundle robbyrussell/oh-my-zsh plugins/ant
90
91 And since this is the default, even that isn't necessary. But we can't specify
92 the `loc` without giving the first argument.
93
94 For this and a few other reasons, `bundle` also supports a simple keyword
95 argument syntax, using which we can rewrite the above as
96
97 bundle --loc=plugins/ant
98
99 Note that you can mix and match positional and keyword arguments. But you can't
100 have positional arguments after starting keyword arguments.
101
102 bundle robbyrussell/oh-my-zsh --loc=plugins/ant
103
104 And keyword arguments don't care about the order in which the arguments are
105 specified. The following is perfectly valid.
106
107 bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh --name=ant
108
109 In addition to the above discussed arguments, `bundle` also takes the following
110 arguments but only as keyword arguments.
111
112 `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
114 into the environment. But with `true`, the plugin is immediately sourced and
115 is ready to use, which is the default behavior.
116
117 ## bundle-install
118
119 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
121 following syntax.
122
123 bundle-install [--update]
124
125 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
127 plugins. It just installs them, if there is a cached copy available and if its
128 not already installed.
129
130 ## bundle-install!
131
132 This is the same as running
133
134 bundle-install --update
135
136 That is, it installs the recorded plugins, and updates them to the latest
137 available versions.
138
139 ## bundle-cleanup
140
141 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`
143 command, and will ask you if you want to delete them.
144
145 This command currently cannot run in a non-interactive mode. So it won't be very
146 pleasant to use it in your `.zshrc`.
147
148 ## bundle-lib
149
150 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
152 oh-my-zsh's library, which you very likely do, put a
153
154 bundle-lib
155
156 in your `.zshrc`, before any `bundle` declarations. It takes no arguments.
157
158 ## bundle-theme
159
160 Used for switching the prompt theme. Invoke it with the name of the theme you
161 want to use.
162
163 bundle-theme fox
164
165 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.
167
168 # Configuration
169
170 The following environment variables can be set to customize the behavior of
171 antigen. Make sure you set them *before* sourceing `antigen.zsh`.
172
173 `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,
175 but you can set this to the fork url of your own fork.
176
177 `ANTIGEN_REPO_CACHE` &mdash; This is where the cloned repositories are cached.
178 Defaults to `$HOME/.antigen/cache`
179
180 `ANTIGEN_BUNDLE_DIR` &mdash; This is where the plugins are installed and sourced
181 from. Defaults to `$HOME/.antigen/bundles`
182
183 # Meta
184
185 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.
187
188 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
190 consider opening an [issue][] first so we can discuss it out.
191
192 [Vundle]: https://github.com/gmarik/vundle
193 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
194 [issue]: https://github.com/sharat87/antigen/issues
195