I’ve been using zsh for a while, with oh-my-zsh to add a pile of new features to it. Oh-my-zsh is great, and has a lot of useful things in it, but I found it a bit of a pain to keep my fork of it in sync with the main repository and another fork that I’d stolen things from. The fact that it was one giant repository with everything in there didn’t seem quite right to me. Then, I came across zsh-antigen, which promises to be to zsh what Pathogen is to Vim. That sounded good to me, so I gave it a try.

The main difference is that instead of having one repository with all the plugins, it lets you load plugins from pretty much any Git repository. It includes a special case for the oh-my-zsh repository, so you can load plugins and themes from there by default. I’d recommend reading the README in the Antigen repository to get the full story, but I’ll give a quick overview of how I’ve got mine set up here.

First off, I created my own Git repository, and added the Antigen repository as a submodule. I’ve called mine .zsh-antigen, and it lives in my home directory. It’s on Github if you want to clone or fork it.

Next I created my zshrc file, at ~/.zsh-antigen/zshrc. I symlink it into my home directory to ~/.zshrc.

On lines 1 and 2, I set up a variable to refer to the antigen directory, and then load the antigen script itself.

On line 4, we tell antigen to use oh-my-zsh by default. That way, we can load plugins from there with the antigen-bundle command. I use a few, the vagrant and git plugins on all my machines, and I detect Mac OS X and load the osx plugin if I’m on a Mac.

I use a couple of bundles that don’t belong to oh-my-zsh, too – these are the zsh-syntax-highlighting bundle from zsh-users, which adds nice syntax highlighting to the command line, and the zsh-history-substring-search bundle that provides history search when you type part of a command and press the up cursor key. As you can see, if they’re hosted on Github, it’s as easy as specifying the repos in a “username/repo-name” format.

On line 14, I load a bundle which is local to my config. (It just provides some path detection to tell me what app I’m in when editing files on my work computer. These appear in the right prompt.) You can add as many bundles and as you like, without them having to be part of oh-my-zsh.

Next, on line 16 I apply a theme. This is a theme in the same format as oh-my-zsh, and just specifies what appears in the left prompt (PS1, as in Bash and similar shells) and RPS1 (which is right-aligned and doesn’t normally exist in Bash).

We then call antigen-apply last of all, which applies all the previous configuration. When antigen-apply is called, it will ensure that it has all the bundles and themes that have been requested. If not, it will go off and download them and cache them locally. This means that the first time you load antigen in a new shell, it’ll wait a few seconds while it goes and grabs the oh-my-zsh code along with any other bundles you’ve requested.

Underneath this, I place all my useful environment variables, aliases, and install things like rbenv, the same way as I used to do in Bash. I find this way of working to be quite a bit cleaner than oh-my-zsh - the .zshrc I ended up with in there had quite a lot going on, along with various ‘magic’ things that I wasn’t keen on. The automatic updating really got on my nerves, even though it’s supposed to be convenient. Feel free to grab my repo and use it as a starting point if it’s helpful.