Update the README

4 files changed, 154 insertions, 9 deletions

diff --git a/README b/README
deleted file mode 100644
index ec5f8ef118..0000000000
--- a/README
+++ /dev/null
@@ -1,7 +0,0 @@
-This is a rewrite of bundler to offer more bundling power
-
-It currently lacks output and good exception handling for common cases. This is coming very soon. We wanted to open this so people could take a look at it.
-
-More soon.
-
-- carlhuda
\ No newline at end of file
diff --git a/README.markdown b/README.markdown
new file mode 100644
index 0000000000..f2a5e42bc6
--- /dev/null
+++ b/README.markdown
@@ -0,0 +1,152 @@
+## Bundler : A gem to bundle gems
+
+    Github:       http://github.com/wycats/bundler
+    Mailing list: http://groups.google.com/group/ruby-bundler
+    IRC:          #carlhuda on freenode
+
+## 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 bundle's gems accordingly. It also lets
+you run any ruby code in context of the bundle's gem environment.
+
+## Installation
+
+Bundler has no dependencies besides Ruby and RubyGems. Just clone the git
+repository and install the gem with the following rake task:
+
+    rake install
+
+You can also install the gem with
+
+    gem install bundler --prerelease
+    
+## Usage
+
+The first thing to do is create a gem manifest file named `Gemfile` at the
+root directory of your application. This can quickly be done by running
+`bundle init` in the directory that you wish the Gemfile to be created in.
+
+### Gemfile
+
+This is where you specify all of your application's dependencies. The
+following is an example. For more information, refer to
+Bundler::Dsl.
+
+    # Add :gemcutter as a source that Bundler will use
+    # to find gems listed in the manifest. At least one source
+    # should be listed. URLs maybe also be used, such as
+    # http://gems.github.com.
+    #
+    source :gemcutter
+
+    # Specify a dependency on rails. When 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"
+
+### Installing gems
+
+Once the manifest file has been created, the next step is to install all
+the gems needed to satisfy the Gemfile's dependencies. The `bundle install`
+command will do this.
+
+This command will load the Gemfile, resolve all the dependencies, download
+all gems that are missing, and install them to the system's RubyGems
+repository. Every time an update is made to the Gemfile, run `bundle install`
+again to get the new gems installed.
+
+### Locking dependencies
+
+By default, bundler will only ensure that the activated gems satisfy the
+Gemfile's dependencies. If you install a newer version of a gem and it
+satisfies the dependencies, it will be used instead of the older one. 
+
+The command `bundle lock` will lock the bundle to the current set of
+resolved gems. This ensures that, until the lock file is removed, that
+bundle install and Bundle.setup will always activate the same gems.
+
+### Running the application
+
+Bundler must be required and setup before anything else is required. This
+is because it will configure all the load paths and manage rubygems for your.
+To do this, include the following at the beginning of your code.
+
+    begin
+      # Require the preresolved locked set of gems.
+      require File.expand_path('../vendor/environment', __FILE__)
+    rescue LoadError
+      # Fallback on doing the resolve at runtime.
+      require "rubygems"
+      require "bundler"
+      Bundler.setup
+    end
+
+    # Your application requires come here
+
+The `bundle exec` command provides a way to run arbitrary ruby code in
+context of the bundle. For example:
+
+    bundle exec ruby my_ruby_script.rb
+
+To enter a shell that will run all gem executables (such as rake, rails,
+etc... ) use `bundle exec bash` (replacing bash for whatever your favorite
+shell is).
+
+### Packing the bundle's gems
+
+When sharing or deploying an application, it might be useful to include
+everything necessary to install gem dependencies. `bundle pack` will
+copy .gem files for all of the bundle's dependencies into vendor/cache.
+This way, bundle install can always work no matter what the state of the
+remote sources.
+
+## Gem resolution
+
+One of the most important things that the bundler does is do a
+dependency resolution on the full list of gems that you specify, all
+at once. This differs from the one-at-a-time dependency resolution that
+Rubygems does, which can result in the following problem:
+
+    # On my system:
+    #   activesupport 3.0.pre
+    #   activesupport 2.3.4
+    #   activemerchant 1.4.2
+    #   rails 2.3.4
+    #
+    # activemerchant 1.4.2 depends on activesupport >= 2.3.2
+
+    gem "activemerchant", "1.4.2"
+    # results in activating activemerchant, as well as
+    # activesupport 3.0.pre, since it is >= 2.3.2
+
+    gem "rails", "2.3.4"
+    # results in:
+    #   can't activate activesupport (= 2.3.4, runtime)
+    #   for ["rails-2.3.4"], already activated
+    #   activesupport-3.0.pre for ["activemerchant-1.4.2"]
+
+This is because activemerchant has a broader dependency, which results
+in the activation of a version of activesupport that does not satisfy
+a more narrow dependency.
+
+Bundler solves this problem by evaluating all dependencies at once,
+so it can detect that all gems *together* require activesupport "2.3.4".
+
+## Reporting bugs
+
+Please report all bugs on the github issue tracker for the project located
+at:
+
+    http://github.com/wycats/bundler/issues/
\ No newline at end of file
diff --git a/Rakefile b/Rakefile
index 11814ffe2f..6c3d86a4c9 100644
--- a/Rakefile
+++ b/Rakefile
@@ -16,7 +16,7 @@ spec = Gem::Specification.new do |s|
 
   s.required_rubygems_version = ">= 1.3.5"
 
