carat 1.9.9.pre1

data/lib/carat/vendor/thor/lib/thor/version.rb

@@ -0,0 +1,3 @@
+class Carat::Thor
+  VERSION = "0.19.1"
+end

data/lib/carat/vendored_fileutils.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Carat; end
+if RUBY_VERSION >= "2.4"
+  require "carat/vendor/fileutils/lib/fileutils"
+else
+  # the version we vendor is 2.4+
+  require "fileutils"
+end

data/lib/carat/vendored_molinillo.rb

@@ -0,0 +1,2 @@
+module Carat; end
+require 'carat/vendor/molinillo/lib/molinillo'

data/lib/carat/vendored_persistent.rb

@@ -0,0 +1,11 @@
+# We forcibly require OpenSSL, because net/http/persistent will only autoload
+# it. On some Rubies, autoload fails but explicit require succeeds.
+begin
+  require 'openssl'
+rescue LoadError
+  # some Ruby builds don't have OpenSSL
+end
+
+vendor = File.expand_path('../vendor', __FILE__)
+$:.unshift(vendor) unless $:.include?(vendor)
+require 'net/http/persistent'

data/lib/carat/vendored_thor.rb

@@ -0,0 +1,3 @@
+module Carat; end
+require 'carat/vendor/thor/lib/thor'
+require 'carat/vendor/thor/lib/thor/actions'

data/lib/carat/version.rb

@@ -0,0 +1,6 @@
+module Carat
+  # We're doing this because we might write tests that deal
+  # with other versions of carat and we are unsure how to
+  # handle this better.
+  VERSION = "1.9.9.pre1" unless defined?(::Carat::VERSION)
+end

data/lib/carat/vlad.rb

@@ -0,0 +1,11 @@
+# Vlad task for Carat.
+#
+# Just add "require 'carat/vlad'" in your Vlad deploy.rb, and
+# include the vlad:carat:install task in your vlad:deploy task.
+require 'carat/deployment'
+
+include Rake::DSL if defined? Rake::DSL
+
+namespace :vlad do
+  Carat::Deployment.define_task(Rake::RemoteTask, :remote_task, :roles => :app)
+end

data/lib/carat/worker.rb

@@ -0,0 +1,73 @@
+require 'thread'
+
+module Carat
+  class Worker
+    POISON = Object.new
+
+    class WrappedException < StandardError
+      attr_reader :exception
+      def initialize(exn)
+        @exception = exn
+      end
+    end
+
+    # Creates a worker pool of specified size
+    #
+    # @param size [Integer] Size of pool
+    # @param func [Proc] job to run in inside the worker pool
+    def initialize(size, func)
+      @request_queue = Queue.new
+      @response_queue = Queue.new
+      @func = func
+      @threads = size.times.map { |i| Thread.start { process_queue(i) } }
+      trap("INT") { abort_threads }
+    end
+
+    # Enqueue a request to be executed in the worker pool
+    #
+    # @param obj [String] mostly it is name of spec that should be downloaded
+    def enq(obj)
+      @request_queue.enq obj
+    end
+
+    # Retrieves results of job function being executed in worker pool
+    def deq
+      result = @response_queue.deq
+      raise result.exception if result.is_a?(WrappedException)
+      result
+    end
+
+    def stop
+      stop_threads
+    end
+
+  private
+
+    def process_queue(i)
+      loop do
+        obj = @request_queue.deq
+        break if obj.equal? POISON
+        @response_queue.enq apply_func(obj, i)
+      end
+    end
+
+    def apply_func(obj, i)
+      @func.call(obj, i)
+    rescue Exception => e
+      WrappedException.new(e)
+    end
+
+    # Stop the worker threads by sending a poison object down the request queue
+    # so as worker threads after retrieving it, shut themselves down
+    def stop_threads
+      @threads.each { @request_queue.enq POISON }
+      @threads.each { |thread| thread.join }
+    end
+
+    def abort_threads
+      @threads.each {|i| i.exit }
+      exit 1
+    end
+
+  end
+end

