mj / zsh-config

1

# Antigen β

1

# Antigen β

2

3

[![Build Status](https://secure.travis-ci.org/zsh-users/antigen.png)](http://travis-ci.org/zsh-users/antigen)

3

[![Build Status](https://secure.travis-ci.org/zsh-users/antigen.png)](http://travis-ci.org/zsh-users/antigen)

4

5

Antigen is a small set of functions that help you easily manage your shell (zsh)

5

Antigen is a small set of functions that help you easily manage your shell (zsh)

6

plugins, called bundles. The concept is pretty much the same as bundles in a

6

plugins, called bundles. The concept is pretty much the same as bundles in a

7

typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.

7

typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.

8

9

Please note that this is a very new project and can be considered beta at best.

9

Please note that this is a very new project and can be considered beta at best.

10

That said, I am using antigen full time now on my work machine.

10

That said, I am using antigen full time now on my work machine.

11

12

Note: Please read the commit comments of the changesets when you pull a new

12

Note: Please read the commit comments of the changesets when you pull a new

13

version of antigen.

13

version of antigen.

14

15

## Show off

15

## Show off

16

17

> Enough talk. Let's fight!

17

> Enough talk. Let's fight!

18

> -- Po, Kung-fu Panda.

18

> -- Po, Kung-fu Panda.

19

20

You're going to experience antigen right in your open shell. No `.zshrc`

20

You're going to experience antigen right in your open shell. No `.zshrc`

21

tweaking and reading the rest of this documentation. Kinda like an ice-cream

21

tweaking and reading the rest of this documentation. Kinda like an ice-cream

22

sample, if you will.

22

sample, if you will.

23

24

Get and load antigen.

24

Get and load antigen.

25

26

curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh

26

curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh

27

source antigen.zsh

27

source antigen.zsh

28

29

There. You now have all the antigen goodies. Let's try install some plugins. How

29

There. You now have all the antigen goodies. Let's try install some plugins. How

30

about some color to start with. Get the [syntax highlighting plugin][] by

30

about some color to start with. Get the [syntax highlighting plugin][] by

31

running

31

running

32

33

antigen bundle zsh-users/zsh-syntax-highlighting

33

antigen bundle zsh-users/zsh-syntax-highlighting

34

35

Now let it do its thing and once you're back at your prompt, try and type a

35

Now let it do its thing and once you're back at your prompt, try and type a

36

command. See that? Colors!

36

command. See that? Colors!

37

38

So, you do git? ruby? git and ruby? There are lots of awesome plugins over at

38

So, you do git? ruby? git and ruby? There are lots of awesome plugins over at

39

oh-my-zsh. Treat yourself to some.

39

oh-my-zsh. Treat yourself to some.

40

41

antigen bundle robbyrussell/oh-my-zsh plugins/ruby

41

antigen bundle robbyrussell/oh-my-zsh plugins/ruby

42

# Or for the lazy,

42

# Or for the lazy,

43

antigen bundle git

43

antigen bundle git

44

45

There are lots of plugins out there in the wild and people are writing zsh

45

There are lots of plugins out there in the wild and people are writing zsh

46

utilities as small scripts all the time. Antigen is compatible with all of them.

46

utilities as small scripts all the time. Antigen is compatible with all of them.

47

The plugins and scripts don't need any special handling to be compatible with

47

The plugins and scripts don't need any special handling to be compatible with

48

antigen.

48

antigen.

49

50

Another example, [kennethreitz's autoenv][autoenv] (or [my fork][f-autoenv] of

50

Another example, [kennethreitz's autoenv][autoenv] (or [my fork][f-autoenv] of

51

it). Just a bundle command away.

51

it). Just a bundle command away.

52

53

antigen bundle sharat87/autoenv

53

antigen bundle sharat87/autoenv

54

55

And boom! you have all the autoenv goodness. Just remember how you used to do

55

And boom! you have all the autoenv goodness. Just remember how you used to do

56

these before antigen, clone it, modify your zshrc to source it, load a new

56

these before antigen, clone it, modify your zshrc to source it, load a new

57

terminal, all just to test it out. Duh!

57

terminal, all just to test it out. Duh!

58

59

A subtle aspect of this is that you can tell antigen to grab just about anything

59

A subtle aspect of this is that you can tell antigen to grab just about anything

60

from anyone's `dotfiles` repo, as long as it is in a directory under any repo on

60

from anyone's `dotfiles` repo, as long as it is in a directory under any repo on

61

github.

61

github.

62

63

And themes? How would you like a fancy new prompt for yourself?

63

And themes? How would you like a fancy new prompt for yourself?

64

65

antigen theme funky

65

antigen theme funky

66

67

No? Not your taste? There are many themes available to you, check out the

67

No? Not your taste? There are many themes available to you, check out the

68

oh-my-zsh's [page on themes][].

68

oh-my-zsh's [page on themes][].

69

70

You can install themes from unofficial repos too!

70

You can install themes from unofficial repos too!

71

72

antigen theme XsErG/zsh-themes themes/lazyuser

72

antigen theme XsErG/zsh-themes themes/lazyuser

73

74

See? It's easy! To see how that works, refer to [the section on the

74

See? It's easy! To see how that works, refer to [the section on the

75

`antigen theme` command further down](#antigen-theme).

75

`antigen theme` command further down](#antigen-theme).

76

77

Note: Many of those plugins and especially themes, assume you have the core

77

Note: Many of those plugins and especially themes, assume you have the core

78

library of oh-my-zsh loaded. So, if you want to experiment further, issue a

78

library of oh-my-zsh loaded. So, if you want to experiment further, issue a

79

80

antigen use oh-my-zsh

80

antigen use oh-my-zsh

81

82

and continue until you're tired. At which point you can come back to this page

82

and continue until you're tired. At which point you can come back to this page

83

;)

83

;)

84

85

## Usage

85

## Usage

86

87

So, now that you're here, I suppose you are convinced and want antigen running

87

So, now that you're here, I suppose you are convinced and want antigen running

88

your shell all the time. Sweet. Let's do it.

88

your shell all the time. Sweet. Let's do it.

89

90

First, clone this repo, probably as a submodule if you have your dotfiles in a

90

First, clone this repo, probably as a submodule if you have your dotfiles in a

91

git repo,

91

git repo,

92

93

git clone https://github.com/zsh-users/antigen.git

93

git clone https://github.com/zsh-users/antigen.git

94

95

The usage should be very familiar to you if you use Vundle. A typical `.zshrc`

95

The usage should be very familiar to you if you use Vundle. A typical `.zshrc`

96

might look like this

96

might look like this

97

98

source /path-to-antigen clone/antigen.zsh

98

source /path-to-antigen clone/antigen.zsh

99

100

# Load the oh-my-zsh's library.

100

# Load the oh-my-zsh's library.

101

antigen use oh-my-zsh

101

antigen use oh-my-zsh

102

103

# Bundles from the default repo (robbyrussell's oh-my-zsh).

103

# Bundles from the default repo (robbyrussell's oh-my-zsh).

104

antigen bundle git

104

antigen bundle git

105

antigen bundle heroku

105

antigen bundle heroku

106

antigen bundle pip

106

antigen bundle pip

107

antigen bundle lein

107

antigen bundle lein

108

antigen bundle command-not-found

108

antigen bundle command-not-found

109

110

# Syntax highlighting bundle.

110

# Syntax highlighting bundle.

111

antigen bundle zsh-users/zsh-syntax-highlighting

111

antigen bundle zsh-users/zsh-syntax-highlighting

112

113

# Load the theme.

113

# Load the theme.

114

antigen theme robbyrussell

114

antigen theme robbyrussell

115

116

# Tell antigen that you're done.

116

# Tell antigen that you're done.

117

antigen apply

117

antigen apply

118

119

Open your zsh with this zshrc and you should see all the bundles you defined

119

Open your zsh with this zshrc and you should see all the bundles you defined

120

here, getting installed. Once its done, you are ready to roll. The complete

120

here, getting installed. Once its done, you are ready to roll. The complete

121

syntax for the `antigen bundle` command is discussed further down on this page.

121

syntax for the `antigen bundle` command is discussed further down on this page.

122

123

You can find more examples in the wiki: [Antigen in the wild][wild].

123

You can find more examples in the wiki: [Antigen in the wild][wild].

124

125

## Motivation

125

## Motivation

126

127

If you use zsh and [oh-my-zsh][], you know that having many different plugins

127

If you use zsh and [oh-my-zsh][], you know that having many different plugins

128

that are developed by many different authors in a single (sub)repo is not very

128

that are developed by many different authors in a single (sub)repo is not very

129

easy to maintain. There are some really fantastic plugins and utilities in

129

easy to maintain. There are some really fantastic plugins and utilities in

130

oh-my-zsh, but having them all in a single repo doesn't really scale well. And I

130

oh-my-zsh, but having them all in a single repo doesn't really scale well. And I

131

admire robbyrussell's efforts for reviewing and merging the gigantic number of

131

admire robbyrussell's efforts for reviewing and merging the gigantic number of

132

pull requests the project gets. We need a better way of plugin management.

132

pull requests the project gets. We need a better way of plugin management.

133

134

This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like

134

This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like

135

there was any progress made. So, I'm trying to start this off with antigen,

135

there was any progress made. So, I'm trying to start this off with antigen,

136

hoping to better this situation. Please note that I'm by no means a zsh or any

136

hoping to better this situation. Please note that I'm by no means a zsh or any

137

shell script expert (far from it).

137

shell script expert (far from it).

138

139

[1]: https://github.com/robbyrussell/oh-my-zsh/issues/465

139

[1]: https://github.com/robbyrussell/oh-my-zsh/issues/465

140

[2]: https://github.com/robbyrussell/oh-my-zsh/issues/377

140

[2]: https://github.com/robbyrussell/oh-my-zsh/issues/377

141

[3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014

141

[3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014

142

143

Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github

143

Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github

144

repositories. You are not limited to use plugins from the oh-my-zsh repository

144

repositories. You are not limited to use plugins from the oh-my-zsh repository

145

only and you don't need to maintain your own fork and pull from upstream every

145

only and you don't need to maintain your own fork and pull from upstream every

146

now and then. I actually encourage you to grab plugins and scripts from various

146

now and then. I actually encourage you to grab plugins and scripts from various

147

sources, straight from the authors, before they even submit it to oh-my-zsh as a

147

sources, straight from the authors, before they even submit it to oh-my-zsh as a

148

pull request.

148

pull request.

149

150

Antigen also lets you switch the prompt theme with one command, just like that

150

Antigen also lets you switch the prompt theme with one command, just like that

151

152

antigen theme candy

152

antigen theme candy

153

154

and your prompt is changed, just for this session of course (unless you put this

154

and your prompt is changed, just for this session of course (unless you put this

155

line in your `.zshrc`).

155

line in your `.zshrc`).

156

157

## Commands

157

## Commands

158

159

### antigen bundle

159

### antigen bundle

160

161

This command tells antigen to install (if not already installed) and load the

161

This command tells antigen to install (if not already installed) and load the

162

given plugin. The simplest usage follows the following syntax.

162

given plugin. The simplest usage follows the following syntax.

163

164

antigen bundle <plugin-name>

164

antigen bundle <plugin-name>

165

166

This will install and load the `plugins/<name>` directory from [robbyrussell's

166

This will install and load the `plugins/<name>` directory from [robbyrussell's

167

oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).

167

oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).

168

169

However, the above is just syntax sugar for the extended syntax of the

169

However, the above is just syntax sugar for the extended syntax of the

170

`antigen bundle` command.

170

`antigen bundle` command.

171

172

antigen bundle [<url> [<loc>]]

172

antigen bundle [<url> [<loc>]]

173

174

where `<url>` is the repository url and it defaults to [robbyrussell's

174

where `<url>` is the repository url and it defaults to [robbyrussell's

175

oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`

175

oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`

176

discussed further down). `<loc>` is the path under this repository which has the

176

discussed further down). `<loc>` is the path under this repository which has the

177

zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,

177

zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,

178

but it could contain a completion file or just many `*.zsh` files to be sourced.

178

but it could contain a completion file or just many `*.zsh` files to be sourced.

179

`<loc>` defaults to `/`, which indicates the repository itself is a plugin.

179

`<loc>` defaults to `/`, which indicates the repository itself is a plugin.

180

181

An example invocation would be

181

An example invocation would be

182

183

# The following is the same as `antigen bundle ant`. But for demonstration

183

# The following is the same as `antigen bundle ant`. But for demonstration

184

# purposes, we use the extended syntax here.

184

# purposes, we use the extended syntax here.

185

antigen bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant

185

antigen bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant

186

187

This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,

187

This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,

188

github url's can be shortened.

188

github url's can be shortened.

189

190

antigen bundle robbyrussell/oh-my-zsh plugins/ant

190

antigen bundle robbyrussell/oh-my-zsh plugins/ant

191

192

And since this repo is the default, even that isn't necessary. But we can't

192

And since this repo is the default, even that isn't necessary. But we can't

193

specify the `loc` without giving the first argument.

193

specify the `loc` without giving the first argument.

194

195

For this and a few other reasons, `antigen bundle` also supports a simple

195

For this and a few other reasons, `antigen bundle` also supports a simple

196

keyword argument syntax, using which we can rewrite the above as

196

keyword argument syntax, using which we can rewrite the above as

197

198

antigen bundle --loc=plugins/ant

198

antigen bundle --loc=plugins/ant

199

200

Which picks up the default for the `url` argument, and uses the `loc` given to

200

Which picks up the default for the `url` argument, and uses the `loc` given to

201

it.

201

it.

202

203

*Note* that you can mix and match positional and keyword arguments. But you

203

*Note* that you can mix and match positional and keyword arguments. But you

204

can't have positional arguments after keyword arguments.

204

can't have positional arguments after keyword arguments.

205

206

antigen bundle robbyrussell/oh-my-zsh --loc=plugins/ant

206

antigen bundle robbyrussell/oh-my-zsh --loc=plugins/ant

207

208

And keyword arguments don't care about the order in which the arguments are

208

And keyword arguments don't care about the order in which the arguments are

209

specified. The following is perfectly valid.

209

specified. The following is perfectly valid.

210

211

antigen bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh

211

antigen bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh

212

213

You can also specify a local directory on your file system as a bundle. In this

213

You can also specify a local directory on your file system as a bundle. In this

214

case, make sure the path you give is the absolute path (i.e., starts with a

214

case, make sure the path you give is the absolute path (i.e., starts with a

215

`/`). Relative paths are not supported. If the repo you gave is a local

215

`/`). Relative paths are not supported. If the repo you gave is a local

216

directory path, then it is not necessary that this path is a git repo. Please

216

directory path, then it is not necessary that this path is a git repo. Please

217

refer to the notes on `--no-local-clone` below.

217

refer to the notes on `--no-local-clone` below.

218

219

This command can also be used from your shell environment. This allows you to

219

This command can also be used from your shell environment. This allows you to

220

install plugins on the fly and try them out. Of course if you want a bundle to

220

install plugins on the fly and try them out. Of course if you want a bundle to

221

be available every time you open a shell, put it in your `.zshrc`.

221

be available every time you open a shell, put it in your `.zshrc`.

222

223

Other keyword-only arguments accepted:

223

Other keyword-only arguments accepted:

224

225

`--branch={git-branch-name}` — Specify the branch of the git repo to be

225

`--branch={git-branch-name}` — Specify the branch of the git repo to be

226

used for this bundle (without the braces of course). The default is whatever

226

used for this bundle (without the braces of course). The default is whatever

227

branch the clone comes with, which is usually `master`. For example,

227

branch the clone comes with, which is usually `master`. For example,

228

229

antigen bundle github-user/repo --branch=develop

229

antigen bundle github-user/repo --branch=develop

230

231

This will get the plugin as in the branch `develop`.

231

This will get the plugin as in the branch `develop`.

232

233

Note that if you specify two plugins to be loaded from the same git repo, but

233

Note that if you specify two plugins to be loaded from the same git repo, but

234

different branches, then two separate clones of this repo will be maintained.

234

different branches, then two separate clones of this repo will be maintained.

235

This is a small implementation detail and shouldn't influence you in any way.

235

This is a small implementation detail and shouldn't influence you in any way.

236

237

`--no-local-clone` — This command can be useful if you are developing a

237

`--no-local-clone` — This command can be useful if you are developing a

238

plugin and already have a clone on your local file system. If this argument is

238

plugin and already have a clone on your local file system. If this argument is

239

not given, even if the given repo url is a local path, a clone is made in the

239

not given, even if the given repo url is a local path, a clone is made in the

240

`$ADOTDIR/repos`, and the plugin is loaded from that clone. But, if you give

240

`$ADOTDIR/repos`, and the plugin is loaded from that clone. But, if you give

241

this argument, the plugin is sourced straight from the repo location, without

241

this argument, the plugin is sourced straight from the repo location, without

242

creating a clone. For example,

242

creating a clone. For example,

243

244

antigen bundle /absolute/path/to/the/plugin --no-local-clone

244

antigen bundle /absolute/path/to/the/plugin --no-local-clone

245

246

Note that if the repo url is *not* an absolute local path or a branch has been

246

Note that if the repo url is *not* an absolute local path or a branch has been

247

specified with the `--branch` option, this argument has no effect. That is,

247

specified with the `--branch` option, this argument has no effect. That is,

248

for this option to have any affect, the repo url must be an absolute local path

248

for this option to have any affect, the repo url must be an absolute local path

249

and no `--branch` should be specified.

249

and no `--branch` should be specified.

250

251

Also, if the local path given as the url is not a git repo, then this

251

Also, if the local path given as the url is not a git repo, then this

252

argument is forced as it doesn't makes sense to *clone* something that's not a

252

argument is forced as it doesn't makes sense to *clone* something that's not a

253

git repo. This property can be used to load any utility scripts you have in your

253

git repo. This property can be used to load any utility scripts you have in your

254

dotfiles repo. For example,

254

dotfiles repo. For example,

255

256

antigen bundle $HOME/dotfiles/oh-my-zsh/custom

256

antigen bundle $HOME/dotfiles/oh-my-zsh/custom

257

258

In addition to the above discussed arguments, `antigen bundle` also takes a

258

In addition to the above discussed arguments, `antigen bundle` also takes a

259

`btype` keyword-only argument, that is used internally. You shouldn't be

259

`btype` keyword-only argument, that is used internally. You shouldn't be

260

concerned with this argument, its only used internally and will probably go away

260

concerned with this argument, its only used internally and will probably go away

261

in the future. It indicates whether the bundle is a theme or a simple plugin.

261

in the future. It indicates whether the bundle is a theme or a simple plugin.

262

263

### antigen bundles

263

### antigen bundles

264

265

If you have a fair number of bundles, using the `antigen bundle` command can

265

If you have a fair number of bundles, using the `antigen bundle` command can

266

look cumbersome. You can use the `antigen bundles` command to *bulk* define

266

look cumbersome. You can use the `antigen bundles` command to *bulk* define

267

bundles instead of individual calls to `antigen bundle`.

267

bundles instead of individual calls to `antigen bundle`.

268

269

Usage is pretty straightforward. Just pipe the bundle specifications, just as

269

Usage is pretty straightforward. Just pipe the bundle specifications, just as

270

you would give to the `antigen bundle` command, one per line, into the

270

you would give to the `antigen bundle` command, one per line, into the

271

`antigen bundles` command. The easiest way to do this, is using the heredoc

271

`antigen bundles` command. The easiest way to do this, is using the heredoc

272

syntax.

272

syntax.

273

274

antigen bundles <<EOBUNDLES

274

antigen bundles <<EOBUNDLES

275

# Guess what to install when running an unknown command.

275

# Guess what to install when running an unknown command.

276

command-not-found

276

command-not-found

277

278

# The heroku tool helper plugin.

278

# The heroku tool helper plugin.

279

heroku

279

heroku

280

EOBUNDLES

280

EOBUNDLES

281

282

This is equivalent to

282

This is equivalent to

283

284

antigen bundle command-not-found

284

antigen bundle command-not-found

285

antigen bundle heroku

285

antigen bundle heroku

286

287

Of course, as you can see, from the lines piped to `antigen bundles`, empty

287

Of course, as you can see, from the lines piped to `antigen bundles`, empty

288

lines and those starting with a `#` are ignored. The rest are passed to

288

lines and those starting with a `#` are ignored. The rest are passed to

289

`antigen bundle` without any quoting rules applied. They are actually `eval`-ed

289

`antigen bundle` without any quoting rules applied. They are actually `eval`-ed

290

with the `antigen bundle` command. See the source if you want to really

290

with the `antigen bundle` command. See the source if you want to really

291

understand how it works. Its a very small function.

291

understand how it works. Its a very small function.

292

293

*Note*: Indenting the contents inside the EOBUNDLES heredoc is not required for

293

*Note*: Indenting the contents inside the EOBUNDLES heredoc is not required for

294

antigen-bundles to work. Its allowed (and encouraged) to improve readability.

294

antigen-bundles to work. Its allowed (and encouraged) to improve readability.

295

296

### antigen update

296

### antigen update

297

298

This is something you might not want to put in your `.zshrc`. Instead, run it

298

This is something you might not want to put in your `.zshrc`. Instead, run it

299

occasionally to update all your plugins. It doesn't take any arguments.

299

occasionally to update all your plugins. It doesn't take any arguments.

300

301

antigen update

301

antigen update

302

303

Please note that the updates that are downloaded are not immediately available.

303

Please note that the updates that are downloaded are not immediately available.

304

You have to open a new shell to be able to see the changes. This is a limitation

304

You have to open a new shell to be able to see the changes. This is a limitation

305

by design since reloading all the plugins *might* have some nasty side effects

305

by design since reloading all the plugins *might* have some nasty side effects

306

that may not be immediately apparent. Let's just say it can make your shell act

306

that may not be immediately apparent. Let's just say it can make your shell act

307

real quirky.

307

real quirky.

308

309

**Please note**: This command is not for updating *antigen* itself. Its for

309

**Please note**: This command is not for updating *antigen* itself. Its for

310

updating the bundles you are using with antigen. To update your copy of antigen,

310

updating the bundles you are using with antigen. To update your copy of antigen,

311

use the `selfupdate` command described further below.

311

use the `selfupdate` command described further below.

312

313

### antigen revert α

313

### antigen revert α

314

315

Reverts the state of all your plugins to how they were before the last

315

Reverts the state of all your plugins to how they were before the last

316

`antigen update`. This command is currently experimental, so don't rely too much

316

`antigen update`. This command is currently experimental, so don't rely too much

317

on it. There is a test for it, and it passes, so it should work fine though.

317

on it. There is a test for it, and it passes, so it should work fine though.

318

319

Takes no options.

319

Takes no options.

320

321

Insider detail: The information for reverting is stored in

321

Insider detail: The information for reverting is stored in

322

`$ADOTDIR/revert-info` file. If its not present, reverting is not possible.

322

`$ADOTDIR/revert-info` file. If its not present, reverting is not possible.

323

324

### antigen list

324

### antigen list

325

326

Use this command to list out the currently *loaded* plugins. Keep in mind that

326

Use this command to list out the currently *loaded* plugins. Keep in mind that

327

this includes any bundles installed on-the-fly.

327

this includes any bundles installed on-the-fly.

328

329

Takes no arguments. Gives out four entries per line of output, denoting the

329

Takes no arguments. Gives out four entries per line of output, denoting the

330

following fields of each bundle.

330

following fields of each bundle.

331

332

<repo-url> <loc> <btype> <has-local-clone?>

332

<repo-url> <loc> <btype> <has-local-clone?>

333

334

The `btype` field is an internal detail, that specifies if the bundle is a

334

The `btype` field is an internal detail, that specifies if the bundle is a

335

`plugin` or a `theme`.

335

`plugin` or a `theme`.

336

337

The final field is `true` or `false` reflecting whether there is a local clone

337

The final field is `true` or `false` reflecting whether there is a local clone

338

for this bundle.

338

for this bundle.

339

340

### antigen cleanup

340

### antigen cleanup

341

342

Used to clean up the clones of repos which are not used by any plugins currently

342

Used to clean up the clones of repos which are not used by any plugins currently

343

loaded. It takes no arguments. When run, it lists out the repo-clones that are

343

loaded. It takes no arguments. When run, it lists out the repo-clones that are

344

available but are not used by any plugin *currently loaded*.

344

available but are not used by any plugin *currently loaded*.

345

346

This command, by default asks for confirmation before deleting the unused

346

This command, by default asks for confirmation before deleting the unused

347

clones. If the `--force` argument is given, then this confirmation is not asked.

347

clones. If the `--force` argument is given, then this confirmation is not asked.

348

It straight away deletes all the unused clones. This option makes this command

348

It straight away deletes all the unused clones. This option makes this command

349

usable in a non-interactive fashion.

349

usable in a non-interactive fashion.

350

351

### antigen use

351

### antigen use

352

353

This command lets you load any (supported) zsh pre-packaged framework, like

353

This command lets you load any (supported) zsh pre-packaged framework, like

354

oh-my-zsh. Usage is

354

oh-my-zsh. Usage is

355

356

antigen use oh-my-zsh

356

antigen use oh-my-zsh

357

358

Additional arguments may be present depending on the framework you are

358

Additional arguments may be present depending on the framework you are

359

`use`-ing. Here are the supported frameworks.

359

`use`-ing. Here are the supported frameworks.

360

361

#### oh-my-zsh

361

#### oh-my-zsh

362

363

This is (almost) the same as

363

This is (almost) the same as

364

365

antigen bundle --loc=lib

365

antigen bundle --loc=lib

366

367

So, it basically installs the oh-my-zsh's library as a bundle.

367

So, it basically installs the oh-my-zsh's library as a bundle.

368

369

One other thing it does is that some oh-my-zsh plugins expect a `$ZSH` set to

369

One other thing it does is that some oh-my-zsh plugins expect a `$ZSH` set to

370

the full path of the oh-my-zsh clone being used. This is also set to the

370

the full path of the oh-my-zsh clone being used. This is also set to the

371

correct path, if not already set to something else.

371

correct path, if not already set to something else.

372

373

Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the

373

Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the

374

oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too,

374

oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too,

375

then you can't use the `antigen use oh-my-zsh` short cut. You have to do that

375

then you can't use the `antigen use oh-my-zsh` short cut. You have to do that

376

directly with the `antigen bundle` command.

376

directly with the `antigen bundle` command.

377

378

Use

378

Use

379

380

antigen use oh-my-zsh

380

antigen use oh-my-zsh

381

382

in your `.zshrc`, before any `antigen bundle` declarations. It takes no further

382

in your `.zshrc`, before any `antigen bundle` declarations. It takes no further

383

arguments.

383

arguments.

384

385

#### prezto

385

#### prezto

386

387

This is (almost, but not quite) the same as doing,

387

This is (almost, but not quite) the same as doing,

388

389

antigen bundle sorin-ionescu/prezto

389

antigen bundle sorin-ionescu/prezto

390

391

That is, initializes the canonical repo of the prezto framework. Please note

391

That is, initializes the canonical repo of the prezto framework. Please note

392

that prezto support is very new and experimental in antigen. If you find any

392

that prezto support is very new and experimental in antigen. If you find any

393

bugs, please report over on github issues.

393

bugs, please report over on github issues.

394

395

Takes no further arguments.

395

Takes no further arguments.

396

397

### antigen theme

397

### antigen theme

398

399

Used for switching the prompt theme. Invoke it with the name of the theme you

399

Used for switching the prompt theme. Invoke it with the name of the theme you

400

want to use.

400

want to use.

401

402

antigen theme fox

402

antigen theme fox

403

404

This will get the theme file located at `themes/fox.zsh-theme` in the repo

404

This will get the theme file located at `themes/fox.zsh-theme` in the repo

405

specified by `ANTIGEN_DEFAULT_REPO_URL`.

405

specified by `ANTIGEN_DEFAULT_REPO_URL`.

406

407

To pull themes from other repositories, use `antigen theme` just like

407

To pull themes from other repositories, use `antigen theme` just like

408

`antigen bundle`. Exactly the same, just make sure the `url` and `loc`

408

`antigen bundle`. Exactly the same, just make sure the `url` and `loc`

409

combination point to a theme file, having a `.zsh-theme` extension.

409

combination point to a theme file, having a `.zsh-theme` extension.

410

411

For example,

411

For example,

412

413

antigen theme robbyrussell/oh-my-zsh themes/apple

413

antigen theme robbyrussell/oh-my-zsh themes/apple

414

415

Will pull the apple theme from the canonical oh-my-zsh repo. Also, note that the

415

Will pull the apple theme from the canonical oh-my-zsh repo. Also, note that the

416

`.zsh-theme` extension is not present. It can be given, its optional.

416

`.zsh-theme` extension is not present. It can be given, its optional.

417

418

To get themes from arbitrary git repos (such as gists) use,

419

420

antigen theme https://gist.github.com/3750104.git agnoster

421

418

You can use this command to change your theme on the fly in your shell. Go on,

422

You can use this command to change your theme on the fly in your shell. Go on,

419

try out a few themes in your shell before you set it in your `.zshrc`.

423

try out a few themes in your shell before you set it in your `.zshrc`.

420

424

421

**Note**: Some themes use functions that are loaded by `antigen use oh-my-zsh`.

425

**Note**: Some themes use functions that are loaded by `antigen use oh-my-zsh`.

422

So, to avoid any trouble, run `antigen use oh-my-zsh` if you haven't already

426

So, to avoid any trouble, run `antigen use oh-my-zsh` if you haven't already

423

before experimenting with themes. If you have `antigen use oh-my-zsh` in your

427

before experimenting with themes. If you have `antigen use oh-my-zsh` in your

424

`.zshrc`, you're covered.

428

`.zshrc`, you're covered.

425

429

426

**Note**: Do *not* provide the `--btype` argument to `antigen theme`. Its an

430

**Note**: Do *not* provide the `--btype` argument to `antigen theme`. Its an

427

internal argument.

431

internal argument.

428

432

429

### antigen apply

433

### antigen apply

430

434

431

You have to add this command after defining all bundles you need, in your zshrc.

435

You have to add this command after defining all bundles you need, in your zshrc.

432

The completions defined by your bundles will be loaded at this step.

436

The completions defined by your bundles will be loaded at this step.

433

437

434

It is possible to load completions as and when a bundle is specified with the

438

It is possible to load completions as and when a bundle is specified with the

435

bundle command, in which case this command would not be necessary. But loading

439

bundle command, in which case this command would not be necessary. But loading

436

the completions is a time-consuming process, so if the completions were loaded

440

the completions is a time-consuming process, so if the completions were loaded

437

at every call to `antigen bundle`, your shell will start noticeably slow when

441

at every call to `antigen bundle`, your shell will start noticeably slow when

438

you have a good number of bundle specifications.

442

you have a good number of bundle specifications.

439

443

440

However, if you can suggest a way so that this would not be necessary, I am very

444

However, if you can suggest a way so that this would not be necessary, I am very

441

interested in discussing it. Please open up an issue with your details. Thanks.

445

interested in discussing it. Please open up an issue with your details. Thanks.

442

446

443

### antigen snapshot α

447

### antigen snapshot α

444

448

445

Creates a snapshot of all the clones you currently have *active* including the

449

Creates a snapshot of all the clones you currently have *active* including the

446

git version hash they are at and save it to a snapshot file. *Active* means, the

450

git version hash they are at and save it to a snapshot file. *Active* means, the

447

clones for those listed by `antigen cleanup` are not included in the snapshot.

451

clones for those listed by `antigen cleanup` are not included in the snapshot.

448

452

449

Takes one optional argument, the file name in which the snapshot is to be saved.

453

Takes one optional argument, the file name in which the snapshot is to be saved.

450

Defaults to `antigen snapshot`.

454

Defaults to `antigen snapshot`.

451

455

452

**Note**: The snapshot currently *only* contains the details of those bundles

456

**Note**: The snapshot currently *only* contains the details of those bundles

453

that have a clone. That is, bundles that have `--no-local-clone` set or are

457

that have a clone. That is, bundles that have `--no-local-clone` set or are

454

directly sourced from your file system (without a git repo), are not recorded

458

directly sourced from your file system (without a git repo), are not recorded

455

in the snapshot file.

459

in the snapshot file.

456

460

457

### antigen restore α

461

### antigen restore α

458

462

459

Restore the bundles state as specified in the snapshot. Takes one required

463

Restore the bundles state as specified in the snapshot. Takes one required

460

argument, the snapshot file name to read.

464

argument, the snapshot file name to read.

461

465

462

Although it restores the clones of the repos specified in the snapshot file, any

466

Although it restores the clones of the repos specified in the snapshot file, any

463

other clones present in your environment are not touched. This behavior may

467

other clones present in your environment are not touched. This behavior may

464

change in the future.

468

change in the future.

465

469

466

### antigen selfupdate

470

### antigen selfupdate

467

471

468

Use this command to update your copy of antigen. It basically does a `git pull`

472

Use this command to update your copy of antigen. It basically does a `git pull`

469

on your antigen's clone, *if* it is a git clone. Otherwise, it doesn't do

473

on your antigen's clone, *if* it is a git clone. Otherwise, it doesn't do

470

anything.

474

anything.

471

475

472

Takes no options.

476

Takes no options.

473

477

474

### antigen help

478

### antigen help

475

479

476

This exists so that there can be some help right in the command line. Currently

480

This exists so that there can be some help right in the command line. Currently

477

it doesn't provide much help other than redirecting you to the project page for

481

it doesn't provide much help other than redirecting you to the project page for

478

documentation. It is intended to provide more meaning and sub-command specific

482

documentation. It is intended to provide more meaning and sub-command specific

479

help in the future.

483

help in the future.

480

484

481

I could use some help here as I'm not that good at writing documentation that

485

I could use some help here as I'm not that good at writing documentation that

482

looks good as output on the command line.

486

looks good as output on the command line.

483

487

484

## Configuration

488

## Configuration

485

489

486

The following environment variables can be set to customize the behavior of

490

The following environment variables can be set to customize the behavior of

487

antigen. Make sure you set them *before* source-ing `antigen.zsh`.

491

antigen. Make sure you set them *before* source-ing `antigen.zsh`.

488

492

489

`ANTIGEN_DEFAULT_REPO_URL` — This is the default repository url that is

493

`ANTIGEN_DEFAULT_REPO_URL` — This is the default repository url that is

490

used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,

494

used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,

491

but you can set this to the fork url of your own fork.

495

but you can set this to the fork url of your own fork.

492

496

493

`ADOTDIR` — This directory is used to store all the repo clones, your

497

`ADOTDIR` — This directory is used to store all the repo clones, your

494

bundles, themes, caches and everything else antigen requires to run smoothly.

498

bundles, themes, caches and everything else antigen requires to run smoothly.

495

Defaults to `$HOME/.antigen`.

499

Defaults to `$HOME/.antigen`.

496

500

497

**Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` — These variables

501

**Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` — These variables

498

were used previously but are now removed. Please use `ADOTDIR` instead, as

502

were used previously but are now removed. Please use `ADOTDIR` instead, as

499

mentioned above.

503

mentioned above.

500

504

501

## Running the tests

505

## Running the tests

502

506

503

All the tests are in the `tests` folder and are run using the [cram][] test

507

All the tests are in the `tests` folder and are run using the [cram][] test

504

system. The latest version on that website, as of today is v0.5, which does not

508

system. The latest version on that website, as of today is v0.5, which does not

505

have the `--shell` argument which is required to run our tests. So, to get the

509

have the `--shell` argument which is required to run our tests. So, to get the

506

correct version of cram, run

510

correct version of cram, run

507

511

508

pip install -r requirements.txt

512

pip install -r requirements.txt

509

513

510

With that, once you have cram installed, you can run the tests as

514

With that, once you have cram installed, you can run the tests as

511

515

512

make

516

make

513

517

514

If you are making a feature addition, I'd really appreciate if you can add a

518

If you are making a feature addition, I'd really appreciate if you can add a

515

test for your feature. Even if you can add a test for an existing feature, that

519

test for your feature. Even if you can add a test for an existing feature, that

516

would be great as the tests are currently seriously lagging behind the full

520

would be great as the tests are currently seriously lagging behind the full

517

functionality of antigen.

521

functionality of antigen.

518

522

519

## Notes on writing plugins

523

## Notes on writing plugins

520

524

521

Most shell utilities/plugins are made up of just one file. For a plugin called

525

Most shell utilities/plugins are made up of just one file. For a plugin called

522

`awesomeness`, create a `awesomeness.plugin.zsh` and code away.

526

`awesomeness`, create a `awesomeness.plugin.zsh` and code away.

523

527

524

That said, even if you write a single file as a `.sh` file with the goodness you

528

That said, even if you write a single file as a `.sh` file with the goodness you

525

want to create, antigen will work just fine with it. The `*.plugin.zsh` way is

529

want to create, antigen will work just fine with it. The `*.plugin.zsh` way is

526

recommended by antigen, because it is widely used because of the [oh-my-zsh][]

530

recommended by antigen, because it is widely used because of the [oh-my-zsh][]

527

project.

531

project.

528

532

529

If you want to know how antigen loads the plugins, do continue.

533

If you want to know how antigen loads the plugins, do continue.

530

534

531

Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If

535

Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If

532

present, it will source *only* this script. Nothing else is sourced. This is for

536

present, it will source *only* this script. Nothing else is sourced. This is for

533

oh-my-zsh style plugins.

537

oh-my-zsh style plugins.

534

538

535

Secondly, it looks for a `init.zsh` file in the plugin directory. If present, it

539

Secondly, it looks for a `init.zsh` file in the plugin directory. If present, it

536

will source *only* this script. Nothing else is sourced. This is for prezto

540

will source *only* this script. Nothing else is sourced. This is for prezto

537

style modules.

541

style modules.

538

542

539

Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are

543

Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are

540

sourced. The order in which they are sourced is not currently defined. Please

544

sourced. The order in which they are sourced is not currently defined. Please

541

don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.

545

don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.

542

546

543

If no `*.zsh` files are present, it finally looks for any `*.sh` files and

547

If no `*.zsh` files are present, it finally looks for any `*.sh` files and

544

sources *all* of them. Again, the order in which they are sourced in not

548

sources *all* of them. Again, the order in which they are sourced in not

545

currently defined.

549

currently defined.

546

550

547

No matter which (or none) of the above happen to be sourced, this plugin

551

No matter which (or none) of the above happen to be sourced, this plugin

548

directory is added to the zsh's function path (`$fpath`) so that any completions

552

directory is added to the zsh's function path (`$fpath`) so that any completions

549

in it are loaded.

553

in it are loaded.

550

554

551

One exception to this rule is that if this plugin is a theme. In which case the

555

One exception to this rule is that if this plugin is a theme. In which case the

552

theme script is just sourced and nothing else is done. Not even adding to

556

theme script is just sourced and nothing else is done. Not even adding to

553

`$fpath`.

557

`$fpath`.

554

558

555

## A note on external zsh plugins

559

## A note on external zsh plugins

556

560

557

Antigen downloads zsh scripts and sources them, according to your

561

Antigen downloads zsh scripts and sources them, according to your

558

specifications. As such, these scripts are capable of doing some *real* damage

562

specifications. As such, these scripts are capable of doing some *real* damage

559

to your system. If you are only downloading scripts from oh-my-zsh and/or

563

to your system. If you are only downloading scripts from oh-my-zsh and/or

560

prezto, you're probably fine, since there is a second level of manual checking

564

prezto, you're probably fine, since there is a second level of manual checking

561

before a script gets into the framework.

565

before a script gets into the framework.

562

566

563

But, if you are adding a script from any other source, please check the source

567

But, if you are adding a script from any other source, please check the source

564

code of the plugin to see its not doing anything malicious, before adding it to

568

code of the plugin to see its not doing anything malicious, before adding it to

565

your `.zshrc`.

569

your `.zshrc`.

566

570

567

## Meta

571

## Meta

568

572

569

### Helping out

573

### Helping out

570

574

571

Antigen is licensed with the [MIT License][license].

575

Antigen is licensed with the [MIT License][license].

572

576

573

To contribute, please read the [contributing wiki page][contributing] before

577

To contribute, please read the [contributing wiki page][contributing] before

574

sending pull requests. If its a long/complicated change, please consider opening

578

sending pull requests. If its a long/complicated change, please consider opening

575

an [issue][] first so we can discuss it out. Thanks!

579

an [issue][] first so we can discuss it out. Thanks!

576

580

577

### Feedback please

581

### Feedback please

578

582

579

Any comments/suggestions/feedback welcome. Please say hello to me

583

Any comments/suggestions/feedback welcome. Please say hello to me

580

([@sharat87][twitter]) on twitter. Or open an issue to discuss something

584

([@sharat87][twitter]) on twitter. Or open an issue to discuss something

581

(anything!) about the project ;).

585

(anything!) about the project ;).

582

586

583

587

584

[Vundle]: https://github.com/gmarik/vundle

588

[Vundle]: https://github.com/gmarik/vundle

585

[page on themes]: https://github.com/robbyrussell/oh-my-zsh/wiki/Themes

589

[page on themes]: https://github.com/robbyrussell/oh-my-zsh/wiki/Themes

586

[wild]: https://github.com/zsh-users/antigen/wiki/In-the-wild

590

[wild]: https://github.com/zsh-users/antigen/wiki/In-the-wild

587

[syntax highlighting plugin]: https://github.com/zsh-users/zsh-syntax-highlighting

591

[syntax highlighting plugin]: https://github.com/zsh-users/zsh-syntax-highlighting

588

[autoenv]: https://github.com/kennethreitz/autoenv

592

[autoenv]: https://github.com/kennethreitz/autoenv

589

[f-autoenv]: https://github.com/sharat87/autoenv

593

[f-autoenv]: https://github.com/sharat87/autoenv

590

[oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh

594

[oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh

591

[cram]: https://bitheap.org/cram/

595

[cram]: https://bitheap.org/cram/

592

[issue]: https://github.com/zsh-users/antigen/issues

596

[issue]: https://github.com/zsh-users/antigen/issues

593

[license]: http://mit.sharats.me

597

[license]: http://mit.sharats.me

594

[contributing]: https://github.com/zsh-users/antigen/wiki/Contributing

598

[contributing]: https://github.com/zsh-users/antigen/wiki/Contributing

595

[twitter]: http://twitter.com/sharat87

599

[twitter]: http://twitter.com/sharat87

596

600

GITLAB

mj / zsh-config

Adding explanation for theme command and generic git repos

 # Antigen <sup>&beta;</sup>
 [![Build Status](https://secure.travis-ci.org/zsh-users/antigen.png)](http://travis-ci.org/zsh-users/antigen)
 Antigen is a small set of functions that help you easily manage your shell (zsh)
 plugins, called bundles. The concept is pretty much the same as bundles in a
 typical vim+pathogen setup. Antigen is to zsh, what [Vundle][] is to vim.
 Please note that this is a very new project and can be considered beta at best.
 That said, I am using antigen full time now on my work machine.
 Note: Please read the commit comments of the changesets when you pull a new
 version of antigen.
 ## Show off
 > Enough talk. Let's fight!
 >   -- Po, Kung-fu Panda.
 You're going to experience antigen right in your open shell. No `.zshrc`
 tweaking and reading the rest of this documentation. Kinda like an ice-cream
 sample, if you will.
 Get and load antigen.
     curl https://raw.github.com/zsh-users/antigen/master/antigen.zsh > antigen.zsh
     source antigen.zsh
 There. You now have all the antigen goodies. Let's try install some plugins. How
 about some color to start with. Get the [syntax highlighting plugin][] by
 running
     antigen bundle zsh-users/zsh-syntax-highlighting
 Now let it do its thing and once you're back at your prompt, try and type a
 command. See that? Colors!
 So, you do git? ruby? git and ruby? There are lots of awesome plugins over at
 oh-my-zsh. Treat yourself to some.
     antigen bundle robbyrussell/oh-my-zsh plugins/ruby
     # Or for the lazy,
     antigen bundle git
 There are lots of plugins out there in the wild and people are writing zsh
 utilities as small scripts all the time. Antigen is compatible with all of them.
 The plugins and scripts don't need any special handling to be compatible with
 antigen.
 Another example, [kennethreitz's autoenv][autoenv] (or [my fork][f-autoenv] of
 it). Just a bundle command away.
     antigen bundle sharat87/autoenv
 And boom! you have all the autoenv goodness. Just remember how you used to do
 these before antigen, clone it, modify your zshrc to source it, load a new
 terminal, all just to test it out. Duh!
 A subtle aspect of this is that you can tell antigen to grab just about anything
 from anyone's `dotfiles` repo, as long as it is in a directory under any repo on
 github.
 And themes? How would you like a fancy new prompt for yourself?
     antigen theme funky
 No? Not your taste? There are many themes available to you, check out the
 oh-my-zsh's [page on themes][].
 You can install themes from unofficial repos too!
     antigen theme XsErG/zsh-themes themes/lazyuser
 See? It's easy! To see how that works, refer to [the section on the
 `antigen theme` command further down](#antigen-theme).
 Note: Many of those plugins and especially themes, assume you have the core
 library of oh-my-zsh loaded. So, if you want to experiment further, issue a
     antigen use oh-my-zsh
 and continue until you're tired. At which point you can come back to this page
 ;)
 ## Usage
 So, now that you're here, I suppose you are convinced and want antigen running
 your shell all the time. Sweet. Let's do it.
 First, clone this repo, probably as a submodule if you have your dotfiles in a
 git repo,
     git clone https://github.com/zsh-users/antigen.git
 The usage should be very familiar to you if you use Vundle. A typical `.zshrc`
 might look like this
     source /path-to-antigen clone/antigen.zsh
     # Load the oh-my-zsh's library.
     antigen use oh-my-zsh
     # Bundles from the default repo (robbyrussell's oh-my-zsh).
     antigen bundle git
     antigen bundle heroku
     antigen bundle pip
     antigen bundle lein
     antigen bundle command-not-found
     # Syntax highlighting bundle.
     antigen bundle zsh-users/zsh-syntax-highlighting
     # Load the theme.
     antigen theme robbyrussell
     # Tell antigen that you're done.
     antigen apply
 Open your zsh with this zshrc and you should see all the bundles you defined
 here, getting installed. Once its done, you are ready to roll. The complete
 syntax for the `antigen bundle` command is discussed further down on this page.
 You can find more examples in the wiki: [Antigen in the wild][wild].
 ## Motivation
 If you use zsh and [oh-my-zsh][], you know that having many different plugins
 that are developed by many different authors in a single (sub)repo is not very
 easy to maintain. There are some really fantastic plugins and utilities in
 oh-my-zsh, but having them all in a single repo doesn't really scale well. And I
 admire robbyrussell's efforts for reviewing and merging the gigantic number of
 pull requests the project gets. We need a better way of plugin management.
 This was discussed on [a][1] [few][2] [issues][3], but it doesn't look like
 there was any progress made. So, I'm trying to start this off with antigen,
 hoping to better this situation. Please note that I'm by no means a zsh or any
 shell script expert (far from it).
 [1]: https://github.com/robbyrussell/oh-my-zsh/issues/465
 [2]: https://github.com/robbyrussell/oh-my-zsh/issues/377
 [3]: https://github.com/robbyrussell/oh-my-zsh/issues/1014
 Inspired by vundle, antigen can pull oh-my-zsh style plugins from various github
 repositories. You are not limited to use plugins from the oh-my-zsh repository
 only and you don't need to maintain your own fork and pull from upstream every
 now and then. I actually encourage you to grab plugins and scripts from various
 sources, straight from the authors, before they even submit it to oh-my-zsh as a
 pull request.
 Antigen also lets you switch the prompt theme with one command, just like that
     antigen theme candy
 and your prompt is changed, just for this session of course (unless you put this
 line in your `.zshrc`).
 ## Commands
 ### antigen bundle
 This command tells antigen to install (if not already installed) and load the
 given plugin. The simplest usage follows the following syntax.
     antigen bundle <plugin-name>
 This will install and load the `plugins/<name>` directory from [robbyrussell's
 oh-my-zsh][oh-my-zsh] (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`).
 However, the above is just syntax sugar for the extended syntax of the
 `antigen bundle` command.
     antigen bundle [<url> [<loc>]]
 where `<url>` is the repository url and it defaults to [robbyrussell's
 oh-my-zsh][oh-my-zsh] repo (can be changed by setting `ANTIGEN_DEFAULT_REPO_URL`
 discussed further down). `<loc>` is the path under this repository which has the
 zsh plugin. This is typically the directory that contains a `*.plugin.zsh` file,
 but it could contain a completion file or just many `*.zsh` files to be sourced.
 `<loc>` defaults to `/`, which indicates the repository itself is a plugin.
 An example invocation would be
     # The following is the same as `antigen bundle ant`. But for demonstration
     # purposes, we use the extended syntax here.
     antigen bundle https://github.com/robbyrussell/oh-my-zsh.git plugins/ant
 This would install the ant plugin from robbyrussell's oh-my-zsh repo. Of course,
 github url's can be shortened.
     antigen bundle robbyrussell/oh-my-zsh plugins/ant
 And since this repo is the default, even that isn't necessary. But we can't
 specify the `loc` without giving the first argument.
 For this and a few other reasons, `antigen bundle` also supports a simple
 keyword argument syntax, using which we can rewrite the above as
     antigen bundle --loc=plugins/ant
 Which picks up the default for the `url` argument, and uses the `loc` given to
 it.
 *Note* that you can mix and match positional and keyword arguments. But you
 can't have positional arguments after keyword arguments.
     antigen bundle robbyrussell/oh-my-zsh --loc=plugins/ant
 And keyword arguments don't care about the order in which the arguments are
 specified. The following is perfectly valid.
     antigen bundle --loc=plugins/ant --url=robbyrussell/oh-my-zsh
 You can also specify a local directory on your file system as a bundle. In this
 case, make sure the path you give is the absolute path (i.e., starts with a
 `/`). Relative paths are not supported. If the repo you gave is a local
 directory path, then it is not necessary that this path is a git repo. Please
 refer to the notes on `--no-local-clone` below.
 This command can also be used from your shell environment. This allows you to
 install plugins on the fly and try them out. Of course if you want a bundle to
 be available every time you open a shell, put it in your `.zshrc`.
 Other keyword-only arguments accepted:
 `--branch={git-branch-name}` &mdash; Specify the branch of the git repo to be
 used for this bundle (without the braces of course). The default is whatever
 branch the clone comes with, which is usually `master`. For example,
     antigen bundle github-user/repo --branch=develop
 This will get the plugin as in the branch `develop`.
 Note that if you specify two plugins to be loaded from the same git repo, but
 different branches, then two separate clones of this repo will be maintained.
 This is a small implementation detail and shouldn't influence you in any way.
 `--no-local-clone` &mdash; This command can be useful if you are developing a
 plugin and already have a clone on your local file system. If this argument is
 not given, even if the given repo url is a local path, a clone is made in the
 `$ADOTDIR/repos`, and the plugin is loaded from that clone. But, if you give
 this argument, the plugin is sourced straight from the repo location, without
 creating a clone. For example,
     antigen bundle /absolute/path/to/the/plugin --no-local-clone
 Note that if the repo url is *not* an absolute local path or a branch has been
 specified with the `--branch` option, this argument has no effect. That is,
 for this option to have any affect, the repo url must be an absolute local path
 and no `--branch` should be specified.
 Also, if the local path given as the url is not a git repo, then this
 argument is forced as it doesn't makes sense to *clone* something that's not a
 git repo. This property can be used to load any utility scripts you have in your
 dotfiles repo. For example,
     antigen bundle $HOME/dotfiles/oh-my-zsh/custom
 In addition to the above discussed arguments, `antigen bundle` also takes a
 `btype` keyword-only argument, that is used internally. You shouldn't be
 concerned with this argument, its only used internally and will probably go away
 in the future.  It indicates whether the bundle is a theme or a simple plugin.
 ### antigen bundles
 If you have a fair number of bundles, using the `antigen bundle` command can
 look cumbersome. You can use the `antigen bundles` command to *bulk* define
 bundles instead of individual calls to `antigen bundle`.
 Usage is pretty straightforward. Just pipe the bundle specifications, just as
 you would give to the `antigen bundle` command, one per line, into the
 `antigen bundles` command. The easiest way to do this, is using the heredoc
 syntax.
     antigen bundles <<EOBUNDLES
       # Guess what to install when running an unknown command.
       command-not-found
       # The heroku tool helper plugin.
       heroku
     EOBUNDLES
 This is equivalent to
     antigen bundle command-not-found
     antigen bundle heroku
 Of course, as you can see, from the lines piped to `antigen bundles`, empty
 lines and those starting with a `#` are ignored. The rest are passed to
 `antigen bundle` without any quoting rules applied. They are actually `eval`-ed
 with the `antigen bundle` command. See the source if you want to really
 understand how it works. Its a very small function.
 *Note*: Indenting the contents inside the EOBUNDLES heredoc is not required for
 antigen-bundles to work. Its allowed (and encouraged) to improve readability.
 ### antigen update
 This is something you might not want to put in your `.zshrc`. Instead, run it
 occasionally to update all your plugins. It doesn't take any arguments.
     antigen update
 Please note that the updates that are downloaded are not immediately available.
 You have to open a new shell to be able to see the changes. This is a limitation
 by design since reloading all the plugins *might* have some nasty side effects
 that may not be immediately apparent. Let's just say it can make your shell act
 real quirky.
 **Please note**: This command is not for updating *antigen* itself. Its for
 updating the bundles you are using with antigen. To update your copy of antigen,
 use the `selfupdate` command described further below.
 ### antigen revert <sup>&alpha;</sup>
 Reverts the state of all your plugins to how they were before the last
 `antigen update`. This command is currently experimental, so don't rely too much
 on it. There is a test for it, and it passes, so it should work fine though.
 Takes no options.
 Insider detail: The information for reverting is stored in
 `$ADOTDIR/revert-info` file.  If its not present, reverting is not possible.
 ### antigen list
 Use this command to list out the currently *loaded* plugins. Keep in mind that
 this includes any bundles installed on-the-fly.
 Takes no arguments. Gives out four entries per line of output, denoting the
 following fields of each bundle.
     <repo-url> <loc> <btype> <has-local-clone?>
 The `btype` field is an internal detail, that specifies if the bundle is a
 `plugin` or a `theme`.
 The final field is `true` or `false` reflecting whether there is a local clone
 for this bundle.
 ### antigen cleanup
 Used to clean up the clones of repos which are not used by any plugins currently
 loaded. It takes no arguments. When run, it lists out the repo-clones that are
 available but are not used by any plugin *currently loaded*.
 This command, by default asks for confirmation before deleting the unused
 clones. If the `--force` argument is given, then this confirmation is not asked.
 It straight away deletes all the unused clones. This option makes this command
 usable in a non-interactive fashion.
 ### antigen use
 This command lets you load any (supported) zsh pre-packaged framework, like
 oh-my-zsh. Usage is
     antigen use oh-my-zsh
 Additional arguments may be present depending on the framework you are
 `use`-ing. Here are the supported frameworks.
 #### oh-my-zsh
 This is (almost) the same as
     antigen bundle --loc=lib
 So, it basically installs the oh-my-zsh's library as a bundle.
 One other thing it does is that some oh-my-zsh plugins expect a `$ZSH` set to
 the full path of the oh-my-zsh clone being used. This is also set to the
 correct path, if not already set to something else.
 Please note that this assumes that the `ANTIGEN_DEFAULT_REPO_URL` is set to the
 oh-my-zsh repo or a fork of that repo. If you want to specify the `url` too,
 then you can't use the `antigen use oh-my-zsh` short cut. You have to do that
 directly with the `antigen bundle` command.
 Use
     antigen use oh-my-zsh
 in  your `.zshrc`, before any `antigen bundle` declarations. It takes no further
 arguments.
 #### prezto
 This is (almost, but not quite) the same as doing,
     antigen bundle sorin-ionescu/prezto
 That is, initializes the canonical repo of the prezto framework. Please note
 that prezto support is very new and experimental in antigen. If you find any
 bugs, please report over on github issues.
 Takes no further arguments.
 ### antigen theme
 Used for switching the prompt theme. Invoke it with the name of the theme you
 want to use.
     antigen theme fox
 This will get the theme file located at `themes/fox.zsh-theme` in the repo
 specified by `ANTIGEN_DEFAULT_REPO_URL`.
 To pull themes from other repositories, use `antigen theme` just like
 `antigen bundle`. Exactly the same, just make sure the `url` and `loc`
 combination point to a theme file, having a `.zsh-theme` extension.
 For example,
     antigen theme robbyrussell/oh-my-zsh themes/apple
 Will pull the apple theme from the canonical oh-my-zsh repo. Also, note that the
 `.zsh-theme` extension is not present. It can be given, its optional.
+To get themes from arbitrary git repos (such as gists) use,
+    antigen theme https://gist.github.com/3750104.git agnoster
 You can use this command to change your theme on the fly in your shell. Go on,
 try out a few themes in your shell before you set it in your `.zshrc`.
 **Note**: Some themes use functions that are loaded by `antigen use oh-my-zsh`.
 So, to avoid any trouble, run `antigen use oh-my-zsh` if you haven't already
 before experimenting with themes. If you have `antigen use oh-my-zsh` in your
 `.zshrc`, you're covered.
 **Note**: Do *not* provide the `--btype` argument to `antigen theme`. Its an
 internal argument.
 ### antigen apply
 You have to add this command after defining all bundles you need, in your zshrc.
 The completions defined by your bundles will be loaded at this step.
 It is possible to load completions as and when a bundle is specified with the
 bundle command, in which case this command would not be necessary. But loading
 the completions is a time-consuming process, so if the completions were loaded
 at every call to `antigen bundle`, your shell will start noticeably slow when
 you have a good number of bundle specifications.
 However, if you can suggest a way so that this would not be necessary, I am very
 interested in discussing it. Please open up an issue with your details. Thanks.
 ### antigen snapshot <sup>&alpha;</sup>
 Creates a snapshot of all the clones you currently have *active* including the
 git version hash they are at and save it to a snapshot file. *Active* means, the
 clones for those listed by `antigen cleanup` are not included in the snapshot.
 Takes one optional argument, the file name in which the snapshot is to be saved.
 Defaults to `antigen snapshot`.
 **Note**: The snapshot currently *only* contains the details of those bundles
 that have a clone. That is, bundles that have `--no-local-clone` set or are
 directly sourced from your file system (without a git repo), are not recorded
 in the snapshot file.
 ### antigen restore <sup>&alpha;</sup>
 Restore the bundles state as specified in the snapshot. Takes one required
 argument, the snapshot file name to read.
 Although it restores the clones of the repos specified in the snapshot file, any
 other clones present in your environment are not touched. This behavior may
 change in the future.
 ### antigen selfupdate
 Use this command to update your copy of antigen. It basically does a `git pull`
 on your antigen's clone, *if* it is a git clone. Otherwise, it doesn't do
 anything.
 Takes no options.
 ### antigen help
 This exists so that there can be some help right in the command line. Currently
 it doesn't provide much help other than redirecting you to the project page for
 documentation. It is intended to provide more meaning and sub-command specific
 help in the future.
 I could use some help here as I'm not that good at writing documentation that
 looks good as output on the command line.
 ## Configuration
 The following environment variables can be set to customize the behavior of
 antigen. Make sure you set them *before* source-ing `antigen.zsh`.
 `ANTIGEN_DEFAULT_REPO_URL` &mdash; This is the default repository url that is
 used for `bundle` commands. The default value is robbyrussell's oh-my-zsh repo,
 but you can set this to the fork url of your own fork.
 `ADOTDIR` &mdash; This directory is used to store all the repo clones, your
 bundles, themes, caches and everything else antigen requires to run smoothly.
 Defaults to `$HOME/.antigen`.
 **Note**: `ANTIGEN_REPO_CACHE` & `ANTIGEN_BUNDLE_DIR` &mdash; These variables
 were used previously but are now removed. Please use `ADOTDIR` instead, as
 mentioned above.
 ## Running the tests
 All the tests are in the `tests` folder and are run using the [cram][] test
 system. The latest version on that website, as of today is v0.5, which does not
 have the `--shell` argument which is required to run our tests. So, to get the
 correct version of cram, run
     pip install -r requirements.txt
 With that, once you have cram installed, you can run the tests as
     make
 If you are making a feature addition, I'd really appreciate if you can add a
 test for your feature. Even if you can add a test for an existing feature, that
 would be great as the tests are currently seriously lagging behind the full
 functionality of antigen.
 ## Notes on writing plugins
 Most shell utilities/plugins are made up of just one file. For a plugin called
 `awesomeness`, create a `awesomeness.plugin.zsh` and code away.
 That said, even if you write a single file as a `.sh` file with the goodness you
 want to create, antigen will work just fine with it. The `*.plugin.zsh` way is
 recommended by antigen, because it is widely used because of the [oh-my-zsh][]
 project.
 If you want to know how antigen loads the plugins, do continue.
 Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If
 present, it will source *only* this script. Nothing else is sourced. This is for
 oh-my-zsh style plugins.
 Secondly, it looks for a `init.zsh` file in the plugin directory. If present, it
 will source *only* this script. Nothing else is sourced. This is for prezto
 style modules.
 Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are
 sourced. The order in which they are sourced is not currently defined. Please
 don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.
 If no `*.zsh` files are present, it finally looks for any `*.sh` files and
 sources *all* of them. Again, the order in which they are sourced in not
 currently defined.
 No matter which (or none) of the above happen to be sourced, this plugin
 directory is added to the zsh's function path (`$fpath`) so that any completions
 in it are loaded.
 One exception to this rule is that if this plugin is a theme. In which case the
 theme script is just sourced and nothing else is done. Not even adding to
 `$fpath`.
 ## A note on external zsh plugins
 Antigen downloads zsh scripts and sources them, according to your
 specifications. As such, these scripts are capable of doing some *real* damage
 to your system. If you are only downloading scripts from oh-my-zsh and/or
 prezto, you're probably fine, since there is a second level of manual checking
 before a script gets into the framework.
 But, if you are adding a script from any other source, please check the source
 code of the plugin to see its not doing anything malicious, before adding it to
 your `.zshrc`.
 ## Meta
 ### Helping out
 Antigen is licensed with the [MIT License][license].
 To contribute, please read the [contributing wiki page][contributing] before
 sending pull requests. If its a long/complicated change, please consider opening
 an [issue][] first so we can discuss it out. Thanks!
 ### Feedback please
 Any comments/suggestions/feedback welcome. Please say hello to me
 ([@sharat87][twitter]) on twitter. Or open an issue to discuss something
 (anything!) about the project ;).
 [Vundle]: https://github.com/gmarik/vundle
 [page on themes]: https://github.com/robbyrussell/oh-my-zsh/wiki/Themes
 [wild]: https://github.com/zsh-users/antigen/wiki/In-the-wild
 [syntax highlighting plugin]: https://github.com/zsh-users/zsh-syntax-highlighting
 [autoenv]: https://github.com/kennethreitz/autoenv
 [f-autoenv]: https://github.com/sharat87/autoenv
 [oh-my-zsh]: https://github.com/robbyrussell/oh-my-zsh
 [cram]: https://bitheap.org/cram/
 [issue]: https://github.com/zsh-users/antigen/issues
 [license]: http://mit.sharats.me
 [contributing]: https://github.com/zsh-users/antigen/wiki/Contributing
 [twitter]: http://twitter.com/sharat87