diff options
author | wycats <wycats@gmail.com> | 2010-08-15 19:33:43 -0700 |
---|---|---|
committer | wycats <wycats@gmail.com> | 2010-08-15 19:46:13 -0700 |
commit | 2051536fef0c4441c8778c2ea3cb44b2077e0062 (patch) | |
tree | f41d4ed847477d9ff0ef6bf2074147fc4a60bb98 | |
parent | 702e7aac1e29492604487c52c807f63de2aba193 (diff) | |
download | bundler-2051536fef0c4441c8778c2ea3cb44b2077e0062.tar.gz |
Gemfile(5) not Gemfile(7)
-rw-r--r-- | .gitignore | 4 | ||||
-rw-r--r-- | man/bundle-config.ronn | 2 | ||||
-rw-r--r-- | man/bundle-install.ronn | 46 | ||||
-rw-r--r-- | man/bundle-package.ronn | 2 | ||||
-rw-r--r-- | man/bundle-update.ronn | 22 | ||||
-rw-r--r-- | man/bundle.ronn | 2 | ||||
-rw-r--r-- | man/index.txt | 2 |
7 files changed, 43 insertions, 37 deletions
diff --git a/.gitignore b/.gitignore index 285e4de952..cabbaf2234 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,7 @@ pkg *.rbc lib/bundler/man + +man/* +!man/*.ronn +!man/index.txt diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn index 50408723a3..0f80d535a4 100644 --- a/man/bundle-config.ronn +++ b/man/bundle-config.ronn @@ -48,7 +48,7 @@ Configuration keys in bundler have two forms: the canonical form and the environment variable form. For instance, passing the `--without` flag to `bundle install(1)` prevents -Bundler from installing certain groups specified in the `Gemfile(1)`. Bundler +Bundler from installing certain groups specified in the Gemfile(5). Bundler persists this value in `app/.bundle/config` so that calls to `Bundler.setup` do not try to find gems from the `Gemfile` that you didn't install. Additionally, subsequent calls to `bundle install(1)` remember this setting and skip those diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn index 3f793dbd54..99fa88f45f 100644 --- a/man/bundle-install.ronn +++ b/man/bundle-install.ronn @@ -9,16 +9,16 @@ bundle-install(1) -- Install the dependencies specified in your Gemfile ## DESCRIPTION -Install the gems specified in your `Gemfile(7)`. If this is the first +Install the gems specified in your Gemfile(5). If this is the first time you run bundle install (and a `Gemfile.lock` does not exist), bundler 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`, +If a `Gemfile.lock` does exist, and you have not updated your Gemfile(5), bundler 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`, +If a `Gemfile.lock` does exist, and you have updated your Gemfile(5), bundler 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 @@ -27,9 +27,9 @@ update process below under [CONSERVATIVE UPDATING][]. ## OPTIONS * `--gemfile=<gemfile>`: - The location of the `Gemfile` that bundler should use. This defaults + The location of the Gemfile(5) that bundler should use. This defaults to a gemfile in the current working directory. In general, bundler - will assume that the location of the `Gemfile` is also the project + will assume that the location of the Gemfile(5) is also the project root, and will look for the `Gemfile.lock` and `vendor/cache` relative to it. @@ -81,12 +81,12 @@ defaults optimized for deployment, use the `--deployment` flag. 2. The `Gemfile.lock` must be up to date - In development, you can modify your `Gemfile` and re-run + In development, you can modify your Gemfile(5) and re-run `bundle 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`. + changes made in your Gemfile(5). 3. Gems are installed to `vendor/bundle` not your default system location @@ -134,7 +134,7 @@ the final step. ## INSTALLING GROUPS By default, `bundle install` will install all gems in all groups -in your `Gemfile(7)`, except those declared for a different platform. +in your Gemfile(5), except those declared for a different platform. However, you can explicitly tell bundler to skip installing certain groups with the `--without` option. This option takes @@ -142,7 +142,7 @@ 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`. +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 @@ -155,7 +155,7 @@ 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`: +For a simple illustration, consider the following Gemfile(5): source "http://rubygems.org" @@ -182,7 +182,7 @@ 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`, and can +affects more than just the gems you list in your Gemfile(5), and can (surprisingly) radically change the gems you are using. ## REMEMBERED OPTIONS @@ -224,7 +224,7 @@ The settings that are remembered are: When you run `bundle install`, Bundler will persist the full names and versions of all gems that you used (including dependencies of -the gems specified in the `Gemfile`) into a file called `Gemfile.lock`. +the gems specified in the Gemfile(5)) into a file called `Gemfile.lock`. Bundler uses this file in all subsequent calls to `bundle install`, which guarantees that you always use the same exact code, even @@ -232,26 +232,26 @@ 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`) can result in radically +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` +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` and then run `bundle install`, +When you make a change to the Gemfile(5) and then run `bundle install`, Bundler will update only the gems that you modified. In other words, if a gem that you `did not modify` worked before you called `bundle 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`: +Let's take a look at an example. Here's your original Gemfile(5): source "http://rubygems.org" @@ -265,9 +265,9 @@ and `rack ~> 1.1.0`, while the `activemerchant` gem depends on When the dependencies are first resolved, Bundler will select `activesupport 2.3.8`, which satisfies the requirements of both -gems in your `Gemfile`. +gems in your Gemfile(5). -Next, you modify your `Gemfile` to: +Next, you modify your Gemfile(5) to: source "http://rubygems.org" @@ -295,16 +295,16 @@ 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`, bundler treats -gems in your `Gemfile` that have not changed as an atomic unit +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 `bundle install` will report that it cannot update `actionpack`. To explicitly update `actionpack`, including its dependencies -which other gems in the `Gemfile` still depend on, run +which other gems in the Gemfile(5) still depend on, run `bundle update actionpack` (see `bundle update(1)`). -`Summary`: In general, after making a change to the `Gemfile`, you +`Summary`: In general, after making a change to the Gemfile(5) , you should first try to run `bundle install`, which will guarantee that no -other gems in the `Gemfile` are impacted by the change. If that -does not work, run `bundle update(1)`. +other gems in the Gemfile(5) are impacted by the change. If that +does not work, run [bundle update(1)][bundle-update]. diff --git a/man/bundle-package.ronn b/man/bundle-package.ronn index f7fcf0fce8..f77e536821 100644 --- a/man/bundle-package.ronn +++ b/man/bundle-package.ronn @@ -24,7 +24,7 @@ By default, if you simply run `bundle install(1)` after running to check whether a platform-specific gem exists for any of the gems in `vendor/cache`. -For instance, consider this `Gemfile(7)`: +For instance, consider this Gemfile(5): source "http://rubygems.org" diff --git a/man/bundle-update.ronn b/man/bundle-update.ronn index 5e66c45b80..c701a36dfa 100644 --- a/man/bundle-update.ronn +++ b/man/bundle-update.ronn @@ -18,7 +18,7 @@ gem. ## OPTIONS * `--source=<name>`: - The name of a `:git` or `:path` source used in the `Gemfile`. For + 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 `bundle update --source rails` @@ -28,7 +28,7 @@ If you run `bundle update` with no parameters, bundler 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`: +Consider the following Gemfile(5): source "http://rubygems.org" @@ -67,7 +67,7 @@ all of the dependencies, all the way down, and install what you need: Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed. -As you can see, even though you have just two gems in the `Gemfile(7)`, your application +As you can see, even though you have just two gems in the Gemfile(5), your application actually needs 25 different gems in order to run. Bundler remembers the exact versions it installed in `Gemfile.lock`. The next time you run `bundle install(1)`, bundler skips the dependency resolution and installs the same gems as it installed last time. @@ -78,7 +78,7 @@ last time. You don't need to worry that a new release of `erubis` or `mail` chan 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(7)`. +newest versions that still match the gems in your Gemfile(5). To do this, run `bundle update`, which will ignore the `Gemfile.lock`, and resolve all the dependencies again. Keep in mind that this process can result in a significantly @@ -87,7 +87,7 @@ authors released since the last time you ran `bundle update`. ## UPDATING A LIST OF GEMS -Sometimes, you want to update a single gem in the `Gemfile(7)`, and leave the rest of the +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 @@ -99,7 +99,7 @@ its dependencies. ## OVERLAPPING DEPENDENCIES -Sometimes, multiple gems declared in your `Gemfile(1)` are satisfied by the same +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`. @@ -131,7 +131,7 @@ In this case, the two gems have their own set of dependencies, but they share `In short`, when you update a gem using `bundle update`, bundler 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(7)`, +In this scenario, updating the `thin` version manually in the Gemfile(5), and then running `bundle install(1)` will only update `daemons` and `eventmachine`, but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section of `bundle install(1)`. @@ -141,7 +141,7 @@ of `bundle install(1)`. In general, when working with an application managed with bundler, you should use the following workflow: -* After you create your `Gemfile` for the first time, run +* After you create your Gemfile(5) for the first time, run $ bundle install @@ -157,7 +157,7 @@ use the following workflow: $ bundle install --deployment -* After changing the `Gemfile(7)` to reflect a new or update dependency, run +* After changing the Gemfile(5) to reflect a new or update dependency, run $ bundle install @@ -166,11 +166,11 @@ use the following workflow: $ git add Gemfile.lock * If `bundle install(1)` reports a conflict, manually update the specific - gems that you changed in the `Gemfile(7)` + gems that you changed in the Gemfile(5) $ bundle 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(7)`, run + still match the gems listed in the Gemfile(5), run $ bundle update diff --git a/man/bundle.ronn b/man/bundle.ronn index 1d5fc5c764..8ff559da66 100644 --- a/man/bundle.ronn +++ b/man/bundle.ronn @@ -11,7 +11,7 @@ Bundler manages an `application's dependencies` through its entire life across many machines systematically and repeatably. See [the bundler website](http://gembundler.com) for information on getting -started, and `Gemfile(7)` for more information on the `Gemfile` format. +started, and Gemfile(5) for more information on the `Gemfile` format. ## OPTIONS diff --git a/man/index.txt b/man/index.txt new file mode 100644 index 0000000000..d06d573612 --- /dev/null +++ b/man/index.txt @@ -0,0 +1,2 @@ +Gemfile(5) gemfile.5.ronn +bundle-update bundle-update.ronn |