-  s.files        = Dir.glob("{bin,lib}/**/*") + %w(LICENSE README)
+  s.files        = Dir.glob("{bin,lib}/**/*") + %w(LICENSE README.markdown)
   s.executables  = ['bundle']
   s.require_path = 'lib'
 end
diff --git a/bundler.gemspec b/bundler.gemspec
index 6954f734f1..55facc3944 100644
--- a/bundler.gemspec
+++ b/bundler.gemspec
@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.default_executable = %q{bundle}
   s.email = ["carlhuda@engineyard.com"]
   s.executables = ["bundle"]
-  s.files = ["bin/bundle", "lib/bundler", "lib/bundler/cli.rb", "lib/bundler/definition.rb", "lib/bundler/dependency.rb", "lib/bundler/dsl.rb", "lib/bundler/environment.rb", "lib/bundler/index.rb", "lib/bundler/installer.rb", "lib/bundler/remote_specification.rb", "lib/bundler/resolver.rb", "lib/bundler/rubygems.rb", "lib/bundler/setup.rb", "lib/bundler/source.rb", "lib/bundler/specification.rb", "lib/bundler/templates", "lib/bundler/templates/environment.erb", "lib/bundler/templates/Gemfile", "lib/bundler/ui.rb", "lib/bundler/vendor", "lib/bundler/vendor/thor", "lib/bundler/vendor/thor/actions", "lib/bundler/vendor/thor/actions/create_file.rb", "lib/bundler/vendor/thor/actions/directory.rb", "lib/bundler/vendor/thor/actions/empty_directory.rb", "lib/bundler/vendor/thor/actions/file_manipulation.rb", "lib/bundler/vendor/thor/actions/inject_into_file.rb", "lib/bundler/vendor/thor/actions.rb", "lib/bundler/vendor/thor/base.rb", "lib/bundler/vendor/thor/core_ext", "lib/bundler/vendor/thor/core_ext/file_binary_read.rb", "lib/bundler/vendor/thor/core_ext/hash_with_indifferent_access.rb", "lib/bundler/vendor/thor/core_ext/ordered_hash.rb", "lib/bundler/vendor/thor/error.rb", "lib/bundler/vendor/thor/group.rb", "lib/bundler/vendor/thor/invocation.rb", "lib/bundler/vendor/thor/parser", "lib/bundler/vendor/thor/parser/argument.rb", "lib/bundler/vendor/thor/parser/arguments.rb", "lib/bundler/vendor/thor/parser/option.rb", "lib/bundler/vendor/thor/parser/options.rb", "lib/bundler/vendor/thor/parser.rb", "lib/bundler/vendor/thor/rake_compat.rb", "lib/bundler/vendor/thor/runner.rb", "lib/bundler/vendor/thor/shell", "lib/bundler/vendor/thor/shell/basic.rb", "lib/bundler/vendor/thor/shell/color.rb", "lib/bundler/vendor/thor/shell.rb", "lib/bundler/vendor/thor/task.rb", "lib/bundler/vendor/thor/util.rb", "lib/bundler/vendor/thor/version.rb", "lib/bundler/vendor/thor.rb", "lib/bundler.rb", "LICENSE", "README"]
+  s.files = ["bin/bundle", "lib/bundler/cli.rb", "lib/bundler/definition.rb", "lib/bundler/dependency.rb", "lib/bundler/dsl.rb", "lib/bundler/environment.rb", "lib/bundler/index.rb", "lib/bundler/installer.rb", "lib/bundler/remote_specification.rb", "lib/bundler/resolver.rb", "lib/bundler/rubygems.rb", "lib/bundler/setup.rb", "lib/bundler/source.rb", "lib/bundler/specification.rb", "lib/bundler/templates/environment.erb", "lib/bundler/templates/Gemfile", "lib/bundler/ui.rb", "lib/bundler/vendor/thor/actions/create_file.rb", "lib/bundler/vendor/thor/actions/directory.rb", "lib/bundler/vendor/thor/actions/empty_directory.rb", "lib/bundler/vendor/thor/actions/file_manipulation.rb", "lib/bundler/vendor/thor/actions/inject_into_file.rb", "lib/bundler/vendor/thor/actions.rb", "lib/bundler/vendor/thor/base.rb", "lib/bundler/vendor/thor/core_ext/file_binary_read.rb", "lib/bundler/vendor/thor/core_ext/hash_with_indifferent_access.rb", "lib/bundler/vendor/thor/core_ext/ordered_hash.rb", "lib/bundler/vendor/thor/error.rb", "lib/bundler/vendor/thor/group.rb", "lib/bundler/vendor/thor/invocation.rb", "lib/bundler/vendor/thor/parser/argument.rb", "lib/bundler/vendor/thor/parser/arguments.rb", "lib/bundler/vendor/thor/parser/option.rb", "lib/bundler/vendor/thor/parser/options.rb", "lib/bundler/vendor/thor/parser.rb", "lib/bundler/vendor/thor/rake_compat.rb", "lib/bundler/vendor/thor/runner.rb", "lib/bundler/vendor/thor/shell/basic.rb", "lib/bundler/vendor/thor/shell/color.rb", "lib/bundler/vendor/thor/shell.rb", "lib/bundler/vendor/thor/task.rb", "lib/bundler/vendor/thor/util.rb", "lib/bundler/vendor/thor/version.rb", "lib/bundler/vendor/thor.rb", "lib/bundler.rb", "LICENSE", "README.markdown"]
   s.homepage = %q{http://github.com/carlhuda/bundler}
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}