mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
[rubygems/rubygems] Rebuild bundler man pages
* Recently built man pages on my branch had odd whitespace/characters
resulting from using the macOS installed version of groff (v1.19) and
homebrew's (v1.24)
* Followed the advice in this pull request:
https://github.com/rubygems/rubygems/pull/3394
* Encountered invalid byte sequence sed error, found this link:
https://lists.gnu.org/archive/html/groff/2014-10/msg00072.html
f379d1d70e
This commit is contained in:
Frank Lam
Hiroshi SHIBATA
parent
f75bd9bb8b
commit
3c9d3d18f6
Notes:
git
2020-06-05 07:33:55 +09:00
7 changed files with 263 additions and 263 deletions
|
|
@ -9,8 +9,8 @@ SYNOPSIS
|
||||||
bundle check [--dry-run] [--gemfile=FILE] [--path=PATH]
|
bundle check [--dry-run] [--gemfile=FILE] [--path=PATH]
|
||||||
|
|
||||||
DESCRIPTION
|
DESCRIPTION
|
||||||
check searches the local machine for each of the gems requested in the
|
check searches the local machine for each of the gems requested in the
|
||||||
Gemfile. If all gems are found, Bundler prints a success message and
|
Gemfile. If all gems are found, Bundler prints a success message and
|
||||||
exits with a status of 0.
|
exits with a status of 0.
|
||||||
|
|
||||||
If not, the first missing gem is listed and Bundler exits status 1.
|
If not, the first missing gem is listed and Bundler exits status 1.
|
||||||
|
|
@ -23,8 +23,8 @@ OPTIONS
|
||||||
Use the specified gemfile instead of the
|
Use the specified gemfile instead of the
|
||||||
[Gemfile(5)][Gemfile(5)].
|
[Gemfile(5)][Gemfile(5)].
|
||||||
|
|
||||||
--path Specify a different path than the system default ($BUNDLE_PATH
|
--path Specify a different path than the system default ($BUNDLE_PATH
|
||||||
or $GEM_HOME). Bundler will remember this value for future
|
or $GEM_HOME). Bundler will remember this value for future
|
||||||
installs on this machine.
|
installs on this machine.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -68,29 +68,29 @@ REMEMBERING OPTIONS
|
||||||
foo or --without production, are remembered between commands and saved
|
foo or --without production, are remembered between commands and saved
|
||||||
to your local application's configuration (normally, ./.bundle/config).
|
to your local application's configuration (normally, ./.bundle/config).
|
||||||
|
|
||||||
However, this will be changed in bundler 3, so it's better not to rely
|
However, this will be changed in bundler 3, so it's better not to rely
|
||||||
on this behavior. If these options must be remembered, it's better to
|
on this behavior. If these options must be remembered, it's better to
|
||||||
set them using bundle config (e.g., bundle config set path foo).
|
set them using bundle config (e.g., bundle config set path foo).
|
||||||
|
|
||||||
The options that can be configured are:
|
The options that can be configured are:
|
||||||
|
|
||||||
bin Creates a directory (defaults to ~/bin) and place any
|
bin Creates a directory (defaults to ~/bin) and place any
|
||||||
executables from the gem there. These executables run in
|
executables from the gem there. These executables run in
|
||||||
Bundler's context. If used, you might add this directory to your
|
Bundler's context. If used, you might add this directory to your
|
||||||
environment's PATH variable. For instance, if the rails gem
|
environment's PATH variable. For instance, if the rails gem
|
||||||
comes with a rails executable, this flag will create a bin/rails
|
comes with a rails executable, this flag will create a bin/rails
|
||||||
executable that ensures that all referred dependencies will be
|
executable that ensures that all referred dependencies will be
|
||||||
resolved using the bundled gems.
|
resolved using the bundled gems.
|
||||||
|
|
||||||
deployment
|
deployment
|
||||||
In deployment mode, Bundler will 'roll-out' the bundle for
|
In deployment mode, Bundler will 'roll-out' the bundle for
|
||||||
production use. Please check carefully if you want to have this
|
production use. Please check carefully if you want to have this
|
||||||
option enabled in development or test environments.
|
option enabled in development or test environments.
|
||||||
|
|
||||||
path The location to install the specified gems to. This defaults to
|
path The location to install the specified gems to. This defaults to
|
||||||
Rubygems' setting. Bundler shares this location with Rubygems,
|
Rubygems' setting. Bundler shares this location with Rubygems,
|
||||||
gem install ... will have gem installed there, too. Therefore,
|
gem install ... will have gem installed there, too. Therefore,
|
||||||
gems installed without a --path ... setting will show up by
|
gems installed without a --path ... setting will show up by
|
||||||
calling gem list. Accordingly, gems installed to other locations
|
calling gem list. Accordingly, gems installed to other locations
|
||||||
will not get listed.
|
will not get listed.
|
||||||
|
|
||||||
|
|
@ -98,15 +98,15 @@ REMEMBERING OPTIONS
|
||||||
A space-separated list of groups referencing gems to skip during
|
A space-separated list of groups referencing gems to skip during
|
||||||
installation.
|
installation.
|
||||||
|
|
||||||
with A space-separated list of groups referencing gems to include
|
with A space-separated list of groups referencing gems to include
|
||||||
during installation.
|
during installation.
|
||||||
|
|
||||||
BUILD OPTIONS
|
BUILD OPTIONS
|
||||||
You can use bundle config to give Bundler the flags to pass to the gem
|
You can use bundle config to give Bundler the flags to pass to the gem
|
||||||
installer every time bundler tries to install a particular gem.
|
installer every time bundler tries to install a particular gem.
|
||||||
|
|
||||||
A very common example, the mysql gem, requires Snow Leopard users to
|
A very common example, the mysql gem, requires Snow Leopard users to
|
||||||
pass configuration flags to gem install to specify where to find the
|
pass configuration flags to gem install to specify where to find the
|
||||||
mysql_config executable.
|
mysql_config executable.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -115,7 +115,7 @@ BUILD OPTIONS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Since the specific location of that executable can change from machine
|
Since the specific location of that executable can change from machine
|
||||||
to machine, you can specify these flags on a per-machine basis.
|
to machine, you can specify these flags on a per-machine basis.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -124,44 +124,44 @@ BUILD OPTIONS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
After running this command, every time bundler needs to install the
|
After running this command, every time bundler needs to install the
|
||||||
mysql gem, it will pass along the flags you specified.
|
mysql gem, it will pass along the flags you specified.
|
||||||
|
|
||||||
CONFIGURATION KEYS
|
CONFIGURATION KEYS
|
||||||
Configuration keys in bundler have two forms: the canonical form and
|
Configuration keys in bundler have two forms: the canonical form and
|
||||||
the environment variable form.
|
the environment variable form.
|
||||||
|
|
||||||
For instance, passing the --without flag to bundle install(1)
|
For instance, passing the --without flag to bundle install(1)
|
||||||
bundle-install.1.html prevents Bundler from installing certain groups
|
bundle-install.1.html prevents Bundler from installing certain groups
|
||||||
specified in the Gemfile(5). Bundler persists this value in
|
specified in the Gemfile(5). Bundler persists this value in
|
||||||
app/.bundle/config so that calls to Bundler.setup do not try to find
|
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
|
gems from the Gemfile that you didn't install. Additionally, subsequent
|
||||||
calls to bundle install(1) bundle-install.1.html remember this setting
|
calls to bundle install(1) bundle-install.1.html remember this setting
|
||||||
and skip those groups.
|
and skip those groups.
|
||||||
|
|
||||||
The canonical form of this configuration is "without". To convert the
|
The canonical form of this configuration is "without". To convert the
|
||||||
canonical form to the environment variable form, capitalize it, and
|
canonical form to the environment variable form, capitalize it, and
|
||||||
prepend BUNDLE_. The environment variable form of "without" is
|
prepend BUNDLE_. The environment variable form of "without" is
|
||||||
BUNDLE_WITHOUT.
|
BUNDLE_WITHOUT.
|
||||||
|
|
||||||
Any periods in the configuration keys must be replaced with two
|
Any periods in the configuration keys must be replaced with two
|
||||||
underscores when setting it via environment variables. The
|
underscores when setting it via environment variables. The
|
||||||
configuration key local.rack becomes the environment variable
|
configuration key local.rack becomes the environment variable
|
||||||
BUNDLE_LOCAL__RACK.
|
BUNDLE_LOCAL__RACK.
|
||||||
|
|
||||||
LIST OF AVAILABLE KEYS
|
LIST OF AVAILABLE KEYS
|
||||||
The following is a list of all configuration keys and their purpose.
|
The following is a list of all configuration keys and their purpose.
|
||||||
You can learn more about their operation in bundle install(1)
|
You can learn more about their operation in bundle install(1)
|
||||||
bundle-install.1.html.
|
bundle-install.1.html.
|
||||||
|
|
||||||
o allow_bundler_dependency_conflicts
|
o allow_bundler_dependency_conflicts
|
||||||
(BUNDLE_ALLOW_BUNDLER_DEPENDENCY_CONFLICTS): Allow resolving to
|
(BUNDLE_ALLOW_BUNDLER_DEPENDENCY_CONFLICTS): Allow resolving to
|
||||||
specifications that have dependencies on bundler that are
|
specifications that have dependencies on bundler that are
|
||||||
incompatible with the running Bundler version.
|
incompatible with the running Bundler version.
|
||||||
|
|
||||||
o allow_deployment_source_credential_changes
|
o allow_deployment_source_credential_changes
|
||||||
(BUNDLE_ALLOW_DEPLOYMENT_SOURCE_CREDENTIAL_CHANGES): When in
|
(BUNDLE_ALLOW_DEPLOYMENT_SOURCE_CREDENTIAL_CHANGES): When in
|
||||||
deployment mode, allow changing the credentials to a gem's source.
|
deployment mode, allow changing the credentials to a gem's source.
|
||||||
Ex: https://some.host.com/gems/path/ ->
|
Ex: https://some.host.com/gems/path/ ->
|
||||||
https://user_name:password@some.host.com/gems/path
|
https://user_name:password@some.host.com/gems/path
|
||||||
|
|
||||||
|
|
@ -169,64 +169,64 @@ LIST OF AVAILABLE KEYS
|
||||||
to use cached data when installing without network access.
|
to use cached data when installing without network access.
|
||||||
|
|
||||||
o auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH):
|
o auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH):
|
||||||
Automatically run bundle clean after installing when an explicit
|
Automatically run bundle clean after installing when an explicit
|
||||||
path has not been set and Bundler is not installing into the system
|
path has not been set and Bundler is not installing into the system
|
||||||
gems.
|
gems.
|
||||||
|
|
||||||
o auto_install (BUNDLE_AUTO_INSTALL): Automatically run bundle
|
o auto_install (BUNDLE_AUTO_INSTALL): Automatically run bundle
|
||||||
install when gems are missing.
|
install when gems are missing.
|
||||||
|
|
||||||
o bin (BUNDLE_BIN): Install executables from gems in the bundle to
|
o bin (BUNDLE_BIN): Install executables from gems in the bundle to
|
||||||
the specified directory. Defaults to false.
|
the specified directory. Defaults to false.
|
||||||
|
|
||||||
o cache_all (BUNDLE_CACHE_ALL): Cache all gems, including path and
|
o cache_all (BUNDLE_CACHE_ALL): Cache all gems, including path and
|
||||||
git gems.
|
git gems.
|
||||||
|
|
||||||
o cache_all_platforms (BUNDLE_CACHE_ALL_PLATFORMS): Cache gems for
|
o cache_all_platforms (BUNDLE_CACHE_ALL_PLATFORMS): Cache gems for
|
||||||
all platforms.
|
all platforms.
|
||||||
|
|
||||||
o cache_path (BUNDLE_CACHE_PATH): The directory that bundler will
|
o cache_path (BUNDLE_CACHE_PATH): The directory that bundler will
|
||||||
place cached gems in when running bundle package, and that bundler
|
place cached gems in when running bundle package, and that bundler
|
||||||
will look in when installing gems. Defaults to vendor/cache.
|
will look in when installing gems. Defaults to vendor/cache.
|
||||||
|
|
||||||
o clean (BUNDLE_CLEAN): Whether Bundler should run bundle clean
|
o clean (BUNDLE_CLEAN): Whether Bundler should run bundle clean
|
||||||
automatically after bundle install.
|
automatically after bundle install.
|
||||||
|
|
||||||
o console (BUNDLE_CONSOLE): The console that bundle console starts.
|
o console (BUNDLE_CONSOLE): The console that bundle console starts.
|
||||||
Defaults to irb.
|
Defaults to irb.
|
||||||
|
|
||||||
o default_install_uses_path (BUNDLE_DEFAULT_INSTALL_USES_PATH):
|
o default_install_uses_path (BUNDLE_DEFAULT_INSTALL_USES_PATH):
|
||||||
Whether a bundle install without an explicit --path argument
|
Whether a bundle install without an explicit --path argument
|
||||||
defaults to installing gems in .bundle.
|
defaults to installing gems in .bundle.
|
||||||
|
|
||||||
o deployment (BUNDLE_DEPLOYMENT): Disallow changes to the Gemfile.
|
o deployment (BUNDLE_DEPLOYMENT): Disallow changes to the Gemfile.
|
||||||
When the Gemfile is changed and the lockfile has not been updated,
|
When the Gemfile is changed and the lockfile has not been updated,
|
||||||
running Bundler commands will be blocked.
|
running Bundler commands will be blocked.
|
||||||
|
|
||||||
o disable_checksum_validation (BUNDLE_DISABLE_CHECKSUM_VALIDATION):
|
o disable_checksum_validation (BUNDLE_DISABLE_CHECKSUM_VALIDATION):
|
||||||
Allow installing gems even if they do not match the checksum
|
Allow installing gems even if they do not match the checksum
|
||||||
provided by RubyGems.
|
provided by RubyGems.
|
||||||
|
|
||||||
o disable_exec_load (BUNDLE_DISABLE_EXEC_LOAD): Stop Bundler from
|
o disable_exec_load (BUNDLE_DISABLE_EXEC_LOAD): Stop Bundler from
|
||||||
using load to launch an executable in-process in bundle exec.
|
using load to launch an executable in-process in bundle exec.
|
||||||
|
|
||||||
o disable_local_branch_check (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK):
|
o disable_local_branch_check (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK):
|
||||||
Allow Bundler to use a local git override without a branch
|
Allow Bundler to use a local git override without a branch
|
||||||
specified in the Gemfile.
|
specified in the Gemfile.
|
||||||
|
|
||||||
o disable_multisource (BUNDLE_DISABLE_MULTISOURCE): When set,
|
o disable_multisource (BUNDLE_DISABLE_MULTISOURCE): When set,
|
||||||
Gemfiles containing multiple sources will produce errors instead of
|
Gemfiles containing multiple sources will produce errors instead of
|
||||||
warnings. Use bundle config unset disable_multisource to unset.
|
warnings. Use bundle config unset disable_multisource to unset.
|
||||||
|
|
||||||
o disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS): Stop Bundler from
|
o disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS): Stop Bundler from
|
||||||
accessing gems installed to RubyGems' normal location.
|
accessing gems installed to RubyGems' normal location.
|
||||||
|
|
||||||
o disable_version_check (BUNDLE_DISABLE_VERSION_CHECK): Stop Bundler
|
o disable_version_check (BUNDLE_DISABLE_VERSION_CHECK): Stop Bundler
|
||||||
from checking if a newer Bundler version is available on
|
from checking if a newer Bundler version is available on
|
||||||
rubygems.org.
|
rubygems.org.
|
||||||
|
|
||||||
o force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM): Ignore the
|
o force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM): Ignore the
|
||||||
current machine's platform and install only ruby platform gems. As
|
current machine's platform and install only ruby platform gems. As
|
||||||
a result, gems with native extensions will be compiled from source.
|
a result, gems with native extensions will be compiled from source.
|
||||||
|
|
||||||
o frozen (BUNDLE_FROZEN): Disallow changes to the Gemfile. When the
|
o frozen (BUNDLE_FROZEN): Disallow changes to the Gemfile. When the
|
||||||
|
|
|
||||||
|
|
@ -193,14 +193,14 @@ DEPLOYMENT MODE
|
||||||
|
|
||||||
|
|
||||||
SUDO USAGE
|
SUDO USAGE
|
||||||
By default, Bundler installs gems to the same location as gem install.
|
By default, Bundler installs gems to the same location as gem install.
|
||||||
|
|
||||||
In some cases, that location may not be writable by your Unix user. In
|
In some cases, that location may not be writable by your Unix user. In
|
||||||
that case, Bundler will stage everything in a temporary directory, then
|
that case, Bundler will stage everything in a temporary directory, then
|
||||||
ask you for your sudo password in order to copy the gems into their
|
ask you for your sudo password in order to copy the gems into their
|
||||||
system location.
|
system location.
|
||||||
|
|
||||||
From your perspective, this is identical to installing the gems
|
From your perspective, this is identical to installing the gems
|
||||||
directly into the system.
|
directly into the system.
|
||||||
|
|
||||||
You should never use sudo bundle install. This is because several other
|
You should never use sudo bundle install. This is because several other
|
||||||
|
|
@ -214,37 +214,37 @@ SUDO USAGE
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Of these three, the first two could theoretically be performed by
|
Of these three, the first two could theoretically be performed by
|
||||||
chowning the resulting files to $SUDO_USER. The third, however, can
|
chowning the resulting files to $SUDO_USER. The third, however, can
|
||||||
only be performed by invoking the git command as the current user.
|
only be performed by invoking the git command as the current user.
|
||||||
Therefore, git gems are downloaded and installed into ~/.bundle rather
|
Therefore, git gems are downloaded and installed into ~/.bundle rather
|
||||||
than $GEM_HOME or $BUNDLE_PATH.
|
than $GEM_HOME or $BUNDLE_PATH.
|
||||||
|
|
||||||
As a result, you should run bundle install as the current user, and
|
As a result, you should run bundle install as the current user, and
|
||||||
Bundler will ask for your password if it is needed to put the gems into
|
Bundler will ask for your password if it is needed to put the gems into
|
||||||
their final location.
|
their final location.
|
||||||
|
|
||||||
INSTALLING GROUPS
|
INSTALLING GROUPS
|
||||||
By default, bundle install will install all gems in all groups in your
|
By default, bundle install will install all gems in all groups in your
|
||||||
Gemfile(5), except those declared for a different platform.
|
Gemfile(5), except those declared for a different platform.
|
||||||
|
|
||||||
However, you can explicitly tell Bundler to skip installing certain
|
However, you can explicitly tell Bundler to skip installing certain
|
||||||
groups with the --without option. This option takes a space-separated
|
groups with the --without option. This option takes a space-separated
|
||||||
list of groups.
|
list of groups.
|
||||||
|
|
||||||
While the --without option will skip installing the gems in the
|
While the --without option will skip installing the gems in the
|
||||||
specified groups, it will still download those gems and use them to
|
specified groups, it will still download those gems and use them to
|
||||||
resolve the dependencies of every gem in your Gemfile(5).
|
resolve the dependencies of every gem in your Gemfile(5).
|
||||||
|
|
||||||
This is so that installing a different set of groups on another machine
|
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
|
(such as a production server) will not change the gems and versions
|
||||||
that you have already developed and tested against.
|
that you have already developed and tested against.
|
||||||
|
|
||||||
Bundler offers a rock-solid guarantee that the third-party code you are
|
Bundler 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 development and testing is also the third-party code you are
|
||||||
running in production. You can choose to exclude some of that code in
|
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 environments, but you will never be caught flat-footed by
|
||||||
different versions of third-party code being used in different
|
different versions of third-party code being used in different
|
||||||
environments.
|
environments.
|
||||||
|
|
||||||
For a simple illustration, consider the following Gemfile(5):
|
For a simple illustration, consider the following Gemfile(5):
|
||||||
|
|
@ -261,63 +261,63 @@ INSTALLING GROUPS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
In this case, sinatra depends on any version of Rack (>= 1.0), while
|
In this case, sinatra depends on any version of Rack (>= 1.0), while
|
||||||
rack-perftools-profiler depends on 1.x (~> 1.0).
|
rack-perftools-profiler depends on 1.x (~> 1.0).
|
||||||
|
|
||||||
When you run bundle install --without production in development, we
|
When you run bundle install --without production in development, we
|
||||||
look at the dependencies of rack-perftools-profiler as well. That way,
|
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
|
you do not spend all your time developing against Rack 2.0, using new
|
||||||
APIs unavailable in Rack 1.x, only to have Bundler switch to Rack 1.2
|
APIs unavailable in Rack 1.x, only to have Bundler switch to Rack 1.2
|
||||||
when the production group is used.
|
when the production group is used.
|
||||||
|
|
||||||
This should not cause any problems in practice, because we do not
|
This should not cause any problems in practice, because we do not
|
||||||
attempt to install the gems in the excluded groups, and only evaluate
|
attempt to install the gems in the excluded groups, and only evaluate
|
||||||
as part of the dependency resolution process.
|
as part of the dependency resolution process.
|
||||||
|
|
||||||
This also means that you cannot include different versions of the same
|
This also means that you cannot include different versions of the same
|
||||||
gem in different groups, because doing so would result in different
|
gem in different groups, because doing so would result in different
|
||||||
sets of dependencies used in development and production. Because of the
|
sets of dependencies used in development and production. Because of the
|
||||||
vagaries of the dependency resolution process, this usually affects
|
vagaries of the dependency resolution process, this usually affects
|
||||||
more than the gems you list in your Gemfile(5), and can (surprisingly)
|
more than the gems you list in your Gemfile(5), and can (surprisingly)
|
||||||
radically change the gems you are using.
|
radically change the gems you are using.
|
||||||
|
|
||||||
THE GEMFILE.LOCK
|
THE GEMFILE.LOCK
|
||||||
When you run bundle install, Bundler will persist the full names and
|
When you run bundle install, Bundler will persist the full names and
|
||||||
versions of all gems that you used (including dependencies of the gems
|
versions of all gems that you used (including dependencies of the gems
|
||||||
specified in the Gemfile(5)) into a file called Gemfile.lock.
|
specified in the Gemfile(5)) into a file called Gemfile.lock.
|
||||||
|
|
||||||
Bundler uses this file in all subsequent calls to bundle install, which
|
Bundler uses this file in all subsequent calls to bundle install, which
|
||||||
guarantees that you always use the same exact code, even as your
|
guarantees that you always use the same exact code, even as your
|
||||||
application moves across machines.
|
application moves across machines.
|
||||||
|
|
||||||
Because of the way dependency resolution works, even a seemingly small
|
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
|
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
|
gem in your Gemfile(5)) can result in radically different gems being
|
||||||
needed to satisfy all dependencies.
|
needed to satisfy all dependencies.
|
||||||
|
|
||||||
As a result, you SHOULD check your Gemfile.lock into version control,
|
As a result, you SHOULD check your Gemfile.lock into version control,
|
||||||
in both applications and gems. If you do not, every machine that checks
|
in both applications and gems. If you do not, every machine that checks
|
||||||
out your repository (including your production server) will resolve all
|
out your repository (including your production server) will resolve all
|
||||||
dependencies again, which will result in different versions of
|
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
|
third-party code being used if any of the gems in the Gemfile(5) or any
|
||||||
of their dependencies have been updated.
|
of their dependencies have been updated.
|
||||||
|
|
||||||
When Bundler first shipped, the Gemfile.lock was included in the
|
When Bundler first shipped, the Gemfile.lock was included in the
|
||||||
.gitignore file included with generated gems. Over time, however, it
|
.gitignore file included with generated gems. Over time, however, it
|
||||||
became clear that this practice forces the pain of broken dependencies
|
became clear that this practice forces the pain of broken dependencies
|
||||||
onto new contributors, while leaving existing contributors potentially
|
onto new contributors, while leaving existing contributors potentially
|
||||||
unaware of the problem. Since bundle install is usually the first step
|
unaware of the problem. Since bundle install is usually the first step
|
||||||
towards a contribution, the pain of broken dependencies would
|
towards a contribution, the pain of broken dependencies would
|
||||||
discourage new contributors from contributing. As a result, we have
|
discourage new contributors from contributing. As a result, we have
|
||||||
revised our guidance for gem authors to now recommend checking in the
|
revised our guidance for gem authors to now recommend checking in the
|
||||||
lock for gems.
|
lock for gems.
|
||||||
|
|
||||||
CONSERVATIVE UPDATING
|
CONSERVATIVE UPDATING
|
||||||
When you make a change to the Gemfile(5) 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.
|
Bundler will update only the gems that you modified.
|
||||||
|
|
||||||
In other words, if a gem that you did not modify worked before you
|
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
|
called bundle install, it will continue to use the exact same versions
|
||||||
of all dependencies as it used before the update.
|
of all dependencies as it used before the update.
|
||||||
|
|
||||||
Let's take a look at an example. Here's your original Gemfile(5):
|
Let's take a look at an example. Here's your original Gemfile(5):
|
||||||
|
|
@ -331,13 +331,13 @@ CONSERVATIVE UPDATING
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
In this case, both actionpack and activemerchant depend on
|
In this case, both actionpack and activemerchant depend on
|
||||||
activesupport. The actionpack gem depends on activesupport 2.3.8 and
|
activesupport. The actionpack gem depends on activesupport 2.3.8 and
|
||||||
rack ~> 1.1.0, while the activemerchant gem depends on activesupport >=
|
rack ~> 1.1.0, while the activemerchant gem depends on activesupport >=
|
||||||
2.3.2, braintree >= 2.0.0, and builder >= 2.0.0.
|
2.3.2, braintree >= 2.0.0, and builder >= 2.0.0.
|
||||||
|
|
||||||
When the dependencies are first resolved, Bundler will select
|
When the dependencies are first resolved, Bundler will select
|
||||||
activesupport 2.3.8, which satisfies the requirements of both gems in
|
activesupport 2.3.8, which satisfies the requirements of both gems in
|
||||||
your Gemfile(5).
|
your Gemfile(5).
|
||||||
|
|
||||||
Next, you modify your Gemfile(5) to:
|
Next, you modify your Gemfile(5) to:
|
||||||
|
|
@ -351,44 +351,44 @@ CONSERVATIVE UPDATING
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The actionpack 3.0.0.rc gem has a number of new dependencies, and
|
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
|
updates the activesupport dependency to = 3.0.0.rc and the rack
|
||||||
dependency to ~> 1.2.1.
|
dependency to ~> 1.2.1.
|
||||||
|
|
||||||
When you run bundle install, Bundler notices that you changed the
|
When you run bundle install, Bundler notices that you changed the
|
||||||
actionpack gem, but not the activemerchant gem. It evaluates the gems
|
actionpack gem, but not the activemerchant gem. It evaluates the gems
|
||||||
currently being used to satisfy its requirements:
|
currently being used to satisfy its requirements:
|
||||||
|
|
||||||
activesupport 2.3.8
|
activesupport 2.3.8
|
||||||
also used to satisfy a dependency in activemerchant, which is
|
also used to satisfy a dependency in activemerchant, which is
|
||||||
not being updated
|
not being updated
|
||||||
|
|
||||||
rack ~> 1.1.0
|
rack ~> 1.1.0
|
||||||
not currently being used to satisfy another dependency
|
not currently being used to satisfy another dependency
|
||||||
|
|
||||||
Because you did not explicitly ask to update activemerchant, you would
|
Because you did not explicitly ask to update activemerchant, you would
|
||||||
not expect it to suddenly stop working after updating actionpack.
|
not expect it to suddenly stop working after updating actionpack.
|
||||||
However, satisfying the new activesupport 3.0.0.rc dependency of
|
However, satisfying the new activesupport 3.0.0.rc dependency of
|
||||||
actionpack requires updating one of its dependencies.
|
actionpack requires updating one of its dependencies.
|
||||||
|
|
||||||
Even though activemerchant declares a very loose dependency that
|
Even though activemerchant declares a very loose dependency that
|
||||||
theoretically matches activesupport 3.0.0.rc, Bundler treats gems in
|
theoretically matches activesupport 3.0.0.rc, Bundler treats gems in
|
||||||
your Gemfile(5) that have not changed as an atomic unit together with
|
your Gemfile(5) that have not changed as an atomic unit together with
|
||||||
their dependencies. In this case, the activemerchant dependency is
|
their dependencies. In this case, the activemerchant dependency is
|
||||||
treated as activemerchant 1.7.1 + activesupport 2.3.8, so bundle
|
treated as activemerchant 1.7.1 + activesupport 2.3.8, so bundle
|
||||||
install will report that it cannot update actionpack.
|
install will report that it cannot update actionpack.
|
||||||
|
|
||||||
To explicitly update actionpack, including its dependencies which other
|
To explicitly update actionpack, including its dependencies which other
|
||||||
gems in the Gemfile(5) still depend on, run bundle update actionpack
|
gems in the Gemfile(5) still depend on, run bundle update actionpack
|
||||||
(see bundle update(1)).
|
(see bundle update(1)).
|
||||||
|
|
||||||
Summary: In general, after making a change to the Gemfile(5) , 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
|
should first try to run bundle install, which will guarantee that no
|
||||||
other gem in the Gemfile(5) is impacted by the change. If that does not
|
other gem in the Gemfile(5) is impacted by the change. If that does not
|
||||||
work, run bundle update(1) bundle-update.1.html.
|
work, run bundle update(1) bundle-update.1.html.
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
o Gem install docs
|
o Gem install docs
|
||||||
http://guides.rubygems.org/rubygems-basics/#installing-gems
|
http://guides.rubygems.org/rubygems-basics/#installing-gems
|
||||||
|
|
||||||
o Rubygems signing docs http://guides.rubygems.org/security/
|
o Rubygems signing docs http://guides.rubygems.org/security/
|
||||||
|
|
|
||||||
|
|
@ -16,16 +16,16 @@ DESCRIPTION
|
||||||
OPTIONS
|
OPTIONS
|
||||||
--update=<*gems>
|
--update=<*gems>
|
||||||
Ignores the existing lockfile. Resolve then updates lockfile.
|
Ignores the existing lockfile. Resolve then updates lockfile.
|
||||||
Taking a list of gems or updating all gems if no list is given.
|
Taking a list of gems or updating all gems if no list is given.
|
||||||
|
|
||||||
--local
|
--local
|
||||||
Do not attempt to connect to rubygems.org. Instead, Bundler will
|
Do not attempt to connect to rubygems.org. Instead, Bundler will
|
||||||
use the gems already present in Rubygems' cache or in
|
use the gems already present in Rubygems' cache or in
|
||||||
vendor/cache. Note that if a appropriate platform-specific gem
|
vendor/cache. Note that if a appropriate platform-specific gem
|
||||||
exists on rubygems.org it will not be found.
|
exists on rubygems.org it will not be found.
|
||||||
|
|
||||||
--print
|
--print
|
||||||
Prints the lockfile to STDOUT instead of writing to the file
|
Prints the lockfile to STDOUT instead of writing to the file
|
||||||
system.
|
system.
|
||||||
|
|
||||||
--lockfile=<path>
|
--lockfile=<path>
|
||||||
|
|
@ -35,7 +35,7 @@ OPTIONS
|
||||||
Fall back to using the single-file index of all gems.
|
Fall back to using the single-file index of all gems.
|
||||||
|
|
||||||
--add-platform
|
--add-platform
|
||||||
Add a new platform to the lockfile, re-resolving for the
|
Add a new platform to the lockfile, re-resolving for the
|
||||||
addition of that platform.
|
addition of that platform.
|
||||||
|
|
||||||
--remove-platform
|
--remove-platform
|
||||||
|
|
@ -51,7 +51,7 @@ OPTIONS
|
||||||
If updating, prefer updating to next major version (default).
|
If updating, prefer updating to next major version (default).
|
||||||
|
|
||||||
--strict
|
--strict
|
||||||
If updating, do not allow any gem to be updated past latest
|
If updating, do not allow any gem to be updated past latest
|
||||||
--patch | --minor | --major.
|
--patch | --minor | --major.
|
||||||
|
|
||||||
--conservative
|
--conservative
|
||||||
|
|
@ -59,28 +59,28 @@ OPTIONS
|
||||||
do not allow shared dependencies to be updated.
|
do not allow shared dependencies to be updated.
|
||||||
|
|
||||||
UPDATING ALL GEMS
|
UPDATING ALL GEMS
|
||||||
If you run bundle lock with --update option without list of gems,
|
If you run bundle lock with --update option without list of gems,
|
||||||
bundler will ignore any previously installed gems and resolve all
|
bundler will ignore any previously installed gems and resolve all
|
||||||
dependencies again based on the latest versions of all gems available
|
dependencies again based on the latest versions of all gems available
|
||||||
in the sources.
|
in the sources.
|
||||||
|
|
||||||
UPDATING A LIST OF GEMS
|
UPDATING A LIST OF GEMS
|
||||||
Sometimes, you want to update a single gem in the Gemfile(5), and leave
|
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
|
the rest of the gems that you specified locked to the versions in the
|
||||||
Gemfile.lock.
|
Gemfile.lock.
|
||||||
|
|
||||||
For instance, you only want to update nokogiri, run bundle lock
|
For instance, you only want to update nokogiri, run bundle lock
|
||||||
--update nokogiri.
|
--update nokogiri.
|
||||||
|
|
||||||
Bundler will update nokogiri and any of its dependencies, but leave the
|
Bundler will update nokogiri and any of its dependencies, but leave the
|
||||||
rest of the gems that you specified locked to the versions in the
|
rest of the gems that you specified locked to the versions in the
|
||||||
Gemfile.lock.
|
Gemfile.lock.
|
||||||
|
|
||||||
SUPPORTING OTHER PLATFORMS
|
SUPPORTING OTHER PLATFORMS
|
||||||
If you want your bundle to support platforms other than the one you're
|
If you want your bundle to support platforms other than the one you're
|
||||||
running locally, you can run bundle lock --add-platform PLATFORM to add
|
running locally, you can run bundle lock --add-platform PLATFORM to add
|
||||||
PLATFORM to the lockfile, force bundler to re-resolve and consider the
|
PLATFORM to the lockfile, force bundler to re-resolve and consider the
|
||||||
new platform when picking gems, all without needing to have a machine
|
new platform when picking gems, all without needing to have a machine
|
||||||
that matches PLATFORM handy to install those platform-specific gems on.
|
that matches PLATFORM handy to install those platform-specific gems on.
|
||||||
|
|
||||||
For a full explanation of gem platforms, see gem help platform.
|
For a full explanation of gem platforms, see gem help platform.
|
||||||
|
|
|
||||||
|
|
@ -16,33 +16,33 @@ DESCRIPTION
|
||||||
general, you should use bundle install(1) bundle-install.1.html to
|
general, you should use bundle install(1) bundle-install.1.html to
|
||||||
install the same exact gems and versions across machines.
|
install the same exact gems and versions across machines.
|
||||||
|
|
||||||
You would use bundle update to explicitly update the version of a gem.
|
You would use bundle update to explicitly update the version of a gem.
|
||||||
|
|
||||||
OPTIONS
|
OPTIONS
|
||||||
--all Update all gems specified in Gemfile.
|
--all Update all gems specified in Gemfile.
|
||||||
|
|
||||||
--group=<name>, -g=[<name>]
|
--group=<name>, -g=[<name>]
|
||||||
Only update the gems in the specified group. For instance, you
|
Only update the gems in the specified group. For instance, you
|
||||||
can update all gems in the development group with bundle update
|
can update all gems in the development group with bundle update
|
||||||
--group development. You can also call bundle update rails
|
--group development. You can also call bundle update rails
|
||||||
--group test to update the rails gem and all gems in the test
|
--group test to update the rails gem and all gems in the test
|
||||||
group, for example.
|
group, for example.
|
||||||
|
|
||||||
--source=<name>
|
--source=<name>
|
||||||
The name of a :git or :path source used in the Gemfile(5). For
|
The name of a :git or :path source used in the Gemfile(5). For
|
||||||
instance, with a :git source of
|
instance, with a :git source of
|
||||||
http://github.com/rails/rails.git, you would call bundle update
|
http://github.com/rails/rails.git, you would call bundle update
|
||||||
--source rails
|
--source rails
|
||||||
|
|
||||||
--local
|
--local
|
||||||
Do not attempt to fetch gems remotely and use the gem cache
|
Do not attempt to fetch gems remotely and use the gem cache
|
||||||
instead.
|
instead.
|
||||||
|
|
||||||
--ruby Update the locked version of Ruby to the current version of
|
--ruby Update the locked version of Ruby to the current version of
|
||||||
Ruby.
|
Ruby.
|
||||||
|
|
||||||
--bundler
|
--bundler
|
||||||
Update the locked version of bundler to the invoked bundler
|
Update the locked version of bundler to the invoked bundler
|
||||||
version.
|
version.
|
||||||
|
|
||||||
--full-index
|
--full-index
|
||||||
|
|
@ -328,22 +328,22 @@ PATCH LEVEL EXAMPLES
|
||||||
the dependency from foo 1.4.5 required it.
|
the dependency from foo 1.4.5 required it.
|
||||||
|
|
||||||
In case 2, only foo is requested to be unlocked, but bar is also
|
In case 2, only foo is requested to be unlocked, but bar is also
|
||||||
allowed to move because it's not a declared dependency in the Gemfile.
|
allowed to move because it's not a declared dependency in the Gemfile.
|
||||||
|
|
||||||
In case 3, bar goes up a whole major release, because a minor increase
|
In case 3, bar goes up a whole major release, because a minor increase
|
||||||
is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
|
is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
|
||||||
of bar.
|
of bar.
|
||||||
|
|
||||||
In case 4, foo is preferred up to a minor version, but 1.5.1 won't work
|
In case 4, foo is preferred up to a minor version, but 1.5.1 won't work
|
||||||
because the --strict flag removes bar 3.0.0 from consideration since
|
because the --strict flag removes bar 3.0.0 from consideration since
|
||||||
it's a major increment.
|
it's a major increment.
|
||||||
|
|
||||||
In case 5, both foo and bar have any minor or major increments removed
|
In case 5, both foo and bar have any minor or major increments removed
|
||||||
from consideration because of the --strict flag, so the most they can
|
from consideration because of the --strict flag, so the most they can
|
||||||
move is up to 1.4.4 and 2.0.4.
|
move is up to 1.4.4 and 2.0.4.
|
||||||
|
|
||||||
RECOMMENDED WORKFLOW
|
RECOMMENDED WORKFLOW
|
||||||
In general, when working with an application managed with bundler, you
|
In general, when working with an application managed with bundler, you
|
||||||
should use the following workflow:
|
should use the following workflow:
|
||||||
|
|
||||||
o After you create your Gemfile(5) for the first time, run
|
o After you create your Gemfile(5) for the first time, run
|
||||||
|
|
@ -354,7 +354,7 @@ RECOMMENDED WORKFLOW
|
||||||
|
|
||||||
$ git add Gemfile.lock
|
$ git add Gemfile.lock
|
||||||
|
|
||||||
o When checking out this repository on another development machine,
|
o When checking out this repository on another development machine,
|
||||||
run
|
run
|
||||||
|
|
||||||
$ bundle install
|
$ bundle install
|
||||||
|
|
@ -363,7 +363,7 @@ RECOMMENDED WORKFLOW
|
||||||
|
|
||||||
$ bundle install --deployment
|
$ bundle install --deployment
|
||||||
|
|
||||||
o After changing the Gemfile(5) to reflect a new or update
|
o After changing the Gemfile(5) to reflect a new or update
|
||||||
dependency, run
|
dependency, run
|
||||||
|
|
||||||
$ bundle install
|
$ bundle install
|
||||||
|
|
@ -372,13 +372,13 @@ RECOMMENDED WORKFLOW
|
||||||
|
|
||||||
$ git add Gemfile.lock
|
$ git add Gemfile.lock
|
||||||
|
|
||||||
o If bundle install(1) bundle-install.1.html reports a conflict,
|
o If bundle install(1) bundle-install.1.html reports a conflict,
|
||||||
manually update the specific gems that you changed in the
|
manually update the specific gems that you changed in the
|
||||||
Gemfile(5)
|
Gemfile(5)
|
||||||
|
|
||||||
$ bundle update rails thin
|
$ bundle update rails thin
|
||||||
|
|
||||||
o If you want to update all the gems to the latest possible versions
|
o If you want to update all the gems to the latest possible versions
|
||||||
that still match the gems listed in the Gemfile(5), run
|
that still match the gems listed in the Gemfile(5), run
|
||||||
|
|
||||||
$ bundle update --all
|
$ bundle update --all
|
||||||
|
|
|
||||||
|
|
@ -36,7 +36,7 @@ PRIMARY COMMANDS
|
||||||
Update dependencies to their latest versions
|
Update dependencies to their latest versions
|
||||||
|
|
||||||
bundle package(1) bundle-package.1.html
|
bundle package(1) bundle-package.1.html
|
||||||
Package the .gem files required by your application into the
|
Package the .gem files required by your application into the
|
||||||
vendor/cache directory
|
vendor/cache directory
|
||||||
|
|
||||||
bundle exec(1) bundle-exec.1.html
|
bundle exec(1) bundle-exec.1.html
|
||||||
|
|
@ -56,7 +56,7 @@ UTILITIES
|
||||||
Generate binstubs for executables in a gem
|
Generate binstubs for executables in a gem
|
||||||
|
|
||||||
bundle check(1) bundle-check.1.html
|
bundle check(1) bundle-check.1.html
|
||||||
Determine whether the requirements for your application are
|
Determine whether the requirements for your application are
|
||||||
installed and available to Bundler
|
installed and available to Bundler
|
||||||
|
|
||||||
bundle show(1) bundle-show.1.html
|
bundle show(1) bundle-show.1.html
|
||||||
|
|
@ -96,9 +96,9 @@ UTILITIES
|
||||||
Removes gems from the Gemfile
|
Removes gems from the Gemfile
|
||||||
|
|
||||||
PLUGINS
|
PLUGINS
|
||||||
When running a command that isn't listed in PRIMARY COMMANDS or
|
When running a command that isn't listed in PRIMARY COMMANDS or
|
||||||
UTILITIES, Bundler will try to find an executable on your path named
|
UTILITIES, Bundler will try to find an executable on your path named
|
||||||
bundler-<command> and execute it, passing down any extra arguments to
|
bundler-<command> and execute it, passing down any extra arguments to
|
||||||
it.
|
it.
|
||||||
|
|
||||||
OBSOLETE
|
OBSOLETE
|
||||||
|
|
|
||||||
|
|
@ -99,13 +99,13 @@ RUBY
|
||||||
exist. Some of the more well-known implementations include Rubinius
|
exist. Some of the more well-known implementations include Rubinius
|
||||||
https://rubinius.com/, and JRuby http://jruby.org/. Rubinius is an
|
https://rubinius.com/, and JRuby http://jruby.org/. Rubinius is an
|
||||||
alternative implementation of Ruby written in Ruby. JRuby is an
|
alternative implementation of Ruby written in Ruby. JRuby is an
|
||||||
implementation of Ruby on the JVM, short for Java Virtual Machine.
|
implementation of Ruby on the JVM, short for Java Virtual Machine.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
ENGINE VERSION
|
ENGINE VERSION
|
||||||
Each application may specify a Ruby engine version. If an engine
|
Each application may specify a Ruby engine version. If an engine
|
||||||
version is specified, an engine must also be specified. If the engine
|
version is specified, an engine must also be specified. If the engine
|
||||||
is "ruby" the engine version specified must match the Ruby version.
|
is "ruby" the engine version specified must match the Ruby version.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -124,7 +124,7 @@ RUBY
|
||||||
|
|
||||||
|
|
||||||
GEMS
|
GEMS
|
||||||
Specify gem requirements using the gem method, with the following
|
Specify gem requirements using the gem method, with the following
|
||||||
arguments. All parameters are OPTIONAL unless otherwise specified.
|
arguments. All parameters are OPTIONAL unless otherwise specified.
|
||||||
|
|
||||||
NAME (required)
|
NAME (required)
|
||||||
|
|
@ -147,9 +147,9 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
REQUIRE AS
|
REQUIRE AS
|
||||||
Each gem MAY specify files that should be used when autorequiring via
|
Each gem MAY specify files that should be used when autorequiring via
|
||||||
Bundler.require. You may pass an array with multiple files or true if
|
Bundler.require. You may pass an array with multiple files or true if
|
||||||
file you want required has same name as gem or false to prevent any
|
file you want required has same name as gem or false to prevent any
|
||||||
file from being autorequired.
|
file from being autorequired.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -160,7 +160,7 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The argument defaults to the name of the gem. For example, these are
|
The argument defaults to the name of the gem. For example, these are
|
||||||
identical:
|
identical:
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -172,8 +172,8 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
GROUPS
|
GROUPS
|
||||||
Each gem MAY specify membership in one or more groups. Any gem that
|
Each gem MAY specify membership in one or more groups. Any gem that
|
||||||
does not specify membership in any group is placed in the default
|
does not specify membership in any group is placed in the default
|
||||||
group.
|
group.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -183,7 +183,7 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The Bundler runtime allows its two main methods, Bundler.setup and
|
The Bundler runtime allows its two main methods, Bundler.setup and
|
||||||
Bundler.require, to limit their impact to particular groups.
|
Bundler.require, to limit their impact to particular groups.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -203,10 +203,10 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The Bundler CLI allows you to specify a list of groups whose gems
|
The Bundler CLI allows you to specify a list of groups whose gems
|
||||||
bundle install should not install with the without configuration.
|
bundle install should not install with the without configuration.
|
||||||
|
|
||||||
To specify multiple groups to ignore, specify a list of groups
|
To specify multiple groups to ignore, specify a list of groups
|
||||||
separated by spaces.
|
separated by spaces.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -216,20 +216,20 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Also, calling Bundler.setup with no parameters, or calling require
|
Also, calling Bundler.setup with no parameters, or calling require
|
||||||
"bundler/setup" will setup all groups except for the ones you excluded
|
"bundler/setup" will setup all groups except for the ones you excluded
|
||||||
via --without (since they are not available).
|
via --without (since they are not available).
|
||||||
|
|
||||||
Note that on bundle install, bundler downloads and evaluates all gems,
|
Note that on bundle install, bundler downloads and evaluates all gems,
|
||||||
in order to create a single canonical list of all of the required gems
|
in order to create a single canonical list of all of the required gems
|
||||||
and their dependencies. This means that you cannot list different
|
and their dependencies. This means that you cannot list different
|
||||||
versions of the same gems in different groups. For more details, see
|
versions of the same gems in different groups. For more details, see
|
||||||
Understanding Bundler https://bundler.io/rationale.html.
|
Understanding Bundler https://bundler.io/rationale.html.
|
||||||
|
|
||||||
PLATFORMS
|
PLATFORMS
|
||||||
If a gem should only be used in a particular platform or set of
|
If a gem should only be used in a particular platform or set of
|
||||||
platforms, you can specify them. Platforms are essentially identical to
|
platforms, you can specify them. Platforms are essentially identical to
|
||||||
groups, except that you do not need to use the --without install-time
|
groups, except that you do not need to use the --without install-time
|
||||||
flag to exclude groups of gems for other platforms.
|
flag to exclude groups of gems for other platforms.
|
||||||
|
|
||||||
There are a number of Gemfile platforms:
|
There are a number of Gemfile platforms:
|
||||||
|
|
@ -252,11 +252,11 @@ GEMS
|
||||||
|
|
||||||
mswin Windows
|
mswin Windows
|
||||||
|
|
||||||
You can restrict further by platform and version for all platforms
|
You can restrict further by platform and version for all platforms
|
||||||
except for rbx, jruby, truffleruby and mswin.
|
except for rbx, jruby, truffleruby and mswin.
|
||||||
|
|
||||||
To specify a version in addition to a platform, append the version
|
To specify a version in addition to a platform, append the version
|
||||||
number without the delimiter to the platform. For example, to specify
|
number without the delimiter to the platform. For example, to specify
|
||||||
that a gem should only be used on platforms with Ruby 2.3, use:
|
that a gem should only be used on platforms with Ruby 2.3, use:
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -286,12 +286,12 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
All operations involving groups (bundle install bundle-install.1.html,
|
All operations involving groups (bundle install bundle-install.1.html,
|
||||||
Bundler.setup, Bundler.require) behave exactly the same as if any
|
Bundler.setup, Bundler.require) behave exactly the same as if any
|
||||||
groups not matching the current platform were explicitly excluded.
|
groups not matching the current platform were explicitly excluded.
|
||||||
|
|
||||||
SOURCE
|
SOURCE
|
||||||
You can select an alternate Rubygems repository for a gem using the
|
You can select an alternate Rubygems repository for a gem using the
|
||||||
':source' option.
|
':source' option.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -300,22 +300,22 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
This forces the gem to be loaded from this source and ignores any
|
This forces the gem to be loaded from this source and ignores any
|
||||||
global sources declared at the top level of the file. If the gem does
|
global sources declared at the top level of the file. If the gem does
|
||||||
not exist in this source, it will not be installed.
|
not exist in this source, it will not be installed.
|
||||||
|
|
||||||
Bundler will search for child dependencies of this gem by first looking
|
Bundler will search for child dependencies of this gem by first looking
|
||||||
in the source selected for the parent, but if they are not found there,
|
in the source selected for the parent, but if they are not found there,
|
||||||
it will fall back on global sources using the ordering described in
|
it will fall back on global sources using the ordering described in
|
||||||
SOURCE PRIORITY.
|
SOURCE PRIORITY.
|
||||||
|
|
||||||
Selecting a specific source repository this way also suppresses the
|
Selecting a specific source repository this way also suppresses the
|
||||||
ambiguous gem warning described above in GLOBAL SOURCES (#source).
|
ambiguous gem warning described above in GLOBAL SOURCES (#source).
|
||||||
|
|
||||||
Using the :source option for an individual gem will also make that
|
Using the :source option for an individual gem will also make that
|
||||||
source available as a possible global source for any other gems which
|
source available as a possible global source for any other gems which
|
||||||
do not specify explicit sources. Thus, when adding gems with explicit
|
do not specify explicit sources. Thus, when adding gems with explicit
|
||||||
sources, it is recommended that you also ensure all other gems in the
|
sources, it is recommended that you also ensure all other gems in the
|
||||||
Gemfile are using explicit sources.
|
Gemfile are using explicit sources.
|
||||||
|
|
||||||
GIT
|
GIT
|
||||||
|
|
@ -333,27 +333,27 @@ GEMS
|
||||||
If using SSH, the user that you use to run bundle install MUST have the
|
If using SSH, the user that you use to run bundle install MUST have the
|
||||||
appropriate keys available in their $HOME/.ssh.
|
appropriate keys available in their $HOME/.ssh.
|
||||||
|
|
||||||
NOTE: http:// and git:// URLs should be avoided if at all possible.
|
NOTE: http:// and git:// URLs should be avoided if at all possible.
|
||||||
These protocols are unauthenticated, so a man-in-the-middle attacker
|
These protocols are unauthenticated, so a man-in-the-middle attacker
|
||||||
can deliver malicious code and compromise your system. HTTPS and SSH
|
can deliver malicious code and compromise your system. HTTPS and SSH
|
||||||
are strongly preferred.
|
are strongly preferred.
|
||||||
|
|
||||||
The group, platforms, and require options are available and behave
|
The group, platforms, and require options are available and behave
|
||||||
exactly the same as they would for a normal gem.
|
exactly the same as they would for a normal gem.
|
||||||
|
|
||||||
A git repository SHOULD have at least one file, at the root of the
|
A git repository SHOULD have at least one file, at the root of the
|
||||||
directory containing the gem, with the extension .gemspec. This file
|
directory containing the gem, with the extension .gemspec. This file
|
||||||
MUST contain a valid gem specification, as expected by the gem build
|
MUST contain a valid gem specification, as expected by the gem build
|
||||||
command.
|
command.
|
||||||
|
|
||||||
If a git repository does not have a .gemspec, bundler will attempt to
|
If a git repository does not have a .gemspec, bundler will attempt to
|
||||||
create one, but it will not contain any dependencies, executables, or C
|
create one, but it will not contain any dependencies, executables, or C
|
||||||
extension compilation instructions. As a result, it may fail to
|
extension compilation instructions. As a result, it may fail to
|
||||||
properly integrate into your application.
|
properly integrate into your application.
|
||||||
|
|
||||||
If a git repository does have a .gemspec for the gem you attached it
|
If a git repository does have a .gemspec for the gem you attached it
|
||||||
to, a version specifier, if provided, means that the git repository is
|
to, a version specifier, if provided, means that the git repository is
|
||||||
only valid if the .gemspec specifies a version matching the version
|
only valid if the .gemspec specifies a version matching the version
|
||||||
specifier. If not, bundler will print a warning.
|
specifier. If not, bundler will print a warning.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -364,34 +364,34 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
If a git repository does not have a .gemspec for the gem you attached
|
If a git repository does not have a .gemspec for the gem you attached
|
||||||
it to, a version specifier MUST be provided. Bundler will use this
|
it to, a version specifier MUST be provided. Bundler will use this
|
||||||
version in the simple .gemspec it creates.
|
version in the simple .gemspec it creates.
|
||||||
|
|
||||||
Git repositories support a number of additional options.
|
Git repositories support a number of additional options.
|
||||||
|
|
||||||
branch, tag, and ref
|
branch, tag, and ref
|
||||||
You MUST only specify at most one of these options. The default
|
You MUST only specify at most one of these options. The default
|
||||||
is :branch => "master". For example:
|
is :branch => "master". For example:
|
||||||
|
|
||||||
gem "rails", :git => "https://github.com/rails/rails.git",
|
gem "rails", :git => "https://github.com/rails/rails.git",
|
||||||
:branch => "5-0-stable"
|
:branch => "5-0-stable"
|
||||||
|
|
||||||
gem "rails", :git => "https://github.com/rails/rails.git", :tag
|
gem "rails", :git => "https://github.com/rails/rails.git", :tag
|
||||||
=> "v5.0.0"
|
=> "v5.0.0"
|
||||||
|
|
||||||
gem "rails", :git => "https://github.com/rails/rails.git", :ref
|
gem "rails", :git => "https://github.com/rails/rails.git", :ref
|
||||||
=> "4aded"
|
=> "4aded"
|
||||||
|
|
||||||
submodules
|
submodules
|
||||||
For reference, a git submodule
|
For reference, a git submodule
|
||||||
https://git-scm.com/book/en/v2/Git-Tools-Submodules lets you
|
https://git-scm.com/book/en/v2/Git-Tools-Submodules lets you
|
||||||
have another git repository within a subfolder of your
|
have another git repository within a subfolder of your
|
||||||
repository. Specify :submodules => true to cause bundler to
|
repository. Specify :submodules => true to cause bundler to
|
||||||
expand any submodules included in the git repository
|
expand any submodules included in the git repository
|
||||||
|
|
||||||
If a git repository contains multiple .gemspecs, each .gemspec
|
If a git repository contains multiple .gemspecs, each .gemspec
|
||||||
represents a gem located at the same place in the file system as the
|
represents a gem located at the same place in the file system as the
|
||||||
.gemspec.
|
.gemspec.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -406,16 +406,16 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
To install a gem located in a git repository, bundler changes to the
|
To install a gem located in a git repository, bundler changes to the
|
||||||
directory containing the gemspec, runs gem build name.gemspec and then
|
directory containing the gemspec, runs gem build name.gemspec and then
|
||||||
installs the resulting gem. The gem build command, which comes standard
|
installs the resulting gem. The gem build command, which comes standard
|
||||||
with Rubygems, evaluates the .gemspec in the context of the directory
|
with Rubygems, evaluates the .gemspec in the context of the directory
|
||||||
in which it is located.
|
in which it is located.
|
||||||
|
|
||||||
GIT SOURCE
|
GIT SOURCE
|
||||||
A custom git source can be defined via the git_source method. Provide
|
A custom git source can be defined via the git_source method. Provide
|
||||||
the source's name as an argument, and a block which receives a single
|
the source's name as an argument, and a block which receives a single
|
||||||
argument and interpolates it into a string to return the full repo
|
argument and interpolates it into a string to return the full repo
|
||||||
address:
|
address:
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -434,14 +434,14 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
GITHUB
|
GITHUB
|
||||||
NOTE: This shorthand should be avoided until Bundler 2.0, since it
|
NOTE: This shorthand should be avoided until Bundler 2.0, since it
|
||||||
currently expands to an insecure git:// URL. This allows a
|
currently expands to an insecure git:// URL. This allows a
|
||||||
man-in-the-middle attacker to compromise your system.
|
man-in-the-middle attacker to compromise your system.
|
||||||
|
|
||||||
If the git repository you want to use is hosted on GitHub and is
|
If the git repository you want to use is hosted on GitHub and is
|
||||||
public, you can use the :github shorthand to specify the github
|
public, you can use the :github shorthand to specify the github
|
||||||
username and repository name (without the trailing ".git"), separated
|
username and repository name (without the trailing ".git"), separated
|
||||||
by a slash. If both the username and repository name are the same, you
|
by a slash. If both the username and repository name are the same, you
|
||||||
can omit one.
|
can omit one.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -464,7 +464,7 @@ GEMS
|
||||||
|
|
||||||
GIST
|
GIST
|
||||||
If the git repository you want to use is hosted as a Github Gist and is
|
If the git repository you want to use is hosted as a Github Gist and is
|
||||||
public, you can use the :gist shorthand to specify the gist identifier
|
public, you can use the :gist shorthand to specify the gist identifier
|
||||||
(without the trailing ".git").
|
(without the trailing ".git").
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -481,14 +481,14 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Since the gist method is a specialization of git_source, it accepts a
|
Since the gist method is a specialization of git_source, it accepts a
|
||||||
:branch named argument.
|
:branch named argument.
|
||||||
|
|
||||||
BITBUCKET
|
BITBUCKET
|
||||||
If the git repository you want to use is hosted on Bitbucket and is
|
If the git repository you want to use is hosted on Bitbucket and is
|
||||||
public, you can use the :bitbucket shorthand to specify the bitbucket
|
public, you can use the :bitbucket shorthand to specify the bitbucket
|
||||||
username and repository name (without the trailing ".git"), separated
|
username and repository name (without the trailing ".git"), separated
|
||||||
by a slash. If both the username and repository name are the same, you
|
by a slash. If both the username and repository name are the same, you
|
||||||
can omit one.
|
can omit one.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -506,19 +506,19 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Since the bitbucket method is a specialization of git_source, it
|
Since the bitbucket method is a specialization of git_source, it
|
||||||
accepts a :branch named argument.
|
accepts a :branch named argument.
|
||||||
|
|
||||||
PATH
|
PATH
|
||||||
You can specify that a gem is located in a particular location on the
|
You can specify that a gem is located in a particular location on the
|
||||||
file system. Relative paths are resolved relative to the directory
|
file system. Relative paths are resolved relative to the directory
|
||||||
containing the Gemfile.
|
containing the Gemfile.
|
||||||
|
|
||||||
Similar to the semantics of the :git option, the :path option requires
|
Similar to the semantics of the :git option, the :path option requires
|
||||||
that the directory in question either contains a .gemspec for the gem,
|
that the directory in question either contains a .gemspec for the gem,
|
||||||
or that you specify an explicit version that bundler should use.
|
or that you specify an explicit version that bundler should use.
|
||||||
|
|
||||||
Unlike :git, bundler does not compile C extensions for gems specified
|
Unlike :git, bundler does not compile C extensions for gems specified
|
||||||
as paths.
|
as paths.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -527,9 +527,9 @@ GEMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
If you would like to use multiple local gems directly from the
|
If you would like to use multiple local gems directly from the
|
||||||
filesystem, you can set a global path option to the path containing the
|
filesystem, you can set a global path option to the path containing the
|
||||||
gem's files. This will automatically load gemspec files from
|
gem's files. This will automatically load gemspec files from
|
||||||
subdirectories.
|
subdirectories.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -569,24 +569,24 @@ BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
In the case of the group block form the :optional option can be given
|
In the case of the group block form the :optional option can be given
|
||||||
to prevent a group from being installed unless listed in the --with
|
to prevent a group from being installed unless listed in the --with
|
||||||
option given to the bundle install command.
|
option given to the bundle install command.
|
||||||
|
|
||||||
In the case of the git block form, the :ref, :branch, :tag, and
|
In the case of the git block form, the :ref, :branch, :tag, and
|
||||||
:submodules options may be passed to the git method, and all gems in
|
:submodules options may be passed to the git method, and all gems in
|
||||||
the block will inherit those options.
|
the block will inherit those options.
|
||||||
|
|
||||||
The presence of a source block in a Gemfile also makes that source
|
The presence of a source block in a Gemfile also makes that source
|
||||||
available as a possible global source for any other gems which do not
|
available as a possible global source for any other gems which do not
|
||||||
specify explicit sources. Thus, when defining source blocks, it is
|
specify explicit sources. Thus, when defining source blocks, it is
|
||||||
recommended that you also ensure all other gems in the Gemfile are
|
recommended that you also ensure all other gems in the Gemfile are
|
||||||
using explicit sources, either via source blocks or :source directives
|
using explicit sources, either via source blocks or :source directives
|
||||||
on individual gems.
|
on individual gems.
|
||||||
|
|
||||||
INSTALL_IF
|
INSTALL_IF
|
||||||
The install_if method allows gems to be installed based on a proc or
|
The install_if method allows gems to be installed based on a proc or
|
||||||
lambda. This is especially useful for optional gems that can only be
|
lambda. This is especially useful for optional gems that can only be
|
||||||
used if certain software is installed or some other conditions are met.
|
used if certain software is installed or some other conditions are met.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue