bundler_package_git 1.1.pre.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (149) hide show
  1. data/.gitignore +22 -0
  2. data/.rvmrc +1 -0
  3. data/CHANGELOG.md +659 -0
  4. data/ISSUES.md +47 -0
  5. data/LICENSE +23 -0
  6. data/README.md +29 -0
  7. data/Rakefile +167 -0
  8. data/UPGRADING.md +103 -0
  9. data/bin/bundle +22 -0
  10. data/bundler.gemspec +30 -0
  11. data/lib/bundler.rb +283 -0
  12. data/lib/bundler/capistrano.rb +11 -0
  13. data/lib/bundler/cli.rb +490 -0
  14. data/lib/bundler/definition.rb +429 -0
  15. data/lib/bundler/dependency.rb +130 -0
  16. data/lib/bundler/deployment.rb +53 -0
  17. data/lib/bundler/dsl.rb +243 -0
  18. data/lib/bundler/environment.rb +47 -0
  19. data/lib/bundler/fetcher.rb +101 -0
  20. data/lib/bundler/gem_helper.rb +146 -0
  21. data/lib/bundler/graph.rb +130 -0
  22. data/lib/bundler/index.rb +131 -0
  23. data/lib/bundler/installer.rb +117 -0
  24. data/lib/bundler/lazy_specification.rb +71 -0
  25. data/lib/bundler/lockfile_parser.rb +108 -0
  26. data/lib/bundler/remote_specification.rb +57 -0
  27. data/lib/bundler/resolver.rb +470 -0
  28. data/lib/bundler/rubygems_ext.rb +226 -0
  29. data/lib/bundler/runtime.rb +201 -0
  30. data/lib/bundler/settings.rb +117 -0
  31. data/lib/bundler/setup.rb +16 -0
  32. data/lib/bundler/shared_helpers.rb +167 -0
  33. data/lib/bundler/source.rb +675 -0
  34. data/lib/bundler/spec_set.rb +134 -0
  35. data/lib/bundler/templates/Executable +16 -0
  36. data/lib/bundler/templates/Gemfile +4 -0
  37. data/lib/bundler/templates/newgem/Gemfile.tt +4 -0
  38. data/lib/bundler/templates/newgem/Rakefile.tt +2 -0
  39. data/lib/bundler/templates/newgem/bin/newgem.tt +3 -0
  40. data/lib/bundler/templates/newgem/gitignore.tt +4 -0
  41. data/lib/bundler/templates/newgem/lib/newgem.rb.tt +7 -0
  42. data/lib/bundler/templates/newgem/lib/newgem/version.rb.tt +7 -0
  43. data/lib/bundler/templates/newgem/newgem.gemspec.tt +21 -0
  44. data/lib/bundler/ui.rb +73 -0
  45. data/lib/bundler/vendor/net/http/faster.rb +27 -0
  46. data/lib/bundler/vendor/net/http/persistent.rb +464 -0
  47. data/lib/bundler/vendor/thor.rb +319 -0
  48. data/lib/bundler/vendor/thor/actions.rb +297 -0
  49. data/lib/bundler/vendor/thor/actions/create_file.rb +105 -0
  50. data/lib/bundler/vendor/thor/actions/directory.rb +93 -0
  51. data/lib/bundler/vendor/thor/actions/empty_directory.rb +134 -0
  52. data/lib/bundler/vendor/thor/actions/file_manipulation.rb +229 -0
  53. data/lib/bundler/vendor/thor/actions/inject_into_file.rb +104 -0
  54. data/lib/bundler/vendor/thor/base.rb +556 -0
  55. data/lib/bundler/vendor/thor/core_ext/file_binary_read.rb +9 -0
  56. data/lib/bundler/vendor/thor/core_ext/hash_with_indifferent_access.rb +75 -0
  57. data/lib/bundler/vendor/thor/core_ext/ordered_hash.rb +100 -0
  58. data/lib/bundler/vendor/thor/error.rb +30 -0
  59. data/lib/bundler/vendor/thor/invocation.rb +168 -0
  60. data/lib/bundler/vendor/thor/parser.rb +4 -0
  61. data/lib/bundler/vendor/thor/parser/argument.rb +67 -0
  62. data/lib/bundler/vendor/thor/parser/arguments.rb +161 -0
  63. data/lib/bundler/vendor/thor/parser/option.rb +120 -0
  64. data/lib/bundler/vendor/thor/parser/options.rb +174 -0
  65. data/lib/bundler/vendor/thor/shell.rb +88 -0
  66. data/lib/bundler/vendor/thor/shell/basic.rb +275 -0
  67. data/lib/bundler/vendor/thor/shell/color.rb +108 -0
  68. data/lib/bundler/vendor/thor/shell/html.rb +121 -0
  69. data/lib/bundler/vendor/thor/task.rb +114 -0
  70. data/lib/bundler/vendor/thor/util.rb +229 -0
  71. data/lib/bundler/vendor/thor/version.rb +3 -0
  72. data/lib/bundler/version.rb +6 -0
  73. data/lib/bundler/vlad.rb +9 -0
  74. data/man/bundle-config.ronn +90 -0
  75. data/man/bundle-exec.ronn +111 -0
  76. data/man/bundle-install.ronn +314 -0
  77. data/man/bundle-package.ronn +59 -0
  78. data/man/bundle-update.ronn +176 -0
  79. data/man/bundle.ronn +80 -0
  80. data/man/gemfile.5.ronn +279 -0
  81. data/man/index.txt +6 -0
  82. data/spec/cache/gems_spec.rb +219 -0
  83. data/spec/cache/git_spec.rb +9 -0
  84. data/spec/cache/path_spec.rb +27 -0
  85. data/spec/cache/platform_spec.rb +57 -0
  86. data/spec/install/deploy_spec.rb +197 -0
  87. data/spec/install/deprecated_spec.rb +37 -0
  88. data/spec/install/gems/c_ext_spec.rb +48 -0
  89. data/spec/install/gems/dependency_api_spec.rb +85 -0
  90. data/spec/install/gems/env_spec.rb +107 -0
  91. data/spec/install/gems/flex_spec.rb +313 -0
  92. data/spec/install/gems/groups_spec.rb +245 -0
  93. data/spec/install/gems/packed_spec.rb +84 -0
  94. data/spec/install/gems/platform_spec.rb +208 -0
  95. data/spec/install/gems/resolving_spec.rb +72 -0
  96. data/spec/install/gems/simple_case_spec.rb +715 -0
  97. data/spec/install/gems/standalone_spec.rb +162 -0
  98. data/spec/install/gems/sudo_spec.rb +73 -0
  99. data/spec/install/gems/win32_spec.rb +26 -0
  100. data/spec/install/gemspec_spec.rb +108 -0
  101. data/spec/install/git_spec.rb +571 -0
  102. data/spec/install/invalid_spec.rb +17 -0
  103. data/spec/install/path_spec.rb +353 -0
  104. data/spec/install/upgrade_spec.rb +26 -0
  105. data/spec/lock/git_spec.rb +35 -0
  106. data/spec/lock/lockfile_spec.rb +683 -0
  107. data/spec/other/check_spec.rb +221 -0
  108. data/spec/other/clean_spec.rb +202 -0
  109. data/spec/other/config_spec.rb +40 -0
  110. data/spec/other/console_spec.rb +54 -0
  111. data/spec/other/exec_spec.rb +241 -0
  112. data/spec/other/ext_spec.rb +16 -0
  113. data/spec/other/gem_helper_spec.rb +128 -0
  114. data/spec/other/help_spec.rb +38 -0
  115. data/spec/other/init_spec.rb +40 -0
  116. data/spec/other/newgem_spec.rb +24 -0
  117. data/spec/other/open_spec.rb +35 -0
  118. data/spec/other/show_spec.rb +82 -0
  119. data/spec/pack/gems_spec.rb +54 -0
  120. data/spec/quality_spec.rb +58 -0
  121. data/spec/resolver/basic_spec.rb +20 -0
  122. data/spec/resolver/platform_spec.rb +82 -0
  123. data/spec/runtime/executable_spec.rb +110 -0
  124. data/spec/runtime/load_spec.rb +107 -0
  125. data/spec/runtime/platform_spec.rb +90 -0
  126. data/spec/runtime/require_spec.rb +231 -0
  127. data/spec/runtime/setup_spec.rb +688 -0
  128. data/spec/runtime/with_clean_env_spec.rb +15 -0
  129. data/spec/spec_helper.rb +85 -0
  130. data/spec/support/artifice/endpoint.rb +50 -0
  131. data/spec/support/artifice/endpoint_fallback.rb +22 -0
  132. data/spec/support/artifice/endpoint_marshal_fail.rb +11 -0
  133. data/spec/support/artifice/endpoint_redirect.rb +11 -0
  134. data/spec/support/builders.rb +574 -0
  135. data/spec/support/fakeweb/rack-1.0.0.marshal +2 -0
  136. data/spec/support/fakeweb/windows.rb +23 -0
  137. data/spec/support/helpers.rb +246 -0
  138. data/spec/support/indexes.rb +112 -0
  139. data/spec/support/matchers.rb +89 -0
  140. data/spec/support/path.rb +73 -0
  141. data/spec/support/platforms.rb +53 -0
  142. data/spec/support/ruby_ext.rb +20 -0
  143. data/spec/support/rubygems_ext.rb +35 -0
  144. data/spec/support/rubygems_hax/platform.rb +11 -0
  145. data/spec/support/sudo.rb +21 -0
  146. data/spec/update/gems_spec.rb +121 -0
  147. data/spec/update/git_spec.rb +196 -0
  148. data/spec/update/source_spec.rb +51 -0
  149. metadata +294 -0