data/man/carat-config.ronn

@@ -0,0 +1,178 @@
+carat-config(1) -- Set carat configuration options
+=====================================================
+
+## SYNOPSIS
+
+`carat config` [<name> [<value>]]
+
+## DESCRIPTION
+
+This command allows you to interact with carat's configuration system.
+Carat retrieves its configuration from the local application (`app/.carat/config`),
+environment variables, and the user's home directory (`~/.carat/config`),
+in that order of priority.
+
+Executing `carat config` with no parameters will print a list of all
+carat configuration for the current carat, and where that configuration
+was set.
+
+Executing `carat config <name>` will print the value of that configuration
+setting, and where it was set.
+
+Executing `carat config <name> <value>` will set that configuration to the
+value specified for all carats executed as the current user. The configuration
+will be stored in `~/.carat/config`. If <name> already is set, <name> will be
+overridden and user will be warned.
+
+Executing `carat config --global <name> <value>` works the same as above.
+
+Executing `carat config --local <name> <value>` will set that configuration to
+the local application. The configuration will be stored in `app/.carat/config`.
+
+Executing `carat config --delete <name>` will delete the configuration in both
+local and global sources. Not compatible with --global or --local flag.
+
+Executing carat with the `BUNDLE_IGNORE_CONFIG` environment variable set will
+cause it to ignore all configuration.
+
+## BUILD OPTIONS
+
+You can use `carat config` to give carat the flags to pass to the gem
+installer every time carat tries to install a particular gem.
+
+A very common example, the `mysql` gem, requires Snow Leopard users to
+pass configuration flags to `gem install` to specify where to find the
+`mysql_config` executable.
+
+    gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
+
+Since the specific location of that executable can change from machine
+to machine, you can specify these flags on a per-machine basis.
+
+    carat config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config
+
+After running this command, every time carat needs to install the
+`mysql` gem, it will pass along the flags you specified.
+
+## CONFIGURATION KEYS
+
+Configuration keys in carat have two forms: the canonical form and the
+environment variable form.
+
+For instance, passing the `--without` flag to [carat install(1)][carat-install]
+prevents Carat from installing certain groups specified in the Gemfile(5). Carat
+persists this value in `app/.carat/config` so that calls to `Carat.setup`
+do not try to find gems from the `Gemfile` that you didn't install. Additionally,
+subsequent calls to [carat install(1)][carat-install] remember this setting and skip those
+groups.
+
+The canonical form of this configuration is `"without"`. To convert the canonical
+form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The
+environment variable form of `"without"` is `BUNDLE_WITHOUT`.
+
+Any periods in the configuration keys must be replaced with two underscores when
+setting it via environment variables. The configuration key `local.rack` becomes
+the environment variable `BUNDLE_LOCAL__RACK`.
+
+## LIST OF AVAILABLE KEYS
+
+The following is a list of all configuration keys and their purpose. You can
+learn more about their operation in [carat install(1)][carat-install].
+
+* `path` (`BUNDLE_PATH`):
+  The location on disk to install gems. Defaults to `$GEM_HOME` in development
+  and `vendor/carat` when `--deployment` is used
+* `frozen` (`BUNDLE_FROZEN`):
+  Disallow changes to the `Gemfile`. Defaults to `true` when `--deployment`
+  is used.
+* `without` (`BUNDLE_WITHOUT`):
+  A `:`-separated list of groups whose gems carat should not install
+* `bin` (`BUNDLE_BIN`):
+  Install executables from gems in the carat to the specified directory.
+  Defaults to `false`.
+* `gemfile` (`BUNDLE_GEMFILE`):
+  The name of the file that carat should use as the `Gemfile`. This location
+  of this file also sets the root of the project, which is used to resolve
+  relative paths in the `Gemfile`, among other things. By default, carat
+  will search up from the current working directory until it finds a
+  `Gemfile`.
+* `ssl_ca_cert` (`BUNDLE_SSL_CA_CERT`):
+  Path to a designated CA certificate file or folder containing multiple
+  certificates for trusted CAs in PEM format.
+* `ssl_client_cert` (`BUNDLE_SSL_CLIENT_CERT`):
+  Path to a designated file containing a X.509 client certificate
+  and key in PEM format.
+* `cache_path` (`BUNDLE_CACHE_PATH`): The directory that carat will place
+  cached gems in when running <code>carat package</code>, and that carat
+  will look in when installing gems.
+* `disable_multisource` (`BUNDLE_DISABLE_MULTISOURCE`): When set, Gemfiles
+  containing multiple sources will produce errors instead of warnings. Use
+  `carat config --delete disable_multisource` to unset.
+
+In general, you should set these settings per-application by using the applicable
+flag to the [carat install(1)][carat-install] or [carat package(1)][carat-package] command.
+
+You can set them globally either via environment variables or `carat config`,
+whichever is preferable for your setup. If you use both, environment variables
+will take preference over global settings.
+
+## LOCAL GIT REPOS
+
+Carat also allows you to work against a git repository locally
+instead of using the remote version. This can be achieved by setting
+up a local override:
+
+    carat config local.GEM_NAME /path/to/local/git/repository
+
+For example, in order to use a local Rack repository, a developer could call:
+
+    carat config local.rack ~/Work/git/rack
+
+Now instead of checking out the remote git repository, the local
+override will be used. Similar to a path source, every time the local
+git repository change, changes will be automatically picked up by
+Carat. This means a commit in the local git repo will update the
+revision in the `Gemfile.lock` to the local git repo revision. This
+requires the same attention as git submodules. Before pushing to
+the remote, you need to ensure the local override was pushed, otherwise
+you may point to a commit that only exists in your local machine.
+
+Carat does many checks to ensure a developer won't work with
+invalid references. Particularly, we force a developer to specify
+a branch in the `Gemfile` in order to use this feature. If the branch
+specified in the `Gemfile` and the current branch in the local git
+repository do not match, Carat will abort. This ensures that
+a developer is always working against the correct branches, and prevents
+accidental locking to a different branch.
+
+Finally, Carat also ensures that the current revision in the
+`Gemfile.lock` exists in the local git repository. By doing this, Carat
+forces you to fetch the latest changes in the remotes.
+
+## MIRRORS OF GEM SOURCES
+
+Carat supports overriding gem sources with mirrors. This allows you to
+configure rubygems.org as the gem source in your Gemfile while still using your
+mirror to fetch gems.
+
+    carat config mirror.SOURCE_URL MIRROR_URL
+
+For example, to use a mirror of rubygems.org hosted at
+
+    carat config mirror.http://rubygems.org http://rubygems-mirror.org
+
+## CREDENTIALS FOR GEM SOURCES
+
+Carat allows you to configure credentials for any gem source, which allows
+you to avoid putting secrets into your Gemfile.
+
+    carat config SOURCE_HOSTNAME USERNAME:PASSWORD
+
+For example, to save the credentials of user `claudette` for the gem source at
+`gems.longerous.com`, you would run:
+
+    carat config gems.longerous.com claudette:s00pers3krit
+
+Or you can set the credentials as an environment variable like this:
+
+    export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit"

