carat 1.9.9.pre1

data/man/carat-package.ronn

@@ -0,0 +1,66 @@
+carat-package(1) -- Package your needed `.gem` files into your application
+===========================================================================
+
+## SYNOPSIS
+
+`carat package`
+
+## DESCRIPTION
+
+Copy all of the `.gem` files needed to run the application into the
+`vendor/cache` directory. In the future, when running [carat install(1)][carat-install],
+use the gems in the cache in preference to the ones on `rubygems.org`.
+
+## GIT AND PATH GEMS
+
+Since Carat 1.2, the `carat package` command can also package `:git` and
+`:path` dependencies besides .gem files. This needs to be explicitly enabled
+via the `--all` option. Once used, the `--all` option will be remembered.
+
+## SUPPORT FOR MULTIPLE PLATFORMS
+
+When using gems that have different packages for different platforms, Carat
+1.8 and newer support caching of gems for other platforms in `vendor/cache`.
+This needs to be enabled via the `--all-platforms` option. This setting will be
+remembered in your local carat configuration.
+
+## REMOTE FETCHING
+
+By default, if you simply run [carat install(1)][carat-install] after running
+[carat package(1)][carat-package], carat will still connect to `rubygems.org`
+to check whether a platform-specific gem exists for any of the gems
+in `vendor/cache`.
+
+For instance, consider this Gemfile(5):
+
+    source "https://rubygems.org"
+
+    gem "nokogiri"
+
+If you run `carat package` under C Ruby, carat will retrieve
+the version of `nokogiri` for the `"ruby"` platform. If you deploy
+to JRuby and run `carat install`, carat is forced to check to
+see whether a `"java"` platformed `nokogiri` exists.
+
+Even though the `nokogiri` gem for the Ruby platform is
+_technically_ acceptable on JRuby, it actually has a C extension
+that does not run on JRuby. As a result, carat will, by default,
+still connect to `rubygems.org` to check whether it has a version
+of one of your gems more specific to your platform.
+
+This problem is also not just limited to the `"java"` platform.
+A similar (common) problem can happen when developing on Windows
+and deploying to Linux, or even when developing on OSX and
+deploying to Linux.
+
+If you know for sure that the gems packaged in `vendor/cache`
+are appropriate for the platform you are on, you can run
+`carat install --local` to skip checking for more appropriate
+gems, and just use the ones in `vendor/cache`.
+
+One way to be sure that you have the right platformed versions
+of all your gems is to run `carat package` on an identical
+machine and check in the gems. For instance, you can run
+`carat package` on an identical staging box during your
+staging process, and check in the `vendor/cache` before
+deploying to production.

data/man/carat-platform.ronn

@@ -0,0 +1,42 @@
+carat-platform(1) -- Displays platform compatibility information
+=================================================================
+
+## SYNOPSIS
+
+`carat platform` [--ruby]
+
+## DESCRIPTION
+
+`platform` will display information from your Gemfile, Gemfile.lock, and Ruby
+VM about your platform.
+
+For instance, using this Gemfile(5):
+
+    source "https://rubygems.org"
+
+    ruby "1.9.3"
+
+    gem "rack"
+
+If you run `carat platform` on Ruby 1.9.3, it will display the following output:
+
+    Your platform is: x86_64-linux
+
+    Your app has gems that work on these platforms:
+    * ruby
+
+    Your Gemfile specifies a Ruby version requirement:
+    * ruby 1.9.3
+
+    Your current platform satisfies the Ruby version requirement.
+
+`platform` will list all the platforms in your `Gemfile.lock` as well as the
+`ruby` directive if applicable from your Gemfile(5). It will also let you know
+if the `ruby` directive requirement has been met. If `ruby` directive doesn't
+match the running Ruby VM, it will tell you what part does not.
+
+## OPTIONS
+
+* `--ruby`:
+  It will just display the ruby directive information, so you don't have to
+  parse it from the Gemfile(5).