@@ -0,0 +1,3 @@
1
+ class Thor
2
+ VERSION = "0.14.0".freeze
3
+ end
@@ -0,0 +1,6 @@
1
+ module Bundler
2
+ # We're doing this because we might write tests that deal
3
+ # with other versions of bundler and we are unsure how to
4
+ # handle this better.
5
+ VERSION = "1.1.pre.1" unless defined?(::Bundler::VERSION)
6
+ end
@@ -0,0 +1,9 @@
1
+ # Vlad task for Bundler.
2
+ #
3
+ # Just add "require 'bundler/vlad'" in your Vlad deploy.rb, and
4
+ # include the vlad:bundle:install task in your vlad:deploy task.
5
+ require 'bundler/deployment'
6
+
7
+ namespace :vlad do
8
+ Bundler::Deployment.define_task(Rake::RemoteTask, :remote_task, :roles => :app)
9
+ end
@@ -0,0 +1,90 @@
1
+ bundle-config(1) -- Set bundler configuration options
2
+ =====================================================
3
+
4
+ ## SYNOPSIS
5
+
6
+ `bundle config` [<name> [<value>]]
7
+
8
+ ## DESCRIPTION
9
+
10
+ This command allows you to interact with bundler's configuration system.
11
+ Bundler retrieves its configuration from the local application (`app/.bundle/config`),
12
+ environment variables, and the user's home directory (`~/.bundle/config`),
13
+ in that order of priority.
14
+
15
+ Executing `bundle config` with no parameters will print a list of all
16
+ bundler configuration for the current bundle, and where that configuration
17
+ was set.
18
+
19
+ Executing `bundle config <name>` will print the value of that configuration
20
+ setting, and where it was set.
21
+
22
+ Executing `bundle config <name> <value>` will set that configuration to the
23
+ value specified for all bundles executed as the current user. The configuration
24
+ will be stored in `~/.bundle/config`.
25
+
26
+ ## BUILD OPTIONS
27
+
28
+ You can use `bundle config` to give bundler the flags to pass to the gem
29
+ installer every time bundler tries to install a particular gem.
30
+
31
+ A very common example, the `mysql` gem, requires Snow Leopard users to
32
+ pass configuration flags to `gem install` to specify where to find the
33
+ `mysql_config` executable.
34
+
35
+ gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
36
+
37
+ Since the specific location of that executable can change from machine
38
+ to machine, you can specify these flags on a per-machine basis.
39
+
40
+ bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config
41
+
42
+ After running this command, every time bundler needs to install the
43
+ `mysql` gem, it will pass along the flags you specified.
44
+
45
+ ## CONFIGURATION KEYS
46
+
47
+ Configuration keys in bundler have two forms: the canonical form and the
48
+ environment variable form.
49
+
50
+ For instance, passing the `--without` flag to [bundle install(1)][bundle-install]
51
+ prevents Bundler from installing certain groups specified in the Gemfile(5). Bundler
52
+ persists this value in `app/.bundle/config` so that calls to `Bundler.setup`
53
+ do not try to find gems from the `Gemfile` that you didn't install. Additionally,
54
+ subsequent calls to [bundle install(1)][bundle-install] remember this setting and skip those
55
+ groups.
56
+
57
+ The canonical form of this configuration is `"without"`. To convert the canonical
58
+ form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The
59
+ environment variable form of `"without"` is `BUNDLE_WITHOUT`.
60
+
61
+ ## LIST OF AVAILABLE KEYS
62
+
63
+ The following is a list of all configuration keys and their purpose. You can
64
+ learn more about their operation in [bundle install(1)][bundle-install].
65
+
66
+ * `path` (`BUNDLE_PATH`):
67
+ The location on disk to install gems. Defaults to `$GEM_HOME` in development
68
+ and `vendor/bundler` when `--deployment` is used
69
+ * `frozen` (`BUNDLE_FROZEN`):
70
+ Disallow changes to the `Gemfile`. Defaults to `true` when `--deployment`
71
+ is used.
72
+ * `without` (`BUNDLE_WITHOUT`):
73
+ A `:`-separated list of groups whose gems bundler should not install
74
+ * `bin` (`BUNDLE_BIN`):
75
+ Install executables from gems in the bundle to the specified directory.
76
+ Defaults to `false`.
77
+ * `gemfile` (`BUNDLE_GEMFILE`):
78
+ The name of the file that bundler should use as the `Gemfile`. This location
79
+ of this file also sets the root of the project, which is used to resolve
80
+ relative paths in the `Gemfile`, among other things. By default, bundler
81
+ will search up from the current working directory until it finds a
82
+ `Gemfile`.
83
+
84
+ In general, you should set these settings per-application by using the applicable
85
+ flag to the [bundle install(1)][bundle-install] command.
86
+
87
+ You can set them globally either via environment variables or `bundle config`,
88
+ whichever is preferable for your setup. If you use both, environment variables
89
+ will take preference over global settings.
90
+
@@ -0,0 +1,111 @@
1
+ bundle-exec(1) -- Execute a command in the context of the bundle
2
+ ================================================================
3
+
4
+ ## SYNOPSIS
5
+
6
+ `bundle exec` <command>
7
+
8
+ ## DESCRIPTION
9
+
10
+ This command executes the command, making all gems specified in the
11
+ `Gemfile(5)` available to `require` in Ruby programs.
12
+
13
+ Essentially, if you would normally have run something like
14
+ `rspec spec/my_spec.rb`, and you want to use the gems specified
15
+ in the `Gemfile(5)` and installed via [bundle install(1)][bundle-install], you
16
+ should run `bundle exec rspec spec/my_spec.rb`.
17
+
18
+ Note that `bundle exec` does not require that an executable is
19
+ available on your shell's `$PATH`.
20
+
21
+ ## BUNDLE INSTALL --BINSTUBS
22
+
23
+ If you use the `--binstubs` flag in [bundle install(1)][bundle-install], Bundler will
24
+ automatically create a directory (which defaults to `app_root/bin`)
25
+ containing all of the executables available from gems in the bundle.
26
+
27
+ After using `--binstubs`, `bin/rspec spec/my_spec.rb` is identical
28
+ to `bundle exec rspec spec/my_spec.rb`.
29
+
30
+ ## ENVIRONMENT MODIFICATIONS
31
+
32
+ `bundle exec` makes a number of changes to the shell environment,
33
+ then executes the command you specify in full.
34
+
35
+ * make sure that it's still possible to shell out to `bundle`
36
+ from inside a command invoked by `bundle exec` (using
37
+ `$BUNDLE_BIN_PATH`)
38
+ * put the directory containing executables (like `rails`, `rspec`,
39
+ `rackup`) for your bundle on `$PATH`
40
+ * make sure that if bundler is invoked in the subshell, it uses
41
+ the same `Gemfile` (by setting `BUNDLE_GEMFILE`)
42
+ * add `-rbundler/setup` to `$RUBYOPT`, which makes sure that
43
+ Ruby programs invoked in the subshell can see the gems in
44
+ the bundle
45
+
46
+ It also modifies Rubygems:
47
+
48
+ * disallow loading additional gems not in the bundle
49
+ * modify the `gem` method to be a no-op if a gem matching
50
+ the requirements is in the bundle, and to raise a
51
+ `Gem::LoadError` if it's not
52
+ * Define `Gem.refresh` to be a no-op, since the source
53
+ index is always frozen when using bundler, and to
54
+ prevent gems from the system leaking into the environment
55
+ * Override `Gem.bin_path` to use the gems in the bundle,
56
+ making system executables work
57
+ * Add all gems in the bundle into Gem.loaded_specs
58
+
59
+ ### Shelling out
60
+
61
+ When shelling out (using the `system` or backticks methods,
62
+ for example), Bundler's environment changes will propogate to
63
+ the subshell environment. If you desire to shell out without
64
+ Bundler's environment changes, simply employ the `with_clean_env`
65
+ method. It will restore all environment variables to what they
66
+ were before Bundler was activated. For example:
67
+
68
+ Bundler.with_clean_env do
69
+ `brew install wget`
70
+ end
71
+
72
+ ## RUBYGEMS PLUGINS
73
+
74
+ At present, the Rubygems plugin system requires all files
75
+ named `rubygems_plugin.rb` on the load path of _any_ installed
76
+ gem when any Ruby code requires `rubygems.rb`. This includes
77
+ executables installed into the system, like `rails`, `rackup`,
78
+ and `rspec`.
79
+
80
+ Since Rubygems plugins can contain arbitrary Ruby code, they
81
+ commonly end up activating themselves or their dependencies.
82
+
83
+ For instance, the `gemcutter 0.5` gem depended on `json_pure`.
84
+ If you had that version of gemcutter installed (even if
85
+ you _also_ had a newer version without this problem), Rubygems
86
+ would activate `gemcutter 0.5` and `json_pure <latest>`.
87
+
88
+ If your Gemfile(5) also contained `json_pure` (or a gem
89
+ with a dependency on `json_pure`), the latest version on
90
+ your system might conflict with the version in your
91
+ Gemfile(5), or the snapshot version in your `Gemfile.lock`.
92
+
93
+ If this happens, bundler will say:
94
+
95
+ You have already activated json_pure 1.4.6 but your Gemfile
96
+ requires json_pure 1.4.3. Consider using bundle exec.
97
+
98
+ In this situation, you almost certainly want to remove the
99
+ underlying gem with the problematic gem plugin. In general,
100
+ the authors of these plugins (in this case, the `gemcutter`
101
+ gem) have released newer versions that are more careful in
102
+ their plugins.
103
+
104
+ You can find a list of all the gems containing gem plugins
105
+ by running
106
+
107
+ ruby -rubygems -e "puts Gem.find_files('rubygems_plugin.rb')"
108
+
109
+ At the very least, you should remove all but the newest
110
+ version of each gem plugin, and also remove all gem plugins
111
+ that you aren't using (`gem uninstall gem_name`).
@@ -0,0 +1,314 @@
1
+ bundle-install(1) -- Install the dependencies specified in your Gemfile
2
+ =======================================================================
3
+
4
+ ## SYNOPSIS
5
+
6
+ `bundle install` [--gemfile=GEMFILE]
7
+ [--path PATH] [--system]
8
+ [--without=GROUP1[ GROUP2...]]
9
+ [--local] [--deployment]
10
+ [--binstubs[=DIRECTORY]]
11
+ [--quiet]
12
+
13
+ ## DESCRIPTION
14
+
15
+ Install the gems specified in your Gemfile(5). If this is the first
16
+ time you run bundle install (and a `Gemfile.lock` does not exist),
17
+ bundler will fetch all remote sources, resolve dependencies and
18
+ install all needed gems.
19
+
20
+ If a `Gemfile.lock` does exist, and you have not updated your Gemfile(5),
21
+ bundler will fetch all remote sources, but use the dependencies
22
+ specified in the `Gemfile.lock` instead of resolving dependencies.
23
+
24
+ If a `Gemfile.lock` does exist, and you have updated your Gemfile(5),
25
+ bundler will use the dependencies in the `Gemfile.lock` for all gems
26
+ that you did not update, but will re-resolve the dependencies of
27
+ gems that you did update. You can find more information about this
28
+ update process below under [CONSERVATIVE UPDATING][].
29
+
30
+ ## OPTIONS
31
+
32
+ * `--gemfile=<gemfile>`:
33
+ The location of the Gemfile(5) that bundler should use. This defaults
34
+ to a gemfile in the current working directory. In general, bundler
35
+ will assume that the location of the Gemfile(5) is also the project
36
+ root, and will look for the `Gemfile.lock` and `vendor/cache` relative
37
+ to it.
38
+
39
+ * `--path=<path>`:
40
+ The location to install the gems in the bundle to. This defaults
41
+ to the gem home, which is the location that `gem install` installs
42
+ gems to. This means that, by default, gems installed without a
43
+ `--path` setting will show up in `gem list`. This setting is a
44
+ [remembered option][REMEMBERED OPTIONS].
45
+
46
+ * `--system`:
47
+ Installs the gems in the bundle to the system location. This
48
+ overrides any previous [remembered][REMEMBERED OPTIONS] use of
49
+ `--path`.
50
+
51
+ * `--without=<list>`:
52
+ A space-separated list of groups to skip installing. This is a
53
+ [remembered option][REMEMBERED OPTIONS].
54
+
55
+ * `--local`:
56
+ Do not attempt to connect to `rubygems.org`, instead using just
57
+ the gems located in `vendor/cache`. Note that if a more
58
+ appropriate platform-specific gem exists on `rubygems.org`,
59
+ this will bypass the normal lookup.
60
+
61
+ * `--deployment`:
62
+ Switches bundler's defaults into [deployment mode][DEPLOYMENT MODE].
63
+
64
+ * `--binstubs[=<directory>]`:
65
+ Create a directory (defaults to `bin`) containing an executable
66
+ that runs in the context of the bundle. For instance, if the
67
+ `rails` gem comes with a `rails` executable, this flag will create
68
+ a `bin/rails` executable that ensures that all dependencies used
69
+ come from the bundled gems.
70
+
71
+ ## DEPLOYMENT MODE
72
+
73
+ Bundler's defaults are optimized for development. To switch to
74
+ defaults optimized for deployment, use the `--deployment` flag.
75
+
76
+ 1. A `Gemfile.lock` is required.
77
+
78
+ To ensure that the same versions of the gems you developed with
79
+ and tested with are also used in deployments, a `Gemfile.lock`
80
+ is required.
81
+
82
+ This is mainly to ensure that you remember to check your
83
+ `Gemfile.lock` into version control.
84
+
85
+ 2. The `Gemfile.lock` must be up to date
86
+
87
+ In development, you can modify your Gemfile(5) and re-run
88
+ `bundle install` to [conservatively update][CONSERVATIVE UPDATING]
89
+ your `Gemfile.lock` snapshot.
90
+
91
+ In deployment, your `Gemfile.lock` should be up-to-date with
92
+ changes made in your Gemfile(5).
93
+
94
+ 3. Gems are installed to `vendor/bundle` not your default system location
95
+
96
+ In development, it's convenient to share the gems used in your
97
+ application with other applications and other scripts run on
98
+ the system.
99
+
100
+ In deployment, isolation is a more important default. In addition,
101
+ the user deploying the application may not have permission to install
102
+ gems to the system, or the web server may not have permission to
103
+ read them.
104
+
105
+ As a result, `bundle install --deployment` installs gems to
106
+ the `vendor/bundle` directory in the application. This may be
107
+ overridden using the `--path` option.
108
+
109
+ ## SUDO USAGE
110
+
111
+ By default, bundler installs gems to the same location as `gem install`.
112
+
113
+ In some cases, that location may not be writable by your Unix user. In
114
+ that case, bundler will stage everything in a temporary directory,
115
+ then ask you for your `sudo` password in order to copy the gems into
116
+ their system location.
117
+
118
+ From your perspective, this is identical to installing them gems
119
+ directly into the system.
120
+
121
+ You should never use `sudo bundle install`. This is because several
122
+ other steps in `bundle install` must be performed as the current user:
123
+
124
+ * Updating your `Gemfile.lock`
125
+ * Updating your `vendor/cache`, if necessary
126
+ * Checking out private git repositories using your user's SSH keys
127
+
128
+ Of these three, the first two could theoretically be performed by
129
+ `chown`ing the resulting files to `$SUDO_USER`. The third, however,
130
+ can only be performed by actually invoking the `git` command as
131
+ the current user. Therefore, git gems are downloaded and installed
132
+ into `~/.bundle` rather than $GEM_HOME or $BUNDLE_PATH.
133
+
134
+ As a result, you should run `bundle install` as the current user,
135
+ and bundler will ask for your password if it is needed to put the
136
+ gems into their final location.
137
+
138
+ ## INSTALLING GROUPS
139
+
140
+ By default, `bundle install` will install all gems in all groups
141
+ in your Gemfile(5), except those declared for a different platform.
142
+
143
+ However, you can explicitly tell bundler to skip installing
144
+ certain groups with the `--without` option. This option takes
145
+ a space-separated list of groups.
146
+
147
+ While the `--without` option will skip _installing_ the gems in the
148
+ specified groups, it will still _download_ those gems and use them to
149
+ resolve the dependencies of every gem in your Gemfile(5).
150
+
151
+ This is so that installing a different set of groups on another
152
+ machine (such as a production server) will not change the
153
+ gems and versions that you have already developed and tested against.
154
+
155
+ `Bundler offers a rock-solid guarantee that the third-party
156
+ code you are running in development and testing is also the
157
+ third-party code you are running in production. You can choose
158
+ to exclude some of that code in different environments, but you
159
+ will never be caught flat-footed by different versions of
160
+ third-party code being used in different environments.`
161
+
162
+ For a simple illustration, consider the following Gemfile(5):
163
+
164
+ source "http://rubygems.org"
165
+
166
+ gem "sinatra"
167
+
168
+ group :production do
169
+ gem "rack-perftools-profiler"
170
+ end
171
+
172
+ In this case, `sinatra` depends on any version of Rack (`>= 1.0`, while
173
+ `rack-perftools-profiler` depends on 1.x (`~> 1.0`).
174
+
175
+ When you run `bundle install --without production` in development, we
176
+ look at the dependencies of `rack-perftools-profiler` as well. That way,
177
+ you do not spend all your time developing against Rack 2.0, using new
178
+ APIs unavailable in Rack 1.x, only to have bundler switch to Rack 1.2
179
+ when the `production` group _is_ used.
180
+
181
+ This should not cause any problems in practice, because we do not
182
+ attempt to `install` the gems in the excluded groups, and only evaluate
183
+ as part of the dependency resolution process.
184
+
185
+ This also means that you cannot include different versions of the same
186
+ gem in different groups, because doing so would result in different
187
+ sets of dependencies used in development and production. Because of
188
+ the vagaries of the dependency resolution process, this usually
189
+ affects more than just the gems you list in your Gemfile(5), and can
190
+ (surprisingly) radically change the gems you are using.
191
+
192
+ ## REMEMBERED OPTIONS
193
+
194
+ Some options (marked above in the [OPTIONS][] section) are remembered
195
+ between calls to `bundle install`, and by the Bundler runtime.
196
+
197
+ For instance, if you run `bundle install --without test`, a subsequent
198
+ call to `bundle install` that does not include a `--without` flag will
199
+ remember your previous choice.
200
+
201
+ In addition, a call to `Bundler.setup` will not attempt to make the
202
+ gems in those groups available on the Ruby load path, as they were
203
+ not installed.
204
+
205
+ The settings that are remembered are:
206
+
207
+ * `--deployment`:
208
+ At runtime, this remembered setting will also result in Bundler
209
+ raising an exception if the `Gemfile.lock` is out of date.
210
+
211
+ * `--path`:
212
+ Subsequent calls to `bundle install` will install gems to the
213
+ directory originally passed to `--path`. The Bundler runtime
214
+ will look for gems in that location. You can revert this
215
+ option by running `bundle install --system`.
216
+
217
+ * `--binstubs`:
218
+ Bundler will update the executables every subsequent call to
219
+ `bundle install`.
220
+
221
+ * `--without`:
222
+ As described above, Bundler will skip the gems specified by
223
+ `--without` in subsequent calls to `bundle install`. The
224
+ Bundler runtime will also not try to make the gems in the
225
+ skipped groups available.
226
+
227
+ ## THE GEMFILE.LOCK
228
+
229
+ When you run `bundle install`, Bundler will persist the full names
230
+ and versions of all gems that you used (including dependencies of
231
+ the gems specified in the Gemfile(5)) into a file called `Gemfile.lock`.
232
+
233
+ Bundler uses this file in all subsequent calls to `bundle install`,
234
+ which guarantees that you always use the same exact code, even
235
+ as your application moves across machines.
236
+
237
+ Because of the way dependency resolution works, even a
238
+ seemingly small change (for instance, an update to a point-release
239
+ of a dependency of a gem in your Gemfile(5)) can result in radically
240
+ different gems being needed to satisfy all dependencies.
241
+
242
+ As a result, you `SHOULD` check your `Gemfile.lock` into version
243
+ control. If you do not, every machine that checks out your
244
+ repository (including your production server) will resolve all
245
+ dependencies again, which will result in different versions of
246
+ third-party code being used if `any` of the gems in the Gemfile(5)
247
+ or any of their dependencies have been updated.
248
+
249
+ ## CONSERVATIVE UPDATING
250
+
251
+ When you make a change to the Gemfile(5) and then run `bundle install`,
252
+ Bundler will update only the gems that you modified.
253
+
254
+ In other words, if a gem that you `did not modify` worked before
255
+ you called `bundle install`, it will continue to use the exact
256
+ same versions of all dependencies as it used before the update.
257
+
258
+ Let's take a look at an example. Here's your original Gemfile(5):
259
+
260
+ source "http://rubygems.org"
261
+
262
+ gem "actionpack", "2.3.8"
263
+ gem "activemerchant"
264
+
265
+ In this case, both `actionpack` and `activemerchant` depend on
266
+ `activesupport`. The `actionpack` gem depends on `activesupport 2.3.8`
267
+ and `rack ~> 1.1.0`, while the `activemerchant` gem depends on
268
+ `activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`.
269
+
270
+ When the dependencies are first resolved, Bundler will select
271
+ `activesupport 2.3.8`, which satisfies the requirements of both
272
+ gems in your Gemfile(5).
273
+
274
+ Next, you modify your Gemfile(5) to:
275
+
276
+ source "http://rubygems.org"
277
+
278
+ gem "actionpack", "3.0.0.rc"
279
+ gem "activemerchant"
280
+
281
+ The `actionpack 3.0.0.rc` gem has a number of new dependencies,
282
+ and updates the `activesupport` dependency to `= 3.0.0.rc` and
283
+ the `rack` dependency to `~> 1.2.1`.
284
+
285
+ When you run `bundle install`, Bundler notices that you changed
286
+ the `actionpack` gem, but not the `activemerchant` gem. It
287
+ evaluates the gems currently being used to satisfy its requirements:
288
+
289
+ * `activesupport 2.3.8`:
290
+ also used to satisfy a dependency in `activemerchant`,
291
+ which is not being updated
292
+ * `rack ~> 1.1.0`:
293
+ not currently being used to satify another dependency
294
+
295
+ Because you did not explicitly ask to update `activemerchant`,
296
+ you would not expect it to suddenly stop working after updating
297
+ `actionpack`. However, satisfying the new `activesupport 3.0.0.rc`
298
+ dependency of actionpack requires updating one of its dependencies.
299
+
300
+ Even though `activemerchant` declares a very loose dependency
301
+ that theoretically matches `activesupport 3.0.0.rc`, bundler treats
302
+ gems in your Gemfile(5) that have not changed as an atomic unit
303
+ together with their dependencies. In this case, the `activemerchant`
304
+ dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`,
305
+ so `bundle install` will report that it cannot update `actionpack`.
306
+
307
+ To explicitly update `actionpack`, including its dependencies
308
+ which other gems in the Gemfile(5) still depend on, run
309
+ `bundle update actionpack` (see `bundle update(1)`).
310
+
311
+ `Summary`: In general, after making a change to the Gemfile(5) , you
312
+ should first try to run `bundle install`, which will guarantee that no
313
+ other gems in the Gemfile(5) are impacted by the change. If that
314
+ does not work, run [bundle update(1)][bundle-update].