data/man/carat-exec.ronn

@@ -0,0 +1,136 @@
+carat-exec(1) -- Execute a command in the context of the bundle
+================================================================
+
+## SYNOPSIS
+
+`carat exec` [--keep-file-descriptors] <command>
+
+## DESCRIPTION
+
+This command executes the command, making all gems specified in the
+`Gemfile(5)` available to `require` in Ruby programs.
+
+Essentially, if you would normally have run something like
+`rspec spec/my_spec.rb`, and you want to use the gems specified
+in the `Gemfile(5)` and installed via [carat install(1)][carat-install], you
+should run `carat exec rspec spec/my_spec.rb`.
+
+Note that `carat exec` does not require that an executable is
+available on your shell's `$PATH`.
+
+## OPTIONS
+
+* `--keep-file-descriptors`:
+  Exec in Ruby 2.0 began discarding non-standard file descriptors. When this
+  flag is passed, exec will revert to the 1.9 behaviour of passing all file
+  descriptors to the new process.
+
+## BUNDLE INSTALL --BINSTUBS
+
+If you use the `--binstubs` flag in [carat install(1)][carat-install], Carat will
+automatically create a directory (which defaults to `app_root/bin`)
+containing all of the executables available from gems in the carat.
+
+After using `--binstubs`, `bin/rspec spec/my_spec.rb` is identical
+to `carat exec rspec spec/my_spec.rb`.
+
+## ENVIRONMENT MODIFICATIONS
+
+`carat exec` makes a number of changes to the shell environment,
+then executes the command you specify in full.
+
+* make sure that it's still possible to shell out to `carat`
+  from inside a command invoked by `carat exec` (using
+  `$BUNDLE_BIN_PATH`)
+* put the directory containing executables (like `rails`, `rspec`,
+  `rackup`) for your bundle on `$PATH`
+* make sure that if carat is invoked in the subshell, it uses
+  the same `Gemfile` (by setting `BUNDLE_GEMFILE`)
+* add `-rcarat/setup` to `$RUBYOPT`, which makes sure that
+  Ruby programs invoked in the subshell can see the gems in
+  the bundle
+
+It also modifies Rubygems:
+
+* disallow loading additional gems not in the bundle
+* modify the `gem` method to be a no-op if a gem matching
+  the requirements is in the bundle, and to raise a
+  `Gem::LoadError` if it's not
+* Define `Gem.refresh` to be a no-op, since the source
+  index is always frozen when using carat, and to
+  prevent gems from the system leaking into the environment
+* Override `Gem.bin_path` to use the gems in the bundle,
+  making system executables work
+* Add all gems in the bundle into Gem.loaded_specs
+
+### Shelling out
+
+Any Ruby code that opens a subshell (like `system`, backticks, or `%x{}`) will
+automatically use the current Carat environment. If you need to shell out to
+a Ruby command that is not part of your current bundle, use the
+`with_clean_env` method with a block. Any subshells created inside the block
+will be given the environment present before Carat was activated. For
+example, Homebrew commands run Ruby, but don't work inside a bundle:
+
+    Carat.with_clean_env do
+      `brew install wget`
+    end
+
+Using `with_clean_env` is also necessary if you are shelling out to a different
+bundle. Any Carat commands run in a subshell will inherit the current
+Gemfile, so commands that need to run in the context of a different bundle also
+need to use `with_clean_env`.
+
+    Carat.with_clean_env do
+      Dir.chdir "/other/carat/project" do
+        `carat exec ./script`
+      end
+    end
+
+Carat provides convenience helpers that wrap `system` and `exec`, and they
+can be used like this:
+
+    Carat.clean_system('brew install wget')
+    Carat.clean_exec('brew install wget')
+
+
+## RUBYGEMS PLUGINS
+
+At present, the Rubygems plugin system requires all files
+named `rubygems_plugin.rb` on the load path of _any_ installed
+gem when any Ruby code requires `rubygems.rb`. This includes
+executables installed into the system, like `rails`, `rackup`,
+and `rspec`.
+
+Since Rubygems plugins can contain arbitrary Ruby code, they
+commonly end up activating themselves or their dependencies.
+
+For instance, the `gemcutter 0.5` gem depended on `json_pure`.
+If you had that version of gemcutter installed (even if
+you _also_ had a newer version without this problem), Rubygems
+would activate `gemcutter 0.5` and `json_pure <latest>`.
+
+If your Gemfile(5) also contained `json_pure` (or a gem
+with a dependency on `json_pure`), the latest version on
+your system might conflict with the version in your
+Gemfile(5), or the snapshot version in your `Gemfile.lock`.
+
+If this happens, carat will say:
+
+    You have already activated json_pure 1.4.6 but your Gemfile
+    requires json_pure 1.4.3. Consider using carat exec.
+
+In this situation, you almost certainly want to remove the
+underlying gem with the problematic gem plugin. In general,
+the authors of these plugins (in this case, the `gemcutter`
+gem) have released newer versions that are more careful in
+their plugins.
+
+You can find a list of all the gems containing gem plugins
+by running
+
+    ruby -rubygems -e "puts Gem.find_files('rubygems_plugin.rb')"
+
+At the very least, you should remove all but the newest
+version of each gem plugin, and also remove all gem plugins
+that you aren't using (`gem uninstall gem_name`).

