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 Side-by-side Diff

... ... @@ -0,0 +1,194 @@
  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