data/man/carat-update.ronn

@@ -0,0 +1,188 @@
+carat-update(1) -- Update your gems to the latest available versions
+=====================================================================
+
+## SYNOPSIS
+
+`carat update` <*gems> [--group=NAME] [--source=NAME] [--local]
+
+## DESCRIPTION
+
+Update the gems specified (all gems, if none are specified), ignoring
+the previously installed gems specified in the `Gemfile.lock`. In
+general, you should use [carat install(1)][carat-install] to install the same exact
+gems and versions across machines.
+
+You would use `carat update` to explicitly update the version of a
+gem.
+
+## OPTIONS
+
+* `--group=<name>`:
+  Only update the gems in the specified group. For instance, you can update all gems
+  in the development group with `carat update --group development`. You can also
+  call `carat update rails --group test` to update the rails gem and all gems in
+  the test group, for example.
+
+* `--source=<name>`:
+  The name of a `:git` or `:path` source used in the Gemfile(5). For
+  instance, with a `:git` source of `http://github.com/rails/rails.git`,
+  you would call `carat update --source rails`
+
+* `--local`:
+  Do not attempt to fetch gems remotely and use the gem cache instead.
+
+## UPDATING ALL GEMS
+
+If you run `carat update` with no parameters, carat will ignore
+any previously installed gems and resolve all dependencies again
+based on the latest versions of all gems available in the sources.
+
+Consider the following Gemfile(5):
+
+    source "https://rubygems.org"
+
+    gem "rails", "3.0.0.rc"
+    gem "nokogiri"
+
+When you run [carat install(1)][carat-install] the first time, carat will resolve
+all of the dependencies, all the way down, and install what you need:
+
+    Fetching gem metadata from https://rubygems.org/.........
+    Resolving dependencies...
+    Installing builder 2.1.2
+    Installing abstract 1.0.0
+    Installing rack 1.2.8
+    Using carat 1.7.6
+    Installing rake 10.4.0
+    Installing polyglot 0.3.5
+    Installing mime-types 1.25.1
+    Installing i18n 0.4.2
+    Installing mini_portile 0.6.1
+    Installing tzinfo 0.3.42
+    Installing rack-mount 0.6.14
+    Installing rack-test 0.5.7
+    Installing treetop 1.4.15
+    Installing thor 0.14.6
+    Installing activesupport 3.0.0.rc
+    Installing erubis 2.6.6
+    Installing activemodel 3.0.0.rc
+    Installing arel 0.4.0
+    Installing mail 2.2.20
+    Installing activeresource 3.0.0.rc
+    Installing actionpack 3.0.0.rc
+    Installing activerecord 3.0.0.rc
+    Installing actionmailer 3.0.0.rc
+    Installing railties 3.0.0.rc
+    Installing rails 3.0.0.rc
+    Installing nokogiri 1.6.5
+
+    Bundle complete! 2 Gemfile dependencies, 26 gems total.
+    Use `carat show [gemname]` to see where a bundled gem is installed.
+
+As you can see, even though you have just two gems in the Gemfile(5), your application
+actually needs 26 different gems in order to run. Carat remembers the exact versions
+it installed in `Gemfile.lock`. The next time you run [carat install(1)][carat-install], carat skips
+the dependency resolution and installs the same gems as it installed last time.
+
+After checking in the `Gemfile.lock` into version control and cloning it on another
+machine, running [carat install(1)][carat-install] will _still_ install the gems that you installed
+last time. You don't need to worry that a new release of `erubis` or `mail` changes
+the gems you use.
+
+However, from time to time, you might want to update the gems you are using to the
+newest versions that still match the gems in your Gemfile(5).
+
+To do this, run `carat update`, which will ignore the `Gemfile.lock`, and resolve
+all the dependencies again. Keep in mind that this process can result in a significantly
+different set of the 25 gems, based on the requirements of new gems that the gem
+authors released since the last time you ran `carat update`.
+
+## UPDATING A LIST OF GEMS
+
+Sometimes, you want to update a single gem in the Gemfile(5), and leave the rest of the
+gems that you specified locked to the versions in the `Gemfile.lock`.
+
+For instance, in the scenario above, imagine that `nokogiri` releases version `1.4.4`, and
+you want to update it _without_ updating Rails and all of its dependencies. To do this,
+run `carat update nokogiri`.
+
+Carat will update `nokogiri` and any of its dependencies, but leave alone Rails and
+its dependencies.
+
+## OVERLAPPING DEPENDENCIES
+
+Sometimes, multiple gems declared in your Gemfile(5) are satisfied by the same
+second-level dependency. For instance, consider the case of `thin` and
+`rack-perftools-profiler`.
+
+    source "https://rubygems.org"
+
+    gem "thin"
+    gem "rack-perftools-profiler"
+
+The `thin` gem depends on `rack >= 1.0`, while `rack-perftools-profiler` depends
+on `rack ~> 1.0`. If you run carat install, you get:
+
+    Fetching source index for https://rubygems.org/
+    Installing daemons (1.1.0)
+    Installing eventmachine (0.12.10) with native extensions
+    Installing open4 (1.0.1)
+    Installing perftools.rb (0.4.7) with native extensions
+    Installing rack (1.2.1)
+    Installing rack-perftools_profiler (0.0.2)
+    Installing thin (1.2.7) with native extensions
+    Using carat (1.0.0.rc.3)
+
+In this case, the two gems have their own set of dependencies, but they share
+`rack` in common. If you run `carat update thin`, carat will update `daemons`,
+`eventmachine` and `rack`, which are dependencies of `thin`, but not `open4` or
+`perftools.rb`, which are dependencies of `rack-perftools_profiler`. Note that
+`carat update thin` will update `rack` even though it's _also_ a dependency of
+`rack-perftools_profiler`.
+
+`In short`, when you update a gem using `carat update`, carat will update all
+dependencies of that gem, including those that are also dependencies of another gem.
+
+In this scenario, updating the `thin` version manually in the Gemfile(5),
+and then running [carat install(1)][carat-install] will only update `daemons` and `eventmachine`,
+but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section
+of [carat install(1)][carat-install].
+
+## RECOMMENDED WORKFLOW
+
+In general, when working with an application managed with carat, you should
+use the following workflow:
+
+* After you create your Gemfile(5) for the first time, run
+
+    $ carat install
+
+* Check the resulting `Gemfile.lock` into version control
+
+    $ git add Gemfile.lock
+
+* When checking out this repository on another development machine, run
+
+    $ carat install
+
+* When checking out this repository on a deployment machine, run
+
+    $ carat install --deployment
+
+* After changing the Gemfile(5) to reflect a new or update dependency, run
+
+    $ carat install
+
+* Make sure to check the updated `Gemfile.lock` into version control
+
+    $ git add Gemfile.lock
+
+* If [carat install(1)][carat-install] reports a conflict, manually update the specific
+  gems that you changed in the Gemfile(5)
+
+    $ carat update rails thin
+
+* If you want to update all the gems to the latest possible versions that
+  still match the gems listed in the Gemfile(5), run
+
+    $ carat update