data/man/carat-install.ronn

@@ -0,0 +1,383 @@
+carat-install(1) -- Install the dependencies specified in your Gemfile
+=======================================================================
+
+## SYNOPSIS
+
+`carat install` [--binstubs[=DIRECTORY]]
+                 [--clean]
+                 [--full-index]
+                 [--gemfile=GEMFILE]
+                 [--jobs=NUMBER]
+                 [--local]
+                 [--deployment]
+                 [--no-cache]
+                 [--no-prune]
+                 [--path PATH]
+                 [--system]
+                 [--quiet]
+                 [--retry=NUMBER]
+                 [--shebang]
+                 [--standalone[=GROUP[ GROUP...]]]
+                 [--trust-policy=POLICY]
+                 [--without=GROUP[ GROUP...]]
+
+## DESCRIPTION
+
+Install the gems specified in your Gemfile(5). If this is the first
+time you run carat install (and a `Gemfile.lock` does not exist),
+Carat will fetch all remote sources, resolve dependencies and
+install all needed gems.
+
+If a `Gemfile.lock` does exist, and you have not updated your Gemfile(5),
+Carat will fetch all remote sources, but use the dependencies
+specified in the `Gemfile.lock` instead of resolving dependencies.
+
+If a `Gemfile.lock` does exist, and you have updated your Gemfile(5),
+Carat will use the dependencies in the `Gemfile.lock` for all gems
+that you did not update, but will re-resolve the dependencies of
+gems that you did update. You can find more information about this
+update process below under [CONSERVATIVE UPDATING][].
+
+## OPTIONS
+
+* `--binstubs[=<directory>]`:
+  Creates a directory (defaults to `~/bin`) and place any executables from the
+  gem there. These executables run in Carat's context. If used, you might add
+  this directory to your environment's `PATH` variable. For instance, if the
+  `rails` gem comes with a `rails` executable, this flag will create a
+  `bin/rails` executable that ensures that all referred dependencies will be
+  resolved using the caratd gems.
+
+* `--clean`:
+  On finishing the installation Carat is going to remove any gems not present
+  in the current Gemfile(5). Don't worry, gems currently in use will not be
+  removed.
+
+* `--full-index`:
+  Carat will not call Rubygems' API endpoint (default) but download and cache
+  a (currently big) index file of all gems. Performance can be improved for
+  large carats that seldomly change by enabling this option.
+
+* `--gemfile=<gemfile>`:
+  The location of the Gemfile(5) which Carat should use. This defaults
+  to a Gemfile(5) in the current working directory. In general, Carat
+  will assume that the location of the Gemfile(5) is also the project's
+  root and will try to find `Gemfile.lock` and `vendor/cache` relative
+  to this location.
+
+* `--jobs=[<number>]`:
+  Install gems by starting <number> of workers parallely.
+
+* `--local`:
+  Do not attempt to connect to `rubygems.org`. Instead, Carat will use the
+  gems already present in Rubygems' cache or in `vendor/cache`. Note that if a
+  appropriate platform-specific gem exists on `rubygems.org` it will not be
+  found.
+
+* `--deployment`:
+  In [deployment mode][DEPLOYMENT MODE], Carat will 'roll-out' the carat for
+  `production` use. Please check carefully if you want to have this option
+  enabled in `development` or `test` environments.
+
+* `--system`:
+  Installs the gems specified in the carat to the system's Rubygems location.
+  This overrides any previous [remembered][REMEMBERED OPTIONS] use of `--path`.
+
+* `--no-cache`:
+  Do not update the cache in `vendor/cache` with the newly caratd gems. This
+  does not remove any gems in the cache but keeps the newly caratd gems from
+  being cached during the install.
+
+* `--no-prune`:
+  Don't remove stale gems from the cache when the installation finishes.
+
+* `--path=<path>`:
+  The location to install the specified gems to. This defaults to Rubygems'
+  setting. Carat shares this location with Rubygems, `gem install ...` will
+  have gem installed there, too. Therefore, gems installed without a
+  `--path ...` setting will show up by calling `gem list`. Accodingly, gems
+  installed to other locations will not get listed. This setting is a
+  [remembered option][REMEMBERED OPTIONS].
+
+* `--quiet`:
+  Do not print progress information to the standard output. Instead, Carat
+  will exit using a status code (`$?`).
+
+* `--retry=[<number>]`:
+  Retry failed network or git requests for <number> times.
+
+* `--shebang=<ruby-executable>`:
+  Uses the specified ruby executable (usually `ruby`) to execute the scripts
+  created with `--binstubs`. In addition, if you use `--binstubs` together with
+  `--shebang jruby` these executables will be changed to execute `jruby`
+  instead.
+
+* `--standalone[=<list>]`:
+  Makes a carat that can work without depending on Rubygems or Carat at
+  runtime. A space separated list of groups to install has to be specified.
+  Carat creates a directory named `carat` and installs the carat there. It
+  also generates a `carat/carat/setup.rb` file to replace Carat's own setup
+  in the manner required.
+
+* `--trust-policy=[<policy>]`:
+  Apply the Rubygems security policy <policy>, where policy is one of
+  `HighSecurity`, `MediumSecurity`, `LowSecurity`, `AlmostNoSecurity`, or
+  `NoSecurity`. For more details, please see the Rubygems signing documentation
+  linked below in [SEE ALSO][].
+
+* `--without=<list>`:
+  A space-separated list of groups referencing gems to skip during installation.
+  This is a [remembered option][REMEMBERED OPTIONS].
+
+
+## DEPLOYMENT MODE
+
+Carat's defaults are optimized for development. To switch to
+defaults optimized for deployment, use the `--deployment` flag.
+Do not activate deployment mode on development machines, as it
+will cause an error when the Gemfile(5) is modified.
+
+1. A `Gemfile.lock` is required.
+
+   To ensure that the same versions of the gems you developed with
+   and tested with are also used in deployments, a `Gemfile.lock`
+   is required.
+
+   This is mainly to ensure that you remember to check your
+   `Gemfile.lock` into version control.
+
+2. The `Gemfile.lock` must be up to date
+
+   In development, you can modify your Gemfile(5) and re-run
+   `carat install` to [conservatively update][CONSERVATIVE UPDATING]
+   your `Gemfile.lock` snapshot.
+
+   In deployment, your `Gemfile.lock` should be up-to-date with
+   changes made in your Gemfile(5).
+
+3. Gems are installed to `vendor/carat` not your default system location
+
+   In development, it's convenient to share the gems used in your
+   application with other applications and other scripts run on
+   the system.
+
+   In deployment, isolation is a more important default. In addition,
+   the user deploying the application may not have permission to install
+   gems to the system, or the web server may not have permission to
+   read them.
+
+   As a result, `carat install --deployment` installs gems to
+   the `vendor/carat` directory in the application. This may be
+   overridden using the `--path` option.
+
+## SUDO USAGE
+
+By default, Carat installs gems to the same location as `gem install`.
+
+In some cases, that location may not be writable by your Unix user. In
+that case, Carat will stage everything in a temporary directory,
+then ask you for your `sudo` password in order to copy the gems into
+their system location.
+
+From your perspective, this is identical to installing them gems
+directly into the system.
+
+You should never use `sudo carat install`. This is because several
+other steps in `carat install` must be performed as the current user:
+
+* Updating your `Gemfile.lock`
+* Updating your `vendor/cache`, if necessary
+* Checking out private git repositories using your user's SSH keys
+
+Of these three, the first two could theoretically be performed by
+`chown`ing the resulting files to `$SUDO_USER`. The third, however,
+can only be performed by actually invoking the `git` command as
+the current user. Therefore, git gems are downloaded and installed
+into `~/.carat` rather than $GEM_HOME or $BUNDLE_PATH.
+
+As a result, you should run `carat install` as the current user,
+and Carat will ask for your password if it is needed to put the
+gems into their final location.
+
+## INSTALLING GROUPS
+
+By default, `carat install` will install all gems in all groups
+in your Gemfile(5), except those declared for a different platform.
+
+However, you can explicitly tell Carat to skip installing
+certain groups with the `--without` option. This option takes
+a space-separated list of groups.
+
+While the `--without` option will skip _installing_ the gems in the
+specified groups, it will still _download_ those gems and use them to
+resolve the dependencies of every gem in your Gemfile(5).
+
+This is so that installing a different set of groups on another
+ machine (such as a production server) will not change the
+gems and versions that you have already developed and tested against.
+
+`Carat offers a rock-solid guarantee that the third-party
+code you are running in development and testing is also the
+third-party code you are running in production. You can choose
+to exclude some of that code in different environments, but you
+will never be caught flat-footed by different versions of
+third-party code being used in different environments.`
+
+For a simple illustration, consider the following Gemfile(5):
+
+    source 'https://rubygems.org'
+
+    gem 'sinatra'
+
+    group :production do
+      gem 'rack-perftools-profiler'
+    end
+
+In this case, `sinatra` depends on any version of Rack (`>= 1.0`), while
+`rack-perftools-profiler` depends on 1.x (`~> 1.0`).
+
+When you run `carat install --without production` in development, we
+look at the dependencies of `rack-perftools-profiler` as well. That way,
+you do not spend all your time developing against Rack 2.0, using new
+APIs unavailable in Rack 1.x, only to have Carat switch to Rack 1.2
+when the `production` group _is_ used.
+
+This should not cause any problems in practice, because we do not
+attempt to `install` the gems in the excluded groups, and only evaluate
+as part of the dependency resolution process.
+
+This also means that you cannot include different versions of the same
+gem in different groups, because doing so would result in different
+sets of dependencies used in development and production. Because of
+the vagaries of the dependency resolution process, this usually
+affects more than just the gems you list in your Gemfile(5), and can
+(surprisingly) radically change the gems you are using.
+
+## REMEMBERED OPTIONS
+
+Some options (marked above in the [OPTIONS][] section) are remembered
+between calls to `carat install`, and by the Carat runtime.
+
+For instance, if you run `carat install --without test`, a subsequent
+call to `carat install` that does not include a `--without` flag will
+remember your previous choice.
+
+In addition, a call to `Carat.setup` will not attempt to make the
+gems in those groups available on the Ruby load path, as they were
+not installed.
+
+The settings that are remembered are:
+
+* `--deployment`:
+  At runtime, this remembered setting will also result in Carat
+  raising an exception if the `Gemfile.lock` is out of date.
+
+* `--path`:
+  Subsequent calls to `carat install` will install gems to the
+  directory originally passed to `--path`. The Carat runtime
+  will look for gems in that location. You can revert this
+  option by running `carat install --system`.
+
+* `--binstubs`:
+  Carat will update the executables every subsequent call to
+  `carat install`.
+
+* `--without`:
+  As described above, Carat will skip the gems specified by
+  `--without` in subsequent calls to `carat install`. The
+  Carat runtime will also not try to make the gems in the
+  skipped groups available.
+
+## THE GEMFILE.LOCK
+
+When you run `carat install`, Carat will persist the full names
+and versions of all gems that you used (including dependencies of
+the gems specified in the Gemfile(5)) into a file called `Gemfile.lock`.
+
+Carat uses this file in all subsequent calls to `carat install`,
+which guarantees that you always use the same exact code, even
+as your application moves across machines.
+
+Because of the way dependency resolution works, even a
+seemingly small change (for instance, an update to a point-release
+of a dependency of a gem in your Gemfile(5)) can result in radically
+different gems being needed to satisfy all dependencies.
+
+As a result, you `SHOULD` check your `Gemfile.lock` into version
+control. If you do not, every machine that checks out your
+repository (including your production server) will resolve all
+dependencies again, which will result in different versions of
+third-party code being used if `any` of the gems in the Gemfile(5)
+or any of their dependencies have been updated.
+
+## CONSERVATIVE UPDATING
+
+When you make a change to the Gemfile(5) and then run `carat install`,
+Carat will update only the gems that you modified.
+
+In other words, if a gem that you `did not modify` worked before
+you called `carat install`, it will continue to use the exact
+same versions of all dependencies as it used before the update.
+
+Let's take a look at an example. Here's your original Gemfile(5):
+
+    source 'https://rubygems.org'
+
+    gem 'actionpack', '2.3.8'
+    gem 'activemerchant'
+
+In this case, both `actionpack` and `activemerchant` depend on
+`activesupport`. The `actionpack` gem depends on `activesupport 2.3.8`
+and `rack ~> 1.1.0`, while the `activemerchant` gem depends on
+`activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`.
+
+When the dependencies are first resolved, Carat will select
+`activesupport 2.3.8`, which satisfies the requirements of both
+gems in your Gemfile(5).
+
+Next, you modify your Gemfile(5) to:
+
+    source 'https://rubygems.org'
+
+    gem 'actionpack', '3.0.0.rc'
+    gem 'activemerchant'
+
+The `actionpack 3.0.0.rc` gem has a number of new dependencies,
+and updates the `activesupport` dependency to `= 3.0.0.rc` and
+the `rack` dependency to `~> 1.2.1`.
+
+When you run `carat install`, Carat notices that you changed
+the `actionpack` gem, but not the `activemerchant` gem. It
+evaluates the gems currently being used to satisfy its requirements:
+
+  * `activesupport 2.3.8`:
+    also used to satisfy a dependency in `activemerchant`,
+    which is not being updated
+  * `rack ~> 1.1.0`:
+    not currently being used to satisfy another dependency
+
+Because you did not explicitly ask to update `activemerchant`,
+you would not expect it to suddenly stop working after updating
+`actionpack`. However, satisfying the new `activesupport 3.0.0.rc`
+dependency of actionpack requires updating one of its dependencies.
+
+Even though `activemerchant` declares a very loose dependency
+that theoretically matches `activesupport 3.0.0.rc`, Carat treats
+gems in your Gemfile(5) that have not changed as an atomic unit
+together with their dependencies. In this case, the `activemerchant`
+dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`,
+so `carat install` will report that it cannot update `actionpack`.
+
+To explicitly update `actionpack`, including its dependencies
+which other gems in the Gemfile(5) still depend on, run
+`carat update actionpack` (see `carat update(1)`).
+
+`Summary`: In general, after making a change to the Gemfile(5) , you
+should first try to run `carat install`, which will guarantee that no
+other gems in the Gemfile(5) are impacted by the change. If that
+does not work, run [carat update(1)][carat-update].
+
+## SEE ALSO
+
+* Gem install docs: http://guides.rubygems.org/rubygems-basics/#installing-gems
+* Rubygems signing docs: http://guides.rubygems.org/security/