Write a more detailed readme

1 files changed, 122 insertions, 2 deletions

diff --git a/README.rdoc b/README.rdoc
index 9b25f58a0d..02954de648 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -1,3 +1,123 @@
-== bundler
+== Bundler : A gem to bundle gems
 
-A gem that provides...
+  Github: http://github.com/wycats/bundler
+
+== Intro
+
+Bundler is a tool that manages gem dependencies for your ruby application. It
+takes a gem manifest file and is able to fetch, download, and install the gems
+and all child dependencies specified in this manifest. It can manage any update
+to the gem manifest file and update the bundled gems accordingly. It also lets
+you run any ruby code in context of the bundled gem environment.
+
+== Installation
+
+Bundler has no dependencies. Just clone the git repository and install the gem
+with the following rake task:
+
+  rake install
+
+== Usage
+
+Bundler requires a gem manifest file to be created. By default, this should be
+a file named 'Gemfile' located in the root directory of your application. After the manifest has been created, in your shell, cd into your application's
+directory and run 'gem_bundler'. This will start the bundling process.
+
+=== Manifest file
+
+This is where you specify all of your application's dependencies. By default
+this should be in a file named Gemfile located in your application's root
+directory. The following is an example of a potential Gemfile. For more
+information, please refer to Bundler::ManifestBuilder.
+
+  # Specify a dependency on rails. When the bundler downloads gems,
+  # it will download rails as well as all of rails' dependencies (such as
+  # activerecord, actionpack, etc...)
+  #
+  # At least one dependency must be specified
+  gem "rails"
+
+  # Specify a dependency on rack v.1.0.0. The version is optional. If present,
+  # it can be specified the same way as with rubygems' #gem method.
+  gem "rack", "1.0.0"
+
+  # Specify a dependency rspec, but only activate that gem in the "testing"
+  # environment (read more about environments later). :except is also a valid
+  # option to specify environment restrictions.
+  gem "rspec", :only => :testing
+
+  # Add http://gems.github.com as a source that the bundler will use
+  # to find gems listed in the manifest. By default,
+  # http://gems.rubyforge.org is already added to the list.
+  #
+  # This is an optional setting.
+  source "http://gems.github.com"
+
+  # Specify where the bundled gems should be stashed. This directory will
+  # be a gem repository where all gems are downloaded to and installed to.
+  #
+  # This is an optional setting.
+  # The default is: vendor/gems
+  bundle_path "my/bundled/gems"
+
+  # Specify where gem executables should be copied to.
+  #
+  # This is an optional setting.
+  # The default is: bin
+  bin_path "my/executables"
+
+  # Specify that rubygems should be completely disabled. This means that it
+  # will be impossible to require it and that available gems will be
+  # limited exclusively to gems that have been bundled.
+  #
+  # The default is to not require rubygems automatically (bundled gems are
+  # available without rubygems), but rubygems can still be required and it
+  # behaves normally.
+  disable_rubygems
+
+=== Running Bundler
+
+Once a manifest file has been created, the only thing that needs to be done
+is to run the "gem_bundler" command anywhere in your application. The script
+will load the manifest file, resole all the dependencies, download all
+needed gems, and install them into the specified directory.
+
+Every time an update is made to the manifest file, run "gem_bundler" again to
+get the changes installed.
+
+=== Running your application
+
+The easiest way to run your application is to start it with an executable
+copied to the specified bin directory (by default, simply bin). For example,
+if the application in question is a rack app, start it with bin/rackup. This
+will automatically set the gem environment correctly.
+
+Another way to run arbitrary ruby code in context of the bundled gems is to
+run it with the gem_bundler command. For example:
+
+  gem_bundler ruby my_ruby_script.rb
+
+Yet another way is to manually require the environment file first. This is
+located in [bundle_path]/environments/[environment_name].rb. The default
+environment file is default.rb. For example:
+
+  ruby -r vendor/gems/environments/default.rb my_ruby_script.rb
+
+== Environments
+
+More to come...
+
+== Reporting bugs
+
+Please report all bugs on the github issue tracker for the project located
+at:
+
+  http://github.com/wycats/bundler/issues/
+
+== Known issues
+
+  * There are certain complex, but valid dependency combinations that cause
+    Bundler to freeze up.
+
+  * Running ruby code with 'gem_bundler ruby my_ruby_script.rb' will require
+    the entire Bundler source code which also requires rubygems.
\ No newline at end of file