data/man/carat.ronn

@@ -0,0 +1,98 @@
+carat(1) -- Ruby Dependency Management
+=======================================
+
+## SYNOPSIS
+
+`carat` COMMAND [--no-color] [--verbose] [ARGS]
+
+## DESCRIPTION
+
+Carat manages an `application's dependencies` through its entire life
+across many machines systematically and repeatably.
+
+See [the carat website](https://github.com/caratrb/carat) for information on getting
+started, and Gemfile(5) for more information on the `Gemfile` format.
+
+## OPTIONS
+
+* `--no-color`:
+  Prints all output without color
+
+* `--verbose`:
+  Prints out additional logging information
+
+## BUNDLE COMMANDS
+
+We divide `carat` subcommands into primary commands and utilities.
+
+## PRIMARY COMMANDS
+
+* [carat install(1)][carat-install]:
+  Install the gems specified by the `Gemfile` or `Gemfile.lock`
+
+* [carat update(1)][carat-update]:
+  Update dependencies to their latest versions
+
+* [carat package(1)][carat-package]:
+  Package the .gem files required by your application into the
+  `vendor/cache` directory
+
+* [carat exec(1)][carat-exec]:
+  Execute a script in the context of the current carat
+
+* [carat config(1)][carat-config]:
+  Specify and read configuration options for carat
+
+* `carat help(1)`:
+  Displays detailed help for each subcommand
+
+## UTILITIES
+
+* `carat check(1)`:
+  Determine whether the requirements for your application are installed
+  and available to carat
+
+* `carat list(1)`:
+  Show all of the gems in the current carat
+
+* `carat show(1)`:
+  Show the source location of a particular gem in the carat
+
+* `carat outdated(1)`:
+  Show all of the outdated gems in the current carat
+
+* `carat console(1)`:
+  Start an IRB session in the context of the current carat
+
+* `carat open(1)`:
+  Open an installed gem in the editor
+
+* `carat viz(1)`:
+  Generate a visual representation of your dependencies
+
+* `carat init(1)`:
+  Generate a simple `Gemfile`, placed in the current directory
+
+* `carat gem(1)`:
+  Create a simple gem, suitable for development with carat
+
+* [carat platform(1)][carat-platform]:
+  Displays platform compatibility information
+
+* `carat clean(1)`:
+  Cleans up unused gems in your carat directory
+
+## PLUGINS
+
+When running a command that isn't listed in PRIMARY COMMANDS or UTILITIES,
+Carat will try to find an executable on your path named `carat-<command>`
+and execute it, passing down any extra arguments to it.
+
+## OBSOLETE
+
+These commands are obsolete and should no longer be used
+
+* `carat lock(1)`
+* `carat unlock(1)`
+* `carat cache(1)`
+

data/man/gemfile.5.ronn

@@ -0,0 +1,473 @@
+Gemfile(5) -- A format for describing gem dependencies for Ruby programs
+========================================================================
+
+## SYNOPSIS
+
+A `Gemfile` describes the gem dependencies required to execute associated
+Ruby code.
+
+Place the `Gemfile` in the root of the directory containing the associated
+code. For instance, in a Rails application, place the `Gemfile` in the same
+directory as the `Rakefile`.
+
+## SYNTAX
+
+A `Gemfile` is evaluated as Ruby code, in a context which makes available
+a number of methods used to describe the gem requirements.
+
+## GLOBAL SOURCES (#source)
+
+At the top of the `Gemfile`, add a line for the `Rubygems` source that contains
+the gems listed in the `Gemfile`.
+
+    source "https://rubygems.org"
+
+It is possible, but not recommended as of Carat 1.7, to add multiple global
+`source` lines. Each of these `source`s `MUST` be a valid Rubygems repository.
+
+Sources are checked for gems following the heuristics described in
+[SOURCE PRIORITY][]. If a gem is found in more than one global source, Carat
+will print a warning after installing the gem indicating which source was used,
+and listing the other sources where the gem is available. A specific source can
+be selected for gems that need to use a non-standard repository, suppressing
+this warning, by using the [`:source` option](#SOURCE-source-) or a
+[`source` block](#BLOCK-FORM-OF-SOURCE-GIT-PATH-GROUP-and-PLATFORMS).
+
+### CREDENTIALS (#credentials)
+
+Some gem sources require a username and password. Use `carat config` to set
+the username and password for any sources that need it. The command must be run
+once on each computer that will install the Gemfile, but this keeps the
+credentials from being stored in plain text in version control.
+
+    carat config gems.example.com user:password
+
+For some sources, like a company Gemfury account, it may be easier to simply
+include the credentials in the Gemfile as part of the source URL.
+
+    source "https://user:password@gems.example.com"
+
+Credentials in the source URL will take precedence over credentials set using
+`config`.
+
+## RUBY (#ruby)
+
+If your application requires a specific Ruby version or engine, specify your
+requirements using the `ruby` method, with the following arguments.
+All parameters are `OPTIONAL` unless otherwise specified.
+
+### VERSION (required)
+
+The version of Ruby that your application requires. If your application
+requires an alternate Ruby engine, such as JRuby or Rubinius, this should be
+the Ruby version that the engine is compatible with.
+
+    ruby "1.9.3"
+
+### ENGINE (:engine)
+
+Each application _may_ specify a Ruby engine. If an engine is specified, an
+engine version _must_ also be specified.
+
+### ENGINE VERSION (:engine_version)
+
+Each application _may_ specify a Ruby engine version. If an engine version is
+specified, an engine _must_ also be specified. If the engine is "ruby" the
+engine version specified _must_ match the Ruby version.
+
+    ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
+
+### PATCHLEVEL (:patchlevel)
+
+Each application _may_ specify a Ruby patchlevel.
+
+    ruby "2.0.0", :patchlevel => "247"
+
+## GEMS (#gem)
+
+Specify gem requirements using the `gem` method, with the following arguments.
+All parameters are `OPTIONAL` unless otherwise specified.
+
+### NAME (required)
+
+For each gem requirement, list a single _gem_ line.
+
+    gem "nokogiri"
+
+### VERSION
+
+Each _gem_ `MAY` have one or more version specifiers.
+
+    gem "nokogiri", ">= 1.4.2"
+    gem "RedCloth", ">= 4.1.0", "< 4.2.0"
+
+### REQUIRE AS (:require)
+
+Each _gem_ `MAY` specify files that should be used when autorequiring via
+`Carat.require`. You may pass an array with multiple files or `true` if file
+you want `required` has same name as _gem_ or `false` to
+prevent any file from being autorequired.
+
+    gem "redis", :require => ["redis/connection/hiredis", "redis"]
+    gem "webmock", :require => false
+    gem "debugger", :require => true
+
+The argument defaults to the name of the gem. For example, these are identical:
+
+    gem "nokogiri"
+    gem "nokogiri", :require => "nokogiri"
+    gem "nokogiri", :require => true
+
+### GROUPS (:group or :groups)
+
+Each _gem_ `MAY` specify membership in one or more groups. Any _gem_ that does
+not specify membership in any group is placed in the `default` group.
+
+    gem "rspec", :group => :test
+    gem "wirble", :groups => [:development, :test]
+
+The Carat runtime allows its two main methods, `Carat.setup` and
+`Carat.require`, to limit their impact to particular groups.
+
+    # setup adds gems to Ruby's load path
+    Carat.setup                    # defaults to all groups
+    require "carat/setup"          # same as Carat.setup
+    Carat.setup(:default)          # only set up the _default_ group
+    Carat.setup(:test)             # only set up the _test_ group (but `not` _default_)
+    Carat.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
+
+    # require requires all of the gems in the specified groups
+    Carat.require                  # defaults to just the _default_ group
+    Carat.require(:default)        # identical
+    Carat.require(:default, :test) # requires the _default_ and _test_ groups
+    Carat.require(:test)           # requires just the _test_ group
+
+The Carat CLI allows you to specify a list of groups whose gems `carat install` should
+not install with the `--without` option. To specify multiple groups to ignore, specify a
+list of groups separated by spaces.
+
+    carat install --without test
+    carat install --without development test
+
+After running `carat install --without test`, carat will remember that you excluded
+the test group in the last installation. The next time you run `carat install`,
+without any `--without option`, carat will recall it.
+
+Also, calling `Carat.setup` with no parameters, or calling `require "carat/setup"`
+will setup all groups except for the ones you excluded via `--without` (since they
+are obviously not available).
+
+Note that on `carat install`, carat downloads and evaluates all gems, in order to
+create a single canonical list of all of the required gems and their dependencies.
+This means that you cannot list different versions of the same gems in different
+groups. For more details, see [Understanding Carat](http://carat.io/rationale.html).
+
+### PLATFORMS (:platforms)
+
+If a gem should only be used in a particular platform or set of platforms, you can
+specify them. Platforms are essentially identical to groups, except that you do not
+need to use the `--without` install-time flag to exclude groups of gems for other
+platforms.
+
+There are a number of `Gemfile` platforms:
+
+  * `ruby`:
+    C Ruby (MRI) or Rubinius, but `NOT` Windows
+  * `ruby_18`:
+    _ruby_ `AND` version 1.8
+  * `ruby_19`:
+    _ruby_ `AND` version 1.9
+  * `ruby_20`:
+    _ruby_ `AND` version 2.0
+  * `ruby_21`:
+    _ruby_ `AND` version 2.1
+  * `ruby_22`:
+    _ruby_ `AND` version 2.2
+  * `mri`:
+    Same as _ruby_, but not Rubinius
+  * `mri_18`:
+    _mri_ `AND` version 1.8
+  * `mri_19`:
+    _mri_ `AND` version 1.9
+  * `mri_20`:
+    _mri_ `AND` version 2.0
+  * `mri_21`:
+    _mri_ `AND` version 2.1
+  * `mri_22`:
+    _mri_ `AND` version 2.2
+  * `rbx`:
+    Same as _ruby_, but only Rubinius (not MRI)
+  * `jruby`:
+    JRuby
+  * `mswin`:
+    Windows
+  * `mingw`:
+    Windows 32 bit 'mingw32' platform (aka RubyInstaller)
+  * `mingw_18`:
+    _mingw_ `AND` version 1.8
+  * `mingw_19`:
+    _mingw_ `AND` version 1.9
+  * `mingw_20`:
+    _mingw_ `AND` version 2.0
+  * `mingw_21`:
+    _mingw_ `AND` version 2.1
+  * `mingw_22`:
+    _mingw_ `AND` version 2.2
+  * `x64_mingw`:
+    Windows 64 bit 'mingw32' platform (aka RubyInstaller x64)
+  * `x64_mingw_20`:
+    _x64_mingw_ `AND` version 2.0
+  * `x64_mingw_21`:
+    _x64_mingw_ `AND` version 2.1
+  * `x64_mingw_22`:
+    _x64_mingw_ `AND` version 2.2
+
+As with groups, you can specify one or more platforms:
+
+    gem "weakling",   :platforms => :jruby
+    gem "ruby-debug", :platforms => :mri_18
+    gem "nokogiri",   :platforms => [:mri_18, :jruby]
+
+All operations involving groups (`carat install`, `Carat.setup`,
+`Carat.require`) behave exactly the same as if any groups not
+matching the current platform were explicitly excluded.
+
+### SOURCE (:source)
+
+You can select an alternate Rubygems repository for a gem using the ':source'
+option.
+
+    gem "some_internal_gem", :source => "https://gems.example.com"
+
+This forces the gem to be loaded from this source and ignores any global sources
+declared at the top level of the file. If the gem does not exist in this source,
+it will not be installed.
+
+Carat will search for child dependencies of this gem by first looking in the
+source selected for the parent, but if they are not found there, it will fall
+back on global sources using the ordering described in [SOURCE PRIORITY][].
+
+Selecting a specific source repository this way also suppresses the ambiguous
+gem warning described above in
+[GLOBAL SOURCES (#source)](#GLOBAL-SOURCES-source-).
+
+### GIT (:git)
+
+If necessary, you can specify that a gem is located at a particular
+git repository using the `:git` parameter. The repository can be accessed via
+several protocols:
+
+  * `HTTP(S)`:
+    gem "rails", :git => "https://github.com/rails/rails.git"
+  * `SSH`:
+    gem "rails", :git => "git@github.com:rails/rails.git"
+  * `git`:
+    gem "rails", :git => "git://github.com/rails/rails.git"
+
+If using SSH, the user that you use to run `carat install` `MUST` have the
+appropriate keys available in their `$HOME/.ssh`.
+
+`NOTE`: `http://` and `git://` URLs should be avoided if at all possible. These
+protocols are unauthenticated, so a man-in-the-middle attacker can deliver
+malicious code and compromise your system. HTTPS and SSH are strongly
+preferred.
+
+The `group`, `platforms`, and `require` options are available and behave
+exactly the same as they would for a normal gem.
+
+A git repository `SHOULD` have at least one file, at the root of the
+directory containing the gem, with the extension `.gemspec`. This file
+`MUST` contain a valid gem specification, as expected by the `gem build`
+command.
+
+If a git repository does not have a `.gemspec`, carat will attempt to
+create one, but it will not contain any dependencies, executables, or
+C extension compilation instructions. As a result, it may fail to properly
+integrate into your application.
+
+If a git repository does have a `.gemspec` for the gem you attached it
+to, a version specifier, if provided, means that the git repository is
+only valid if the `.gemspec` specifies a version matching the version
+specifier. If not, carat will print a warning.
+
+    gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git"
+    # carat install will fail, because the .gemspec in the rails
+    # repository's master branch specifies version 3.0.0
+
+If a git repository does `not` have a `.gemspec` for the gem you attached
+it to, a version specifier `MUST` be provided. Carat will use this
+version in the simple `.gemspec` it creates.
+
+Git repositories support a number of additional options.
+
+  * `branch`, `tag`, and `ref`:
+    You `MUST` only specify at most one of these options. The default
+    is `:branch => "master"`
+  * `submodules`:
+    Specify `:submodules => true` to cause carat to expand any
+    submodules included in the git repository
+
+If a git repository contains multiple `.gemspecs`, each `.gemspec`
+represents a gem located at the same place in the file system as
+the `.gemspec`.
+
+    |~rails                   [git root]
+    | |-rails.gemspec         [rails gem located here]
+    |~actionpack
+    | |-actionpack.gemspec    [actionpack gem located here]
+    |~activesupport
+    | |-activesupport.gemspec [activesupport gem located here]
+    |...
+
+To install a gem located in a git repository, carat changes to
+the directory containing the gemspec, runs `gem build name.gemspec`
+and then installs the resulting gem. The `gem build` command,
+which comes standard with Rubygems, evaluates the `.gemspec` in
+the context of the directory in which it is located.
+
+### GIT SOURCE (:git_source)
+
+A custom git source can be defined via the `git_source` method. Provide the source's name
+as an argument, and a block which receives a single argument and interpolates it into a
+string to return the full repo address:
+
+    git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
+    gem 'rails', :stash => 'forks/rails'
+
+In addition, if you wish to choose a specific branch:
+
+    gem "rails", :stash => "forks/rails", :branch => "branch_name"
+
+### GITHUB (:github)
+
+`NOTE`: This shorthand should be avoided until Carat 2.0, since it
+currently expands to an insecure `git://` URL. This allows a
+man-in-the-middle attacker to compromise your system.
+
+If the git repository you want to use is hosted on GitHub and is public, you can use the
+:github shorthand to specify just the github username and repository name (without the
+trailing ".git"), separated by a slash. If both the username and repository name are the
+same, you can omit one.
+
+    gem "rails", :github => "rails/rails"
+    gem "rails", :github => "rails"
+
+Are both equivalent to
+
+    gem "rails", :git => "git://github.com/rails/rails.git"
+
+Since the `github` method is a specialization of `git_source`, it accepts a `:branch` named argument.
+
+### GIST (:gist)
+
+If the git repository you want to use is hosted as a Github Gist and is public, you can use
+the :gist shorthand to specify just the gist identifier (without the trailing ".git").
+
+    gem "the_hatch", :gist => "4815162342"
+
+Is equivalent to:
+
+    gem "the_hatch", :git => "https://gist.github.com/4815162342.git"
+
+Since the `gist` method is a specialization of `git_source`, it accepts a `:branch` named argument.
+
+### BITBUCKET (:bitbucket)
+
+If the git repository you want to use is hosted on Bitbucket and is public, you can use the
+:bitbucket shorthand to specify just the bitbucket username and repository name (without the
+trailing ".git"), separated by a slash. If both the username and repository name are the
+same, you can omit one.
+
+    gem "rails", :bitbucket => "rails/rails"
+    gem "rails", :bitbucket => "rails"
+
+Are both equivalent to
+
+    gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git"
+
+Since the `bitbucket` method is a specialization of `git_source`, it accepts a `:branch` named argument.
+
+### PATH (:path)
+
+You can specify that a gem is located in a particular location
+on the file system. Relative paths are resolved relative to the
+directory containing the `Gemfile`.
+
+Similar to the semantics of the `:git` option, the `:path`
+option requires that the directory in question either contains
+a `.gemspec` for the gem, or that you specify an explicit
+version that carat should use.
+
+Unlike `:git`, carat does not compile C extensions for
+gems specified as paths.
+
+    gem "rails", :path => "vendor/rails"
+
+If you would like to use multiple local gems directly from the filesystem, you can set a global `path` option to the path containing the gem's files. This will automatically load gemspec files from subdirectories.
+
+    path 'components' do
+      gem 'admin_ui'
+      gem 'public_ui'
+    end
+
+## BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS
+
+The `:source`, `:git`, `:path`, `:group`, and `:platforms` options may be
+applied to a group of gems by using block form.
+
+    source "https://gems.example.com" do
+      gem "some_internal_gem"
+      gem "another_internal_gem"
+    end
+
+    git "https://github.com/rails/rails.git" do
+      gem "activesupport"
+      gem "actionpack"
+    end
+
+    platforms :ruby do
+      gem "ruby-debug"
+      gem "sqlite3"
+    end
+
+    group :development do
+      gem "wirble"
+      gem "faker"
+    end
+
+In the case of the `git` block form, the `:ref`, `:branch`, `:tag`,
+and `:submodules` options may be passed to the `git` method, and
+all gems in the block will inherit those options.
+
+## GEMSPEC (#gemspec)
+
+If you wish to use Carat to help install dependencies for a gem while it is
+being developed, use the `gemspec` method to pull in the dependencies listed in
+the `.gemspec` file.
+
+The `gemspec` method adds any runtime dependencies as gem requirements in the
+default group. It also adds development dependencies as gem requirements in the
+`development` group. Finally, it adds a gem requirement on your project (`:path
+=> '.'`). In conjunction with `Carat.setup`, this allows you to require project
+files in your test code as you would if the project were installed as a gem; you
+need not manipulate the load path manually or require project files via relative
+paths.
+
+The `gemspec` method supports optional `:path`, `:name`, and `:development_group`
+options, which control where carat looks for the `.gemspec`, what named
+`.gemspec` it uses (if more than one is present), and which group development
+dependencies are included in.
+
+## SOURCE PRIORITY
+
+When attempting to locate a gem to satisfy a gem requirement,
+carat uses the following priority order:
+
+  1. The source explicitly attached to the gem (using `:source`, `:path`, or
+     `:git`)
+  2. For implicit gems (dependencies of explicit gems), any source, git, or path
+     repository declared on the parent. This results in carat prioritizing the
+     ActiveSupport gem from the Rails git repository over ones from
+     `rubygems.org`
+  3. The sources specified via global `source` lines, searching each source in
+     your `Gemfile` from last added to first added.