diff options
| author | Hiroshi SHIBATA <hsbt@ruby-lang.org> | 2020-12-08 16:36:29 +0900 |
|---|---|---|
| committer | Hiroshi SHIBATA <hsbt@ruby-lang.org> | 2020-12-08 17:30:02 +0900 |
| commit | 473f9d2df0ddd7fdb5cc73fa3ad49b2f19f22b06 (patch) | |
| tree | 6b39312502d32474da0157f5d55620fabd6454ea /man | |
| parent | 4aca77edde91f826aa243e268bf1ef5214530583 (diff) | |
Merge prepare version of Bundler 2.2.0
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/3864
Diffstat (limited to 'man')
50 files changed, 27 insertions, 2773 deletions
diff --git a/man/bundle-add.1 b/man/bundle-add.1 index 486c249719..985d3be8b1 100644 --- a/man/bundle-add.1 +++ b/man/bundle-add.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-ADD" "1" "October 2020" "" "" +.TH "BUNDLE\-ADD" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-add\fR \- Add gem to the Gemfile and run bundle install diff --git a/man/bundle-add.1.ronn b/man/bundle-add.1.ronn deleted file mode 100644 index 26cbe55647..0000000000 --- a/man/bundle-add.1.ronn +++ /dev/null @@ -1,46 +0,0 @@ -bundle-add(1) -- Add gem to the Gemfile and run bundle install -================================================================ - -## SYNOPSIS - -`bundle add` <GEM_NAME> [--group=GROUP] [--version=VERSION] [--source=SOURCE] [--git=GIT] [--branch=BRANCH] [--skip-install] [--strict] [--optimistic] - -## DESCRIPTION -Adds the named gem to the Gemfile and run `bundle install`. `bundle install` can be avoided by using the flag `--skip-install`. - -Example: - -bundle add rails - -bundle add rails --version "< 3.0, > 1.1" - -bundle add rails --version "~> 5.0.0" --source "https://gems.example.com" --group "development" - -bundle add rails --skip-install - -bundle add rails --group "development, test" - -## OPTIONS -* `--version`, `-v`: - Specify version requirements(s) for the added gem. - -* `--group`, `-g`: - Specify the group(s) for the added gem. Multiple groups should be separated by commas. - -* `--source`, , `-s`: - Specify the source for the added gem. - -* `--git`: - Specify the git source for the added gem. - -* `--branch`: - Specify the git branch for the added gem. - -* `--skip-install`: - Adds the gem to the Gemfile but does not install it. - -* `--optimistic`: - Adds optimistic declaration of version - -* `--strict`: - Adds strict declaration of version diff --git a/man/bundle-binstubs.1 b/man/bundle-binstubs.1 index 782a464c16..75d6b98c96 100644 --- a/man/bundle-binstubs.1 +++ b/man/bundle-binstubs.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-BINSTUBS" "1" "October 2020" "" "" +.TH "BUNDLE\-BINSTUBS" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-binstubs\fR \- Install the binstubs of the listed gems diff --git a/man/bundle-binstubs.1.ronn b/man/bundle-binstubs.1.ronn deleted file mode 100644 index a96186929f..0000000000 --- a/man/bundle-binstubs.1.ronn +++ /dev/null @@ -1,41 +0,0 @@ -bundle-binstubs(1) -- Install the binstubs of the listed gems -============================================================= - -## SYNOPSIS - -`bundle binstubs` <GEM_NAME> [--force] [--path PATH] [--standalone] - -## DESCRIPTION - -Binstubs are scripts that wrap around executables. Bundler creates a -small Ruby file (a binstub) that loads Bundler, runs the command, -and puts it into `bin/`. Binstubs are a shortcut-or alternative- -to always using `bundle exec`. This gives you a file that can be run -directly, and one that will always run the correct gem version -used by the application. - -For example, if you run `bundle binstubs rspec-core`, Bundler will create -the file `bin/rspec`. That file will contain enough code to load Bundler, -tell it to load the bundled gems, and then run rspec. - -This command generates binstubs for executables in `GEM_NAME`. -Binstubs are put into `bin`, or the `--path` directory if one has been set. -Calling binstubs with [GEM [GEM]] will create binstubs for all given gems. - -## OPTIONS - -* `--force`: - Overwrite existing binstubs if they exist. - -* `--path`: - The location to install the specified binstubs to. This defaults to `bin`. - -* `--standalone`: - Makes binstubs that can work without depending on Rubygems or Bundler at - runtime. - -* `--shebang`: - Specify a different shebang executable name than the default (default 'ruby') - -* `--all`: - Create binstubs for all gems in the bundle. diff --git a/man/bundle-cache.1 b/man/bundle-cache.1 index f840893f96..313359d78f 100644 --- a/man/bundle-cache.1 +++ b/man/bundle-cache.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-CACHE" "1" "October 2020" "" "" +.TH "BUNDLE\-CACHE" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-cache\fR \- Package your needed \fB\.gem\fR files into your application diff --git a/man/bundle-cache.1.ronn b/man/bundle-cache.1.ronn deleted file mode 100644 index 383adb2ba3..0000000000 --- a/man/bundle-cache.1.ronn +++ /dev/null @@ -1,72 +0,0 @@ -bundle-cache(1) -- Package your needed `.gem` files into your application -=========================================================================== - -## SYNOPSIS - -`bundle cache` - -## DESCRIPTION - -Copy all of the `.gem` files needed to run the application into the -`vendor/cache` directory. In the future, when running [bundle install(1)][bundle-install], -use the gems in the cache in preference to the ones on `rubygems.org`. - -## GIT AND PATH GEMS - -The `bundle cache` command can also package `:git` and `:path` dependencies -besides .gem files. This needs to be explicitly enabled via the `--all` option. -Once used, the `--all` option will be remembered. - -## SUPPORT FOR MULTIPLE PLATFORMS - -When using gems that have different packages for different platforms, Bundler -supports caching of gems for other platforms where the Gemfile has been resolved -(i.e. present in the lockfile) in `vendor/cache`. This needs to be enabled via -the `--all-platforms` option. This setting will be remembered in your local -bundler configuration. - -## REMOTE FETCHING - -By default, if you run `bundle install(1)`](bundle-install.1.html) after running -[bundle cache(1)](bundle-cache.1.html), bundler will still connect to `rubygems.org` -to check whether a platform-specific gem exists for any of the gems -in `vendor/cache`. - -For instance, consider this Gemfile(5): - - source "https://rubygems.org" - - gem "nokogiri" - -If you run `bundle cache` under C Ruby, bundler will retrieve -the version of `nokogiri` for the `"ruby"` platform. If you deploy -to JRuby and run `bundle install`, bundler is forced to check to -see whether a `"java"` platformed `nokogiri` exists. - -Even though the `nokogiri` gem for the Ruby platform is -_technically_ acceptable on JRuby, it has a C extension -that does not run on JRuby. As a result, bundler will, by default, -still connect to `rubygems.org` to check whether it has a version -of one of your gems more specific to your platform. - -This problem is also not limited to the `"java"` platform. -A similar (common) problem can happen when developing on Windows -and deploying to Linux, or even when developing on OSX and -deploying to Linux. - -If you know for sure that the gems packaged in `vendor/cache` -are appropriate for the platform you are on, you can run -`bundle install --local` to skip checking for more appropriate -gems, and use the ones in `vendor/cache`. - -One way to be sure that you have the right platformed versions -of all your gems is to run `bundle cache` on an identical -machine and check in the gems. For instance, you can run -`bundle cache` on an identical staging box during your -staging process, and check in the `vendor/cache` before -deploying to production. - -By default, [bundle cache(1)](bundle-cache.1.html) fetches and also -installs the gems to the default location. To package the -dependencies to `vendor/cache` without installing them to the -local install location, you can run `bundle cache --no-install`. diff --git a/man/bundle-check.1 b/man/bundle-check.1 index 4c7bc3f329..3f1a4bc329 100644 --- a/man/bundle-check.1 +++ b/man/bundle-check.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-CHECK" "1" "October 2020" "" "" +.TH "BUNDLE\-CHECK" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-check\fR \- Verifies if dependencies are satisfied by installed gems diff --git a/man/bundle-check.1.ronn b/man/bundle-check.1.ronn deleted file mode 100644 index f2846b8ff2..0000000000 --- a/man/bundle-check.1.ronn +++ /dev/null @@ -1,26 +0,0 @@ -bundle-check(1) -- Verifies if dependencies are satisfied by installed gems -=========================================================================== - -## SYNOPSIS - -`bundle check` [--dry-run] - [--gemfile=FILE] - [--path=PATH] - -## DESCRIPTION - -`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 exits with -a status of 0. - -If not, the first missing gem is listed and Bundler exits status 1. - -## OPTIONS - -* `--dry-run`: - Locks the [`Gemfile(5)`][Gemfile(5)] before running the command. -* `--gemfile`: - Use the specified gemfile instead of the [`Gemfile(5)`][Gemfile(5)]. -* `--path`: - Specify a different path than the system default (`$BUNDLE_PATH` or `$GEM_HOME`). - Bundler will remember this value for future installs on this machine. diff --git a/man/bundle-clean.1 b/man/bundle-clean.1 index dd1682a48b..1c111ae906 100644 --- a/man/bundle-clean.1 +++ b/man/bundle-clean.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-CLEAN" "1" "October 2020" "" "" +.TH "BUNDLE\-CLEAN" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-clean\fR \- Cleans up unused gems in your bundler directory diff --git a/man/bundle-clean.1.ronn b/man/bundle-clean.1.ronn deleted file mode 100644 index de23991782..0000000000 --- a/man/bundle-clean.1.ronn +++ /dev/null @@ -1,18 +0,0 @@ -bundle-clean(1) -- Cleans up unused gems in your bundler directory -================================================================== - -## SYNOPSIS - -`bundle clean` [--dry-run] [--force] - -## DESCRIPTION - -This command will remove all unused gems in your bundler directory. This is -useful when you have made many changes to your gem dependencies. - -## OPTIONS - -* `--dry-run`: - Print the changes, but do not clean the unused gems. -* `--force`: - Force a clean even if `--path` is not set. diff --git a/man/bundle-config.1 b/man/bundle-config.1 index d989aaeb86..39b32e7496 100644 --- a/man/bundle-config.1 +++ b/man/bundle-config.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-CONFIG" "1" "October 2020" "" "" +.TH "BUNDLE\-CONFIG" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-config\fR \- Set bundler configuration options @@ -262,9 +262,6 @@ The following is a list of all configuration keys and their purpose\. You can le \fBsilence_root_warning\fR (\fBBUNDLE_SILENCE_ROOT_WARNING\fR): Silence the warning Bundler prints when installing gems as root\. . .IP "\(bu" 4 -\fBspecific_platform\fR (\fBBUNDLE_SPECIFIC_PLATFORM\fR): Allow bundler to resolve for the specific running platform and store it in the lockfile, instead of only using a generic platform\. A specific platform is the exact platform triple reported by \fBGem::Platform\.local\fR, such as \fBx86_64\-darwin\-16\fR or \fBuniversal\-java\-1\.8\fR\. On the other hand, generic platforms are those such as \fBruby\fR, \fBmswin\fR, or \fBjava\fR\. In this example, \fBx86_64\-darwin\-16\fR would map to \fBruby\fR and \fBuniversal\-java\-1\.8\fR to \fBjava\fR\. -. -.IP "\(bu" 4 \fBssl_ca_cert\fR (\fBBUNDLE_SSL_CA_CERT\fR): Path to a designated CA certificate file or folder containing multiple certificates for trusted CAs in PEM format\. . .IP "\(bu" 4 @@ -441,7 +438,7 @@ For gems with a git source with HTTP(S) URL you can specify credentials like so: . .nf -bundle config set \-\-global https://github\.com/bundler/bundler\.git username:password +bundle config set \-\-global https://github\.com/rubygems/rubygems\.git username:password . .fi . diff --git a/man/bundle-config.1.ronn b/man/bundle-config.1.ronn deleted file mode 100644 index a0ff30cb15..0000000000 --- a/man/bundle-config.1.ronn +++ /dev/null @@ -1,396 +0,0 @@ -bundle-config(1) -- Set bundler configuration options -===================================================== - -## SYNOPSIS - -`bundle config` [list|get|set|unset] [<name> [<value>]] - -## DESCRIPTION - -This command allows you to interact with Bundler's configuration system. - -Bundler loads configuration settings in this order: - -1. Local config (`<project_root>/.bundle/config` or `$BUNDLE_APP_CONFIG/config`) -2. Environmental variables (`ENV`) -3. Global config (`~/.bundle/config`) -4. Bundler default config - -Executing `bundle config list` with will print a list of all bundler -configuration for the current bundle, and where that configuration -was set. - -Executing `bundle config get <name>` will print the value of that configuration -setting, and where it was set. - -Executing `bundle config set <name> <value>` will set that configuration to the -value specified for all bundles executed as the current user. The configuration -will be stored in `~/.bundle/config`. If <name> already is set, <name> will be -overridden and user will be warned. - -Executing `bundle config set --global <name> <value>` works the same as above. - -Executing `bundle config set --local <name> <value>` will set that configuration -in the directory for the local application. The configuration will be stored in -`<project_root>/.bundle/config`. If `BUNDLE_APP_CONFIG` is set, the configuration -will be stored in `$BUNDLE_APP_CONFIG/config`. - -Executing `bundle config unset <name>` will delete the configuration in both -local and global sources. - -Executing `bundle config unset --global <name>` will delete the configuration -only from the user configuration. - -Executing `bundle config unset --local <name> <value>` will delete the -configuration only from the local application. - -Executing bundle with the `BUNDLE_IGNORE_CONFIG` environment variable set will -cause it to ignore all configuration. - -Executing `bundle config set --local disable_multisource true` upgrades the warning about -the Gemfile containing multiple primary sources to an error. Executing `bundle -config unset disable_multisource` downgrades this error to a warning. - -## REMEMBERING OPTIONS - -Flags passed to `bundle install` or the Bundler runtime, such as `--path foo` or -`--without production`, are remembered between commands and saved to your local -application's configuration (normally, `./.bundle/config`). - -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 set them using -`bundle config` (e.g., `bundle config set --local path foo`). - -The options that can be configured are: - -* `bin`: - Creates a directory (defaults to `~/bin`) and place any executables from the - gem there. These executables run in Bundler's context. If used, you might add - this directory to your environment's `PATH` variable. For instance, if the - `rails` gem comes with a `rails` executable, this flag will create a - `bin/rails` executable that ensures that all referred dependencies will be - resolved using the bundled gems. - -* `deployment`: - In deployment mode, Bundler will 'roll-out' the bundle for - `production` use. Please check carefully if you want to have this option - enabled in `development` or `test` environments. - -* `path`: - The location to install the specified gems to. This defaults to Rubygems' - setting. Bundler shares this location with Rubygems, `gem install ...` will - have gem installed there, too. Therefore, gems installed without a - `--path ...` setting will show up by calling `gem list`. Accordingly, gems - installed to other locations will not get listed. - -* `without`: - A space-separated list of groups referencing gems to skip during installation. - -* `with`: - A space-separated list of groups referencing gems to include during installation. - -## BUILD OPTIONS - -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. - -A very common example, the `mysql` gem, requires Snow Leopard users to -pass configuration flags to `gem install` to specify where to find the -`mysql_config` executable. - - gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config - -Since the specific location of that executable can change from machine -to machine, you can specify these flags on a per-machine basis. - - bundle config set --global build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config - -After running this command, every time bundler needs to install the -`mysql` gem, it will pass along the flags you specified. - -## CONFIGURATION KEYS - -Configuration keys in bundler have two forms: the canonical form and the -environment variable form. - -For instance, passing the `--without` flag to [bundle install(1)](bundle-install.1.html) -prevents Bundler from installing certain groups specified in the Gemfile(5). Bundler -persists this value in `app/.bundle/config` so that calls to `Bundler.setup` -do not try to find gems from the `Gemfile` that you didn't install. Additionally, -subsequent calls to [bundle install(1)](bundle-install.1.html) remember this setting -and skip those groups. - -The canonical form of this configuration is `"without"`. To convert the canonical -form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The -environment variable form of `"without"` is `BUNDLE_WITHOUT`. - -Any periods in the configuration keys must be replaced with two underscores when -setting it via environment variables. The configuration key `local.rack` becomes -the environment variable `BUNDLE_LOCAL__RACK`. - -## LIST OF AVAILABLE KEYS - -The following is a list of all configuration keys and their purpose. You can -learn more about their operation in [bundle install(1)](bundle-install.1.html). - -* `allow_bundler_dependency_conflicts` (`BUNDLE_ALLOW_BUNDLER_DEPENDENCY_CONFLICTS`): - Allow resolving to specifications that have dependencies on `bundler` that - are incompatible with the running Bundler version. -* `allow_deployment_source_credential_changes` (`BUNDLE_ALLOW_DEPLOYMENT_SOURCE_CREDENTIAL_CHANGES`): - When in deployment mode, allow changing the credentials to a gem's source. - Ex: `https://some.host.com/gems/path/` -> `https://user_name:password@some.host.com/gems/path` -* `allow_offline_install` (`BUNDLE_ALLOW_OFFLINE_INSTALL`): - Allow Bundler to use cached data when installing without network access. -* `auto_clean_without_path` (`BUNDLE_AUTO_CLEAN_WITHOUT_PATH`): - Automatically run `bundle clean` after installing when an explicit `path` - has not been set and Bundler is not installing into the system gems. -* `auto_install` (`BUNDLE_AUTO_INSTALL`): - Automatically run `bundle install` when gems are missing. -* `bin` (`BUNDLE_BIN`): - Install executables from gems in the bundle to the specified directory. - Defaults to `false`. -* `cache_all` (`BUNDLE_CACHE_ALL`): - Cache all gems, including path and git gems. This needs to be explicitly - configured on bundler 1 and bundler 2, but will be the default on bundler 3. -* `cache_all_platforms` (`BUNDLE_CACHE_ALL_PLATFORMS`): - Cache gems for all platforms. -* `cache_path` (`BUNDLE_CACHE_PATH`): - The directory that bundler will place cached gems in when running - <code>bundle package</code>, and that bundler will look in when installing gems. - Defaults to `vendor/cache`. -* `clean` (`BUNDLE_CLEAN`): - Whether Bundler should run `bundle clean` automatically after - `bundle install`. -* `console` (`BUNDLE_CONSOLE`): - The console that `bundle console` starts. Defaults to `irb`. -* `default_install_uses_path` (`BUNDLE_DEFAULT_INSTALL_USES_PATH`): - Whether a `bundle install` without an explicit `--path` argument defaults - to installing gems in `.bundle`. -* `deployment` (`BUNDLE_DEPLOYMENT`): - Disallow changes to the `Gemfile`. When the `Gemfile` is changed and the - lockfile has not been updated, running Bundler commands will be blocked. -* `disable_checksum_validation` (`BUNDLE_DISABLE_CHECKSUM_VALIDATION`): - Allow installing gems even if they do not match the checksum provided by - RubyGems. -* `disable_exec_load` (`BUNDLE_DISABLE_EXEC_LOAD`): - Stop Bundler from using `load` to launch an executable in-process in - `bundle exec`. -* `disable_local_branch_check` (`BUNDLE_DISABLE_LOCAL_BRANCH_CHECK`): - Allow Bundler to use a local git override without a branch specified in the - Gemfile. -* `disable_multisource` (`BUNDLE_DISABLE_MULTISOURCE`): - When set, Gemfiles containing multiple sources will produce errors - instead of warnings. - Use `bundle config unset disable_multisource` to unset. -* `disable_shared_gems` (`BUNDLE_DISABLE_SHARED_GEMS`): - Stop Bundler from accessing gems installed to RubyGems' normal location. -* `disable_version_check` (`BUNDLE_DISABLE_VERSION_CHECK`): - Stop Bundler from checking if a newer Bundler version is available on - rubygems.org. -* `force_ruby_platform` (`BUNDLE_FORCE_RUBY_PLATFORM`): - Ignore the current machine's platform and install only `ruby` platform gems. - As a result, gems with native extensions will be compiled from source. -* `frozen` (`BUNDLE_FROZEN`): - Disallow changes to the `Gemfile`. When the `Gemfile` is changed and the - lockfile has not been updated, running Bundler commands will be blocked. - Defaults to `true` when `--deployment` is used. -* `gem.push_key` (`BUNDLE_GEM__PUSH_KEY`): - Sets the `--key` parameter for `gem push` when using the `rake release` - command with a private gemstash server. -* `gemfile` (`BUNDLE_GEMFILE`): - The name of the file that bundler should use as the `Gemfile`. This location - of this file also sets the root of the project, which is used to resolve - relative paths in the `Gemfile`, among other things. By default, bundler - will search up from the current working directory until it finds a - `Gemfile`. -* `global_gem_cache` (`BUNDLE_GLOBAL_GEM_CACHE`): - Whether Bundler should cache all gems globally, rather than locally to the - installing Ruby installation. -* `ignore_messages` (`BUNDLE_IGNORE_MESSAGES`): When set, no post install - messages will be printed. To silence a single gem, use dot notation like - `ignore_messages.httparty true`. -* `init_gems_rb` (`BUNDLE_INIT_GEMS_RB`) - Generate a `gems.rb` instead of a `Gemfile` when running `bundle init`. -* `jobs` (`BUNDLE_JOBS`): - The number of gems Bundler can install in parallel. Defaults to 1. -* `no_install` (`BUNDLE_NO_INSTALL`): - Whether `bundle package` should skip installing gems. -* `no_prune` (`BUNDLE_NO_PRUNE`): - Whether Bundler should leave outdated gems unpruned when caching. -* `only_update_to_newer_versions` (`BUNDLE_ONLY_UPDATE_TO_NEWER_VERSIONS`): - During `bundle update`, only resolve to newer versions of the gems in the - lockfile. -* `path` (`BUNDLE_PATH`): - The location on disk where all gems in your bundle will be located regardless - of `$GEM_HOME` or `$GEM_PATH` values. Bundle gems not found in this location - will be installed by `bundle install`. Defaults to `Gem.dir`. When --deployment - is used, defaults to vendor/bundle. -* `path.system` (`BUNDLE_PATH__SYSTEM`): - Whether Bundler will install gems into the default system path (`Gem.dir`). -* `path_relative_to_cwd` (`BUNDLE_PATH_RELATIVE_TO_CWD`) - Makes `--path` relative to the CWD instead of the `Gemfile`. -* `plugins` (`BUNDLE_PLUGINS`): - Enable Bundler's experimental plugin system. -* `prefer_patch` (BUNDLE_PREFER_PATCH): - Prefer updating only to next patch version during updates. Makes `bundle update` calls equivalent to `bundler update --patch`. -* `print_only_version_number` (`BUNDLE_PRINT_ONLY_VERSION_NUMBER`) - Print only version number from `bundler --version`. -* `redirect` (`BUNDLE_REDIRECT`): - The number of redirects allowed for network requests. Defaults to `5`. -* `retry` (`BUNDLE_RETRY`): - The number of times to retry failed network requests. Defaults to `3`. -* `setup_makes_kernel_gem_public` (`BUNDLE_SETUP_MAKES_KERNEL_GEM_PUBLIC`): - Have `Bundler.setup` make the `Kernel#gem` method public, even though - RubyGems declares it as private. -* `shebang` (`BUNDLE_SHEBANG`): - The program name that should be invoked for generated binstubs. Defaults to - the ruby install name used to generate the binstub. -* `silence_deprecations` (`BUNDLE_SILENCE_DEPRECATIONS`): - Whether Bundler should silence deprecation warnings for behavior that will - be changed in the next major version. -* `silence_root_warning` (`BUNDLE_SILENCE_ROOT_WARNING`): - Silence the warning Bundler prints when installing gems as root. -* `specific_platform` (`BUNDLE_SPECIFIC_PLATFORM`): - Allow bundler to resolve for the specific running platform and store it in - the lockfile, instead of only using a generic platform. - A specific platform is the exact platform triple reported by - `Gem::Platform.local`, such as `x86_64-darwin-16` or `universal-java-1.8`. - On the other hand, generic platforms are those such as `ruby`, `mswin`, or - `java`. In this example, `x86_64-darwin-16` would map to `ruby` and - `universal-java-1.8` to `java`. -* `ssl_ca_cert` (`BUNDLE_SSL_CA_CERT`): - Path to a designated CA certificate file or folder containing multiple - certificates for trusted CAs in PEM format. -* `ssl_client_cert` (`BUNDLE_SSL_CLIENT_CERT`): - Path to a designated file containing a X.509 client certificate - and key in PEM format. -* `ssl_verify_mode` (`BUNDLE_SSL_VERIFY_MODE`): - The SSL verification mode Bundler uses when making HTTPS requests. - Defaults to verify peer. -* `suppress_install_using_messages` (`BUNDLE_SUPPRESS_INSTALL_USING_MESSAGES`): - Avoid printing `Using ...` messages during installation when the version of - a gem has not changed. -* `system_bindir` (`BUNDLE_SYSTEM_BINDIR`): - The location where RubyGems installs binstubs. Defaults to `Gem.bindir`. -* `timeout` (`BUNDLE_TIMEOUT`): - The seconds allowed before timing out for network requests. Defaults to `10`. -* `unlock_source_unlocks_spec` (`BUNDLE_UNLOCK_SOURCE_UNLOCKS_SPEC`): - Whether running `bundle update --source NAME` unlocks a gem with the given - name. Defaults to `true`. -* `update_requires_all_flag` (`BUNDLE_UPDATE_REQUIRES_ALL_FLAG`) - Require passing `--all` to `bundle update` when everything should be updated, - and disallow passing no options to `bundle update`. -* `user_agent` (`BUNDLE_USER_AGENT`): - The custom user agent fragment Bundler includes in API requests. -* `with` (`BUNDLE_WITH`): - A `:`-separated list of groups whose gems bundler should install. -* `without` (`BUNDLE_WITHOUT`): - A `:`-separated list of groups whose gems bundler should not install. - -In general, you should set these settings per-application by using the applicable -flag to the [bundle install(1)](bundle-install.1.html) or [bundle package(1)](bundle-package.1.html) command. - -You can set them globally either via environment variables or `bundle config`, -whichever is preferable for your setup. If you use both, environment variables -will take preference over global settings. - -## LOCAL GIT REPOS - -Bundler also allows you to work against a git repository locally -instead of using the remote version. This can be achieved by setting -up a local override: - - bundle config set --local local.GEM_NAME /path/to/local/git/repository - -For example, in order to use a local Rack repository, a developer could call: - - bundle config set --local local.rack ~/Work/git/rack - -Now instead of checking out the remote git repository, the local -override will be used. Similar to a path source, every time the local -git repository change, changes will be automatically picked up by -Bundler. This means a commit in the local git repo will update the -revision in the `Gemfile.lock` to the local git repo revision. This -requires the same attention as git submodules. Before pushing to -the remote, you need to ensure the local override was pushed, otherwise -you may point to a commit that only exists in your local machine. -You'll also need to CGI escape your usernames and passwords as well. - -Bundler does many checks to ensure a developer won't work with -invalid references. Particularly, we force a developer to specify -a branch in the `Gemfile` in order to use this feature. If the branch -specified in the `Gemfile` and the current branch in the local git -repository do not match, Bundler will abort. This ensures that -a developer is always working against the correct branches, and prevents -accidental locking to a different branch. - -Finally, Bundler also ensures that the current revision in the -`Gemfile.lock` exists in the local git repository. By doing this, Bundler -forces you to fetch the latest changes in the remotes. - -## MIRRORS OF GEM SOURCES - -Bundler supports overriding gem sources with mirrors. This allows you to -configure rubygems.org as the gem source in your Gemfile while still using your -mirror to fetch gems. - - bundle config set --global mirror.SOURCE_URL MIRROR_URL - -For example, to use a mirror of rubygems.org hosted at rubygems-mirror.org: - - bundle config set --global mirror.http://rubygems.org http://rubygems-mirror.org - -Each mirror also provides a fallback timeout setting. If the mirror does not -respond within the fallback timeout, Bundler will try to use the original -server instead of the mirror. - - bundle config set --global mirror.SOURCE_URL.fallback_timeout TIMEOUT - -For example, to fall back to rubygems.org after 3 seconds: - - bundle config set --global mirror.https://rubygems.org.fallback_timeout 3 - -The default fallback timeout is 0.1 seconds, but the setting can currently -only accept whole seconds (for example, 1, 15, or 30). - -## CREDENTIALS FOR GEM SOURCES - -Bundler allows you to configure credentials for any gem source, which allows -you to avoid putting secrets into your Gemfile. - - bundle config set --global SOURCE_HOSTNAME USERNAME:PASSWORD - -For example, to save the credentials of user `claudette` for the gem source at -`gems.longerous.com`, you would run: - - bundle config set --global gems.longerous.com claudette:s00pers3krit - -Or you can set the credentials as an environment variable like this: - - export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit" - -For gems with a git source with HTTP(S) URL you can specify credentials like so: - - bundle config set --global https://github.com/bundler/bundler.git username:password - -Or you can set the credentials as an environment variable like so: - - export BUNDLE_GITHUB__COM=username:password - -This is especially useful for private repositories on hosts such as Github, -where you can use personal OAuth tokens: - - export BUNDLE_GITHUB__COM=abcd0123generatedtoken:x-oauth-basic - - -## CONFIGURE BUNDLER DIRECTORIES - -Bundler's home, config, cache and plugin directories are able to be configured -through environment variables. The default location for Bundler's home directory is -`~/.bundle`, which all directories inherit from by default. The following -outlines the available environment variables and their default values - - BUNDLE_USER_HOME : $HOME/.bundle - BUNDLE_USER_CACHE : $BUNDLE_USER_HOME/cache - BUNDLE_USER_CONFIG : $BUNDLE_USER_HOME/config - BUNDLE_USER_PLUGIN : $BUNDLE_USER_HOME/plugin diff --git a/man/bundle-doctor.1 b/man/bundle-doctor.1 index 82f0fc6fba..39841c8032 100644 --- a/man/bundle-doctor.1 +++ b/man/bundle-doctor.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-DOCTOR" "1" "October 2020" "" "" +.TH "BUNDLE\-DOCTOR" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-doctor\fR \- Checks the bundle for common problems diff --git a/man/bundle-doctor.1.ronn b/man/bundle-doctor.1.ronn deleted file mode 100644 index 271ee800ad..0000000000 --- a/man/bundle-doctor.1.ronn +++ /dev/null @@ -1,33 +0,0 @@ -bundle-doctor(1) -- Checks the bundle for common problems -========================================================= - -## SYNOPSIS - -`bundle doctor` [--quiet] - [--gemfile=GEMFILE] - -## DESCRIPTION - -Checks your Gemfile and gem environment for common problems. If issues -are detected, Bundler prints them and exits status 1. Otherwise, -Bundler prints a success message and exits status 0. - -Examples of common problems caught by bundle-doctor include: - -* Invalid Bundler settings -* Mismatched Ruby versions -* Mismatched platforms -* Uninstalled gems -* Missing dependencies - -## OPTIONS - -* `--quiet`: - Only output warnings and errors. - -* `--gemfile=<gemfile>`: - The location of the Gemfile(5) which Bundler should use. This defaults - to a Gemfile(5) in the current working directory. In general, Bundler - will assume that the location of the Gemfile(5) is also the project's - root and will try to find `Gemfile.lock` and `vendor/cache` relative - to this location. diff --git a/man/bundle-exec.1 b/man/bundle-exec.1 index 4dc42bed28..b8c1b308c3 100644 --- a/man/bundle-exec.1 +++ b/man/bundle-exec.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-EXEC" "1" "October 2020" "" "" +.TH "BUNDLE\-EXEC" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-exec\fR \- Execute a command in the context of the bundle diff --git a/man/bundle-exec.1.ronn b/man/bundle-exec.1.ronn deleted file mode 100644 index dec3c7cb82..0000000000 --- a/man/bundle-exec.1.ronn +++ /dev/null @@ -1,152 +0,0 @@ -bundle-exec(1) -- Execute a command in the context of the bundle -================================================================ - -## SYNOPSIS - -`bundle exec` [--keep-file-descriptors] <command> - -## DESCRIPTION - -This command executes the command, making all gems specified in the -[`Gemfile(5)`][Gemfile(5)] available to `require` in Ruby programs. - -Essentially, if you would normally have run something like -`rspec spec/my_spec.rb`, and you want to use the gems specified -in the [`Gemfile(5)`][Gemfile(5)] and installed via [bundle install(1)](bundle-install.1.html), you -should run `bundle exec rspec spec/my_spec.rb`. - -Note that `bundle exec` does not require that an executable is -available on your shell's `$PATH`. - -## OPTIONS - -* `--keep-file-descriptors`: - Exec in Ruby 2.0 began discarding non-standard file descriptors. When this - flag is passed, exec will revert to the 1.9 behaviour of passing all file - descriptors to the new process. - -## BUNDLE INSTALL --BINSTUBS - -If you use the `--binstubs` flag in [bundle install(1)](bundle-install.1.html), Bundler will -automatically create a directory (which defaults to `app_root/bin`) -containing all of the executables available from gems in the bundle. - -After using `--binstubs`, `bin/rspec spec/my_spec.rb` is identical -to `bundle exec rspec spec/my_spec.rb`. - -## ENVIRONMENT MODIFICATIONS - -`bundle exec` makes a number of changes to the shell environment, -then executes the command you specify in full. - -* make sure that it's still possible to shell out to `bundle` - from inside a command invoked by `bundle exec` (using - `$BUNDLE_BIN_PATH`) -* put the directory containing executables (like `rails`, `rspec`, - `rackup`) for your bundle on `$PATH` -* make sure that if bundler is invoked in the subshell, it uses - the same `Gemfile` (by setting `BUNDLE_GEMFILE`) -* add `-rbundler/setup` to `$RUBYOPT`, which makes sure that - Ruby programs invoked in the subshell can see the gems in - the bundle - -It also modifies Rubygems: - -* disallow loading additional gems not in the bundle -* modify the `gem` method to be a no-op if a gem matching - the requirements is in the bundle, and to raise a - `Gem::LoadError` if it's not -* Define `Gem.refresh` to be a no-op, since the source - index is always frozen when using bundler, and to - prevent gems from the system leaking into the environment -* Override `Gem.bin_path` to use the gems in the bundle, - making system executables work -* Add all gems in the bundle into Gem.loaded_specs - -Finally, `bundle exec` also implicitly modifies `Gemfile.lock` if the lockfile -and the Gemfile do not match. Bundler needs the Gemfile to determine things -such as a gem's groups, `autorequire`, and platforms, etc., and that -information isn't stored in the lockfile. The Gemfile and lockfile must be -synced in order to `bundle exec` successfully, so `bundle exec` -updates the lockfile beforehand. - -### Loading - -By default, when attempting to `bundle exec` to a file with a ruby shebang, -Bundler will `Kernel.load` that file instead of using `Kernel.exec`. For the -vast majority of cases, this is a performance improvement. In a rare few cases, -this could cause some subtle side-effects (such as dependence on the exact -contents of `$0` or `__FILE__`) and the optimization can be disabled by enabling -the `disable_exec_load` setting. - -### Shelling out - -Any Ruby code that opens a subshell (like `system`, backticks, or `%x{}`) will -automatically use the current Bundler environment. If you need to shell out to -a Ruby command that is not part of your current bundle, use the -`with_clean_env` method with a block. Any subshells created inside the block -will be given the environment present before Bundler was activated. For -example, Homebrew commands run Ruby, but don't work inside a bundle: - - Bundler.with_clean_env do - `brew install wget` - end - -Using `with_clean_env` is also necessary if you are shelling out to a different -bundle. Any Bundler commands run in a subshell will inherit the current -Gemfile, so commands that need to run in the context of a different bundle also -need to use `with_clean_env`. - - Bundler.with_clean_env do - Dir.chdir "/other/bundler/project" do - `bundle exec ./script` - end - end - -Bundler provides convenience helpers that wrap `system` and `exec`, and they -can be used like this: - - Bundler.clean_system('brew install wget') - Bundler.clean_exec('brew install wget') - - -## RUBYGEMS PLUGINS - -At present, the Rubygems plugin system requires all files -named `rubygems_plugin.rb` on the load path of _any_ installed -gem when any Ruby code requires `rubygems.rb`. This includes -executables installed into the system, like `rails`, `rackup`, -and `rspec`. - -Since Rubygems plugins can contain arbitrary Ruby code, they -commonly end up activating themselves or their dependencies. - -For instance, the `gemcutter 0.5` gem depended on `json_pure`. -If you had that version of gemcutter installed (even if -you _also_ had a newer version without this problem), Rubygems -would activate `gemcutter 0.5` and `json_pure <latest>`. - -If your Gemfile(5) also contained `json_pure` (or a gem -with a dependency on `json_pure`), the latest version on -your system might conflict with the version in your -Gemfile(5), or the snapshot version in your `Gemfile.lock`. - -If this happens, bundler will say: - - You have already activated json_pure 1.4.6 but your Gemfile - requires json_pure 1.4.3. Consider using bundle exec. - -In this situation, you almost certainly want to remove the -underlying gem with the problematic gem plugin. In general, -the authors of these plugins (in this case, the `gemcutter` -gem) have released newer versions that are more careful in -their plugins. - -You can find a list of all the gems containing gem plugins -by running - - ruby -rrubygems -e "puts Gem.find_files('rubygems_plugin.rb')" - -At the very least, you should remove all but the newest -version of each gem plugin, and also remove all gem plugins -that you aren't using (`gem uninstall gem_name`). diff --git a/man/bundle-gem.1 b/man/bundle-gem.1 index 124df739cc..65c35615c5 100644 --- a/man/bundle-gem.1 +++ b/man/bundle-gem.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-GEM" "1" "October 2020" "" "" +.TH "BUNDLE\-GEM" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-gem\fR \- Generate a project skeleton for creating a rubygem diff --git a/man/bundle-gem.1.ronn b/man/bundle-gem.1.ronn deleted file mode 100644 index a997cb907a..0000000000 --- a/man/bundle-gem.1.ronn +++ /dev/null @@ -1,101 +0,0 @@ -bundle-gem(1) -- Generate a project skeleton for creating a rubygem -==================================================================== - -## SYNOPSIS - -`bundle gem` <GEM_NAME> [OPTIONS] - -## DESCRIPTION - -Generates a directory named `GEM_NAME` with a `Rakefile`, `GEM_NAME.gemspec`, -and other supporting files and directories that can be used to develop a -rubygem with that name. - -Run `rake -T` in the resulting project for a list of Rake tasks that can be used -to test and publish the gem to rubygems.org. - -The generated project skeleton can be customized with OPTIONS, as explained -below. Note that these options can also be specified via Bundler's global -configuration file using the following names: - -* `gem.coc` -* `gem.mit` -* `gem.test` - -## OPTIONS - -* `--exe` or `-b` or `--bin`: - Specify that Bundler should create a binary executable (as `exe/GEM_NAME`) - in the generated rubygem project. This binary will also be added to the - `GEM_NAME.gemspec` manifest. This behavior is disabled by default. - -* `--no-exe`: - Do not create a binary (overrides `--exe` specified in the global config). - -* `--coc`: - Add a `CODE_OF_CONDUCT.md` file to the root of the generated project. If - this option is unspecified, an interactive prompt will be displayed and the - answer will be saved in Bundler's global config for future `bundle gem` use. - -* `--no-coc`: - Do not create a `CODE_OF_CONDUCT.md` (overrides `--coc` specified in the - global config). - -* `--ext`: - Add boilerplate for C extension code to the generated project. This behavior - is disabled by default. - -* `--no-ext`: - Do not add C extension code (overrides `--ext` specified in the global - config). - -* `--mit`: - Add an MIT license to a `LICENSE.txt` file in the root of the generated - project. Your name from the global git config is used for the copyright - statement. If this option is unspecified, an interactive prompt will be - displayed and the answer will be saved in Bundler's global config for future - `bundle gem` use. - -* `--no-mit`: - Do not create a `LICENSE.txt` (overrides `--mit` specified in the global - config). - -* `-t`, `--test=minitest`, `--test=rspec`, `--test=test-unit`: - Specify the test framework that Bundler should use when generating the - project. Acceptable values are `minitest`, `rspec` and `test-unit`. The - `GEM_NAME.gemspec` will be configured and a skeleton test/spec directory will - be created based on this option. Given no option is specified: - - When Bundler is configured to generate tests, this defaults to Bundler's - global config setting `gem.test`. - - When Bundler is configured to not generate tests, an interactive prompt will - be displayed and the answer will be used for the current rubygem project. - - When Bundler is unconfigured, an interactive prompt will be displayed and - the answer will be saved in Bundler's global config for future `bundle gem` - use. - -* `--ci`, `--ci=github`, `--ci=travis`, `--ci=gitlab`, `--ci=circle`: - Specify the continuous integration service that Bundler should use when - generating the project. Acceptable values are `github`, `travis`, `gitlab` - and `circle`. A configuration file will be generated in the project directory. - Given no option is specified: - - When Bundler is configured to generate CI files, this defaults to Bundler's - global config setting `gem.ci`. - - When Bundler is configured to not generate CI files, an interactive prompt - will be displayed and the answer will be used for the current rubygem project. - - When Bundler is unconfigured, an interactive prompt will be displayed and - the answer will be saved in Bundler's global config for future `bundle gem` - use. - -* `-e`, `--edit[=EDITOR]`: - Open the resulting GEM_NAME.gemspec in EDITOR, or the default editor if not - specified. The default is `$BUNDLER_EDITOR`, `$VISUAL`, or `$EDITOR`. - -## SEE ALSO - -* [bundle config(1)](bundle-config.1.html) diff --git a/man/bundle-info.1 b/man/bundle-info.1 index 2d860d51ab..b20396d273 100644 --- a/man/bundle-info.1 +++ b/man/bundle-info.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-INFO" "1" "October 2020" "" "" +.TH "BUNDLE\-INFO" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-info\fR \- Show information for the given gem in your bundle diff --git a/man/bundle-info.1.ronn b/man/bundle-info.1.ronn deleted file mode 100644 index 47e457aa3c..0000000000 --- a/man/bundle-info.1.ronn +++ /dev/null @@ -1,17 +0,0 @@ -bundle-info(1) -- Show information for the given gem in your bundle -========================================================================= - -## SYNOPSIS - -`bundle info` [GEM] - [--path] - -## DESCRIPTION - -Print the basic information about the provided GEM such as homepage, version, -path and summary. - -## OPTIONS - -* `--path`: -Print the path of the given gem diff --git a/man/bundle-init.1 b/man/bundle-init.1 index c21e269071..b6714730c4 100644 --- a/man/bundle-init.1 +++ b/man/bundle-init.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-INIT" "1" "October 2020" "" "" +.TH "BUNDLE\-INIT" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-init\fR \- Generates a Gemfile into the current working directory diff --git a/man/bundle-init.1.ronn b/man/bundle-init.1.ronn deleted file mode 100644 index 9d3d97deea..0000000000 --- a/man/bundle-init.1.ronn +++ /dev/null @@ -1,29 +0,0 @@ -bundle-init(1) -- Generates a Gemfile into the current working directory -======================================================================== - -## SYNOPSIS - -`bundle init` [--gemspec=FILE] - -## DESCRIPTION - -Init generates a default [`Gemfile(5)`][Gemfile(5)] in the current working directory. When -adding a [`Gemfile(5)`][Gemfile(5)] to a gem with a gemspec, the `--gemspec` option will -automatically add each dependency listed in the gemspec file to the newly -created [`Gemfile(5)`][Gemfile(5)]. - -## OPTIONS - -* `--gemspec`: - Use the specified .gemspec to create the [`Gemfile(5)`][Gemfile(5)] - -## FILES - -Included in the default [`Gemfile(5)`][Gemfile(5)] -generated is the line `# frozen_string_literal: true`. This is a magic comment -supported for the first time in Ruby 2.3. The presence of this line -results in all string literals in the file being implicitly frozen. - -## SEE ALSO - -[Gemfile(5)](https://bundler.io/man/gemfile.5.html) diff --git a/man/bundle-inject.1 b/man/bundle-inject.1 index 20bcbba735..9704eba89b 100644 --- a/man/bundle-inject.1 +++ b/man/bundle-inject.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-INJECT" "1" "October 2020" "" "" +.TH "BUNDLE\-INJECT" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-inject\fR \- Add named gem(s) with version requirements to Gemfile diff --git a/man/bundle-inject.1.ronn b/man/bundle-inject.1.ronn deleted file mode 100644 index f454341896..0000000000 --- a/man/bundle-inject.1.ronn +++ /dev/null @@ -1,22 +0,0 @@ -bundle-inject(1) -- Add named gem(s) with version requirements to Gemfile -========================================================================= - -## SYNOPSIS - -`bundle inject` [GEM] [VERSION] - -## DESCRIPTION - -Adds the named gem(s) with their version requirements to the resolved -[`Gemfile(5)`][Gemfile(5)]. - -This command will add the gem to both your [`Gemfile(5)`][Gemfile(5)] and Gemfile.lock if it -isn't listed yet. - -Example: - - bundle install - bundle inject 'rack' '> 0' - -This will inject the 'rack' gem with a version greater than 0 in your -[`Gemfile(5)`][Gemfile(5)] and Gemfile.lock diff --git a/man/bundle-install.1 b/man/bundle-install.1 index 0abd1a31e2..7c34f37cdd 100644 --- a/man/bundle-install.1 +++ b/man/bundle-install.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-INSTALL" "1" "October 2020" "" "" +.TH "BUNDLE\-INSTALL" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-install\fR \- Install the dependencies specified in your Gemfile @@ -67,7 +67,7 @@ The maximum number of parallel download and install jobs\. The default is \fB1\f . .TP \fB\-\-local\fR -Do not attempt to connect to \fBrubygems\.org\fR\. Instead, Bundler will use the gems already present in Rubygems\' cache or in \fBvendor/cache\fR\. Note that if a appropriate platform\-specific gem exists on \fBrubygems\.org\fR it will not be found\. +Do not attempt to connect to \fBrubygems\.org\fR\. Instead, Bundler will use the gems already present in Rubygems\' cache or in \fBvendor/cache\fR\. Note that if an appropriate platform\-specific gem exists on \fBrubygems\.org\fR it will not be found\. . .TP \fB\-\-no\-cache\fR diff --git a/man/bundle-install.1.ronn b/man/bundle-install.1.ronn deleted file mode 100644 index 07aeb1da90..0000000000 --- a/man/bundle-install.1.ronn +++ /dev/null @@ -1,405 +0,0 @@ -bundle-install(1) -- Install the dependencies specified in your Gemfile -======================================================================= - -## SYNOPSIS - -`bundle install` [--binstubs[=DIRECTORY]] - [--clean] - [--deployment] - [--frozen] - [--full-index] - [--gemfile=GEMFILE] - [--jobs=NUMBER] - [--local] - [--no-cache] - [--no-prune] - [--path PATH] - [--quiet] - [--redownload] - [--retry=NUMBER] - [--shebang] - [--standalone[=GROUP[ GROUP...]]] - [--system] - [--trust-policy=POLICY] - [--with=GROUP[ GROUP...]] - [--without=GROUP[ GROUP...]] - -## DESCRIPTION - -Install the gems specified in your Gemfile(5). If this is the first -time you run bundle install (and a `Gemfile.lock` does not exist), -Bundler will fetch all remote sources, resolve dependencies and -install all needed gems. - -If a `Gemfile.lock` does exist, and you have not updated your Gemfile(5), -Bundler will fetch all remote sources, but use the dependencies -specified in the `Gemfile.lock` instead of resolving dependencies. - -If a `Gemfile.lock` does exist, and you have updated your Gemfile(5), -Bundler will use the dependencies in the `Gemfile.lock` for all gems -that you did not update, but will re-resolve the dependencies of -gems that you did update. You can find more information about this -update process below under [CONSERVATIVE UPDATING][]. - -## OPTIONS - -The `--clean`, `--deployment`, `--frozen`, `--no-prune`, `--path`, `--shebang`, -`--system`, `--without` and `--with` options are deprecated because they only -make sense if they are applied to every subsequent `bundle install` run -automatically and that requires `bundler` to silently remember them. Since -`bundler` will no longer remember CLI flags in future versions, `bundle config` -(see bundle-config(1)) should be used to apply them permanently. - -* `--binstubs[=<directory>]`: - Binstubs are scripts that wrap around executables. Bundler creates a small Ruby - file (a binstub) that loads Bundler, runs the command, and puts it in `bin/`. - This lets you link the binstub inside of an application to the exact gem - version the application needs. - - Creates a directory (defaults to `~/bin`) and places any executables from the - gem there. These executables run in Bundler's context. If used, you might add - this directory to your environment's `PATH` variable. For instance, if the - `rails` gem comes with a `rails` executable, this flag will create a - `bin/rails` executable that ensures that all referred dependencies will be - resolved using the bundled gems. - -* `--clean`: - On finishing the installation Bundler is going to remove any gems not present - in the current Gemfile(5). Don't worry, gems currently in use will not be - removed. - - This option is deprecated in favor of the `clean` setting. - -* `--deployment`: - In [deployment mode][DEPLOYMENT MODE], Bundler will 'roll-out' the bundle for - production or CI use. Please check carefully if you want to have this option - enabled in your development environment. - - This option is deprecated in favor of the `deployment` setting. - -* `--redownload`: - Force download every gem, even if the required versions are already available - locally. - -* `--frozen`: - Do not allow the Gemfile.lock to be updated after this install. Exits - non-zero if there are going to be changes to the Gemfile.lock. - - This option is deprecated in favor of the `frozen` setting. - -* `--full-index`: - Bundler will not call Rubygems' API endpoint (default) but download and cache - a (currently big) index file of all gems. Performance can be improved for - large bundles that seldom change by enabling this option. - -* `--gemfile=<gemfile>`: - The location of the Gemfile(5) which Bundler should use. This defaults - to a Gemfile(5) in the current working directory. In general, Bundler - will assume that the location of the Gemfile(5) is also the project's - root and will try to find `Gemfile.lock` and `vendor/cache` relative - to this location. - -* `--jobs=[<number>]`, `-j[<number>]`: - The maximum number of parallel download and install jobs. The default - is `1`. - -* `--local`: - Do not attempt to connect to `rubygems.org`. Instead, Bundler will use the - gems already present in Rubygems' cache or in `vendor/cache`. Note that if a - appropriate platform-specific gem exists on `rubygems.org` it will not be - found. - -* `--no-cache`: - Do not update the cache in `vendor/cache` with the newly bundled gems. This - does not remove any gems in the cache but keeps the newly bundled gems from - being cached during the install. - -* `--no-prune`: - Don't remove stale gems from the cache when the installation finishes. - - This option is deprecated in favor of the `no_prune` setting. - -* `--path=<path>`: - The location to install the specified gems to. This defaults to Rubygems' - setting. Bundler shares this location with Rubygems, `gem install ...` will - have gem installed there, too. Therefore, gems installed without a - `--path ...` setting will show up by calling `gem list`. Accordingly, gems - installed to other locations will not get listed. - - This option is deprecated in favor of the `path` setting. - -* `--quiet`: - Do not print progress information to the standard output. Instead, Bundler - will exit using a status code (`$?`). - -* `--retry=[<number>]`: - Retry failed network or git requests for <number> times. - -* `--shebang=<ruby-executable>`: - Uses the specified ruby executable (usually `ruby`) to execute the scripts - created with `--binstubs`. In addition, if you use `--binstubs` together with - `--shebang jruby` these executables will be changed to execute `jruby` - instead. - - This option is deprecated in favor of the `shebang` setting. - -* `--standalone[=<list>]`: - Makes a bundle that can work without depending on Rubygems or Bundler at - runtime. A space separated list of groups to install has to be specified. - Bundler creates a directory named `bundle` and installs the bundle there. It - also generates a `bundle/bundler/setup.rb` file to replace Bundler's own setup - in the manner required. Using this option implicitly sets `path`, which is a - [remembered option][REMEMBERED OPTIONS]. - -* `--system`: - Installs the gems specified in the bundle to the system's Rubygems location. - This overrides any previous configuration of `--path`. - - This option is deprecated in favor of the `system` setting. - -* `--trust-policy=[<policy>]`: - Apply the Rubygems security policy <policy>, where policy is one of - `HighSecurity`, `MediumSecurity`, `LowSecurity`, `AlmostNoSecurity`, or - `NoSecurity`. For more details, please see the Rubygems signing documentation - linked below in [SEE ALSO][]. - -* `--with=<list>`: - A space-separated list of groups referencing gems to install. If an - optional group is given it is installed. If a group is given that is - in the remembered list of groups given to --without, it is removed - from that list. - - This option is deprecated in favor of the `with` setting. - -* `--without=<list>`: - A space-separated list of groups referencing gems to skip during installation. - If a group is given that is in the remembered list of groups given - to --with, it is removed from that list. - - This option is deprecated in favor of the `without` setting. - -## DEPLOYMENT MODE - -Bundler's defaults are optimized for development. To switch to -defaults optimized for deployment and for CI, use the `--deployment` -flag. Do not activate deployment mode on development machines, as it -will cause an error when the Gemfile(5) is modified. - -1. A `Gemfile.lock` is required. - - To ensure that the same versions of the gems you developed with - and tested with are also used in deployments, a `Gemfile.lock` - is required. - - This is mainly to ensure that you remember to check your - `Gemfile.lock` into version control. - -2. The `Gemfile.lock` must be up to date - - In development, you can modify your Gemfile(5) and re-run - `bundle install` to [conservatively update][CONSERVATIVE UPDATING] - your `Gemfile.lock` snapshot. - - In deployment, your `Gemfile.lock` should be up-to-date with - changes made in your Gemfile(5). - -3. Gems are installed to `vendor/bundle` not your default system location - - In development, it's convenient to share the gems used in your - application with other applications and other scripts that run on - the system. - - In deployment, isolation is a more important default. In addition, - the user deploying the application may not have permission to install - gems to the system, or the web server may not have permission to - read them. - - As a result, `bundle install --deployment` installs gems to - the `vendor/bundle` directory in the application. This may be - overridden using the `--path` option. - -## SUDO USAGE - -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 -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 system location. - -From your perspective, this is identical to installing the gems -directly into the system. - -You should never use `sudo bundle install`. This is because several -other steps in `bundle install` must be performed as the current user: - -* Updating your `Gemfile.lock` -* Updating your `vendor/cache`, if necessary -* Checking out private git repositories using your user's SSH keys - -Of these three, the first two could theoretically be performed by -`chown`ing the resulting files to `$SUDO_USER`. The third, however, -can only be performed by invoking the `git` command as -the current user. Therefore, git gems are downloaded and installed -into `~/.bundle` rather than $GEM_HOME or $BUNDLE_PATH. - -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 their final location. - -## INSTALLING GROUPS - -By default, `bundle install` will install all gems in all groups -in your Gemfile(5), except those declared for a different platform. - -However, you can explicitly tell Bundler to skip installing -certain groups with the `--without` option. This option takes -a space-separated list of groups. - -While the `--without` option will skip _installing_ the gems in the -specified groups, it will still _download_ those gems and use them to -resolve the dependencies of every gem in your Gemfile(5). - -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 that you have already developed and tested against. - -`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 production. You can choose -to exclude some of that code in different environments, but you -will never be caught flat-footed by different versions of -third-party code being used in different environments.` - -For a simple illustration, consider the following Gemfile(5): - - source 'https://rubygems.org' - - gem 'sinatra' - - group :production do - gem 'rack-perftools-profiler' - end - -In this case, `sinatra` depends on any version of Rack (`>= 1.0`), while -`rack-perftools-profiler` depends on 1.x (`~> 1.0`). - -When you run `bundle install --without production` in development, we -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 -APIs unavailable in Rack 1.x, only to have Bundler switch to Rack 1.2 -when the `production` group _is_ used. - -This should not cause any problems in practice, because we do not -attempt to `install` the gems in the excluded groups, and only evaluate -as part of the dependency resolution process. - -This also means that you cannot include different versions of the same -gem in different groups, because doing so would result in different -sets of dependencies used in development and production. Because of -the vagaries of the dependency resolution process, this usually -affects more than the gems you list in your Gemfile(5), and can -(surprisingly) radically change the gems you are using. - -## THE GEMFILE.LOCK - -When you run `bundle install`, Bundler will persist the full names -and versions of all gems that you used (including dependencies of -the gems specified in the Gemfile(5)) into a file called `Gemfile.lock`. - -Bundler uses this file in all subsequent calls to `bundle install`, -which guarantees that you always use the same exact code, even -as your application moves across machines. - -Because of the way dependency resolution works, even a -seemingly small change (for instance, an update to a point-release -of a dependency of a gem in your Gemfile(5)) can result in radically -different gems being needed to satisfy all dependencies. - -As a result, you `SHOULD` check your `Gemfile.lock` into version -control, in both applications and gems. If you do not, every machine that -checks out your repository (including your production server) will resolve all -dependencies again, which will result in different versions of -third-party code being used if `any` of the gems in the Gemfile(5) -or any of their dependencies have been updated. - -When Bundler first shipped, the `Gemfile.lock` was included in the `.gitignore` -file included with generated gems. Over time, however, it became clear that -this practice forces the pain of broken dependencies onto new contributors, -while leaving existing contributors potentially unaware of the problem. Since -`bundle install` is usually the first step towards a contribution, the pain of -broken dependencies would discourage new contributors from contributing. As a -result, we have revised our guidance for gem authors to now recommend checking -in the lock for gems. - -## CONSERVATIVE UPDATING - -When you make a change to the Gemfile(5) and then run `bundle install`, -Bundler will update only the gems that you modified. - -In other words, if a gem that you `did not modify` worked before -you called `bundle install`, it will continue to use the exact -same versions of all dependencies as it used before the update. - -Let's take a look at an example. Here's your original Gemfile(5): - - source 'https://rubygems.org' - - gem 'actionpack', '2.3.8' - gem 'activemerchant' - -In this case, both `actionpack` and `activemerchant` depend on -`activesupport`. The `actionpack` gem depends on `activesupport 2.3.8` -and `rack ~> 1.1.0`, while the `activemerchant` gem depends on -`activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`. - -When the dependencies are first resolved, Bundler will select -`activesupport 2.3.8`, which satisfies the requirements of both -gems in your Gemfile(5). - -Next, you modify your Gemfile(5) to: - - source 'https://rubygems.org' - - gem 'actionpack', '3.0.0.rc' - gem 'activemerchant' - -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` dependency to `~> 1.2.1`. - -When you run `bundle install`, Bundler notices that you changed -the `actionpack` gem, but not the `activemerchant` gem. It -evaluates the gems currently being used to satisfy its requirements: - - * `activesupport 2.3.8`: - also used to satisfy a dependency in `activemerchant`, - which is not being updated - * `rack ~> 1.1.0`: - not currently being used to satisfy another dependency - -Because you did not explicitly ask to update `activemerchant`, -you would not expect it to suddenly stop working after updating -`actionpack`. However, satisfying the new `activesupport 3.0.0.rc` -dependency of actionpack requires updating one of its dependencies. - -Even though `activemerchant` declares a very loose dependency -that theoretically matches `activesupport 3.0.0.rc`, Bundler treats -gems in your Gemfile(5) that have not changed as an atomic unit -together with their dependencies. In this case, the `activemerchant` -dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`, -so `bundle install` will report that it cannot update `actionpack`. - -To explicitly update `actionpack`, including its dependencies -which other gems in the Gemfile(5) still depend on, run -`bundle update actionpack` (see `bundle update(1)`). - -`Summary`: In general, after making a change to the Gemfile(5) , you -should first try to run `bundle install`, which will guarantee that no -other gem in the Gemfile(5) is impacted by the change. If that -does not work, run [bundle update(1)](bundle-update.1.html). - -## SEE ALSO - -* [Gem install docs](http://guides.rubygems.org/rubygems-basics/#installing-gems) -* [Rubygems signing docs](http://guides.rubygems.org/security/) diff --git a/man/bundle-list.1 b/man/bundle-list.1 index ebedb62b38..d758e61a49 100644 --- a/man/bundle-list.1 +++ b/man/bundle-list.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-LIST" "1" "October 2020" "" "" +.TH "BUNDLE\-LIST" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-list\fR \- List all the gems in the bundle diff --git a/man/bundle-list.1.ronn b/man/bundle-list.1.ronn deleted file mode 100644 index dc058ecd5f..0000000000 --- a/man/bundle-list.1.ronn +++ /dev/null @@ -1,33 +0,0 @@ -bundle-list(1) -- List all the gems in the bundle -========================================================================= - -## SYNOPSIS - -`bundle list` [--name-only] [--paths] [--without-group=GROUP[ GROUP...]] [--only-group=GROUP[ GROUP...]] - -## DESCRIPTION - -Prints a list of all the gems in the bundle including their version. - -Example: - -bundle list --name-only - -bundle list --paths - -bundle list --without-group test - -bundle list --only-group dev - -bundle list --only-group dev test --paths - -## OPTIONS - -* `--name-only`: - Print only the name of each gem. -* `--paths`: - Print the path to each gem in the bundle. -* `--without-group=<list>`: - A space-separated list of groups of gems to skip during printing. -* `--only-group=<list>`: - A space-separated list of groups of gems to print. diff --git a/man/bundle-lock.1 b/man/bundle-lock.1 index 350f1b3daa..a70043df00 100644 --- a/man/bundle-lock.1 +++ b/man/bundle-lock.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-LOCK" "1" "October 2020" "" "" +.TH "BUNDLE\-LOCK" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-lock\fR \- Creates / Updates a lockfile without installing diff --git a/man/bundle-lock.1.ronn b/man/bundle-lock.1.ronn deleted file mode 100644 index 3aa5920f5a..0000000000 --- a/man/bundle-lock.1.ronn +++ /dev/null @@ -1,94 +0,0 @@ -bundle-lock(1) -- Creates / Updates a lockfile without installing -================================================================= - -## SYNOPSIS - -`bundle lock` [--update] - [--local] - [--print] - [--lockfile=PATH] - [--full-index] - [--add-platform] - [--remove-platform] - [--patch] - [--minor] - [--major] - [--strict] - [--conservative] - -## DESCRIPTION - -Lock the gems specified in Gemfile. - -## OPTIONS - -* `--update=<*gems>`: - Ignores the existing lockfile. Resolve then updates lockfile. Taking a list - of gems or updating all gems if no list is given. - -* `--local`: - Do not attempt to connect to `rubygems.org`. Instead, Bundler will use the - gems already present in Rubygems' cache or in `vendor/cache`. Note that if a - appropriate platform-specific gem exists on `rubygems.org` it will not be - found. - -* `--print`: - Prints the lockfile to STDOUT instead of writing to the file system. - -* `--lockfile=<path>`: - The path where the lockfile should be written to. - -* `--full-index`: - Fall back to using the single-file index of all gems. - -* `--add-platform`: - Add a new platform to the lockfile, re-resolving for the addition of that - platform. - -* `--remove-platform`: - Remove a platform from the lockfile. - -* `--patch`: - If updating, prefer updating only to next patch version. - -* `--minor`: - If updating, prefer updating only to next minor version. - -* `--major`: - If updating, prefer updating to next major version (default). - -* `--strict`: - If updating, do not allow any gem to be updated past latest --patch | --minor | --major. - -* `--conservative`: - If updating, use bundle install conservative update behavior and do not allow shared dependencies to be updated. - -## UPDATING ALL GEMS - -If you run `bundle lock` with `--update` option without list of gems, bundler will -ignore any previously installed gems and resolve all dependencies again based -on the latest versions of all gems available in the sources. - -## UPDATING A LIST OF GEMS - -Sometimes, you want to update a single gem in the Gemfile(5), and leave the rest of -the gems that you specified locked to the versions in the `Gemfile.lock`. - -For instance, you only want to update `nokogiri`, run `bundle lock --update nokogiri`. - -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 `Gemfile.lock`. - -## SUPPORTING OTHER PLATFORMS - -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 PLATFORM to -the lockfile, force bundler to re-resolve and consider the new platform when -picking gems, all without needing to have a machine that matches PLATFORM handy -to install those platform-specific gems on. - -For a full explanation of gem platforms, see `gem help platform`. - -## PATCH LEVEL OPTIONS - -See [bundle update(1)](bundle-update.1.html) for details. diff --git a/man/bundle-open.1 b/man/bundle-open.1 index 9986d5004c..631280c969 100644 --- a/man/bundle-open.1 +++ b/man/bundle-open.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-OPEN" "1" "October 2020" "" "" +.TH "BUNDLE\-OPEN" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-open\fR \- Opens the source directory for a gem in your bundle diff --git a/man/bundle-open.1.ronn b/man/bundle-open.1.ronn deleted file mode 100644 index 497beac93f..0000000000 --- a/man/bundle-open.1.ronn +++ /dev/null @@ -1,19 +0,0 @@ -bundle-open(1) -- Opens the source directory for a gem in your bundle -===================================================================== - -## SYNOPSIS - -`bundle open` [GEM] - -## DESCRIPTION - -Opens the source directory of the provided GEM in your editor. - -For this to work the `EDITOR` or `BUNDLER_EDITOR` environment variable has to -be set. - -Example: - - bundle open 'rack' - -Will open the source directory for the 'rack' gem in your bundle. diff --git a/man/bundle-outdated.1 b/man/bundle-outdated.1 index 3fc3cdc601..66cfe1a5f7 100644 --- a/man/bundle-outdated.1 +++ b/man/bundle-outdated.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-OUTDATED" "1" "October 2020" "" "" +.TH "BUNDLE\-OUTDATED" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-outdated\fR \- List installed gems with newer versions available diff --git a/man/bundle-outdated.1.ronn b/man/bundle-outdated.1.ronn deleted file mode 100644 index a991d23789..0000000000 --- a/man/bundle-outdated.1.ronn +++ /dev/null @@ -1,111 +0,0 @@ -bundle-outdated(1) -- List installed gems with newer versions available -======================================================================= - -## SYNOPSIS - -`bundle outdated` [GEM] [--local] - [--pre] - [--source] - [--strict] - [--parseable | --porcelain] - [--group=GROUP] - [--groups] - [--update-strict] - [--patch|--minor|--major] - [--filter-major] - [--filter-minor] - [--filter-patch] - [--only-explicit] - -## DESCRIPTION - -Outdated lists the names and versions of gems that have a newer version available -in the given source. Calling outdated with [GEM [GEM]] will only check for newer -versions of the given gems. Prerelease gems are ignored by default. If your gems -are up to date, Bundler will exit with a status of 0. Otherwise, it will exit 1. - -## OPTIONS - -* `--local`: - Do not attempt to fetch gems remotely and use the gem cache instead. - -* `--pre`: - Check for newer pre-release gems. - -* `--source`: - Check against a specific source. - -* `--strict`: - Only list newer versions allowed by your Gemfile requirements. - -* `--parseable`, `--porcelain`: - Use minimal formatting for more parseable output. - -* `--group`: - List gems from a specific group. - -* `--groups`: - List gems organized by groups. - -* `--update-strict`: - Strict conservative resolution, do not allow any gem to be updated past latest --patch | --minor| --major. - -* `--minor`: - Prefer updating only to next minor version. - -* `--major`: - Prefer updating to next major version (default). - -* `--patch`: - Prefer updating only to next patch version. - -* `--filter-major`: - Only list major newer versions. - -* `--filter-minor`: - Only list minor newer versions. - -* `--filter-patch`: - Only list patch newer versions. - -* `--only-explicit`: - Only list gems specified in your Gemfile, not their dependencies. - -## PATCH LEVEL OPTIONS - -See [bundle update(1)](bundle-update.1.html) for details. - -One difference between the patch level options in `bundle update` and here is the `--strict` option. -`--strict` was already an option on outdated before the patch level options were added. `--strict` -wasn't altered, and the `--update-strict` option on `outdated` reflects what `--strict` does on -`bundle update`. - -## FILTERING OUTPUT - -The 3 filtering options do not affect the resolution of versions, merely what versions are shown -in the output. - -If the regular output shows the following: - - * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test" - * hashie (newest 3.4.6, installed 1.2.0, requested = 1.2.0) in groups "default" - * headless (newest 2.3.1, installed 2.2.3) in groups "test" - -`--filter-major` would only show: - - * hashie (newest 3.4.6, installed 1.2.0, requested = 1.2.0) in groups "default" - -`--filter-minor` would only show: - - * headless (newest 2.3.1, installed 2.2.3) in groups "test" - -`--filter-patch` would only show: - - * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test" - -Filter options can be combined. `--filter-minor` and `--filter-patch` would show: - - * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test" - * headless (newest 2.3.1, installed 2.2.3) in groups "test" - -Combining all three `filter` options would be the same result as providing none of them. diff --git a/man/bundle-platform.1 b/man/bundle-platform.1 index b4c521e0c1..9fda7cb92c 100644 --- a/man/bundle-platform.1 +++ b/man/bundle-platform.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-PLATFORM" "1" "October 2020" "" "" +.TH "BUNDLE\-PLATFORM" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-platform\fR \- Displays platform compatibility information diff --git a/man/bundle-platform.1.ronn b/man/bundle-platform.1.ronn deleted file mode 100644 index b5d3283fb6..0000000000 --- a/man/bundle-platform.1.ronn +++ /dev/null @@ -1,42 +0,0 @@ -bundle-platform(1) -- Displays platform compatibility information -================================================================= - -## SYNOPSIS - -`bundle platform` [--ruby] - -## DESCRIPTION - -`platform` will display information from your Gemfile, Gemfile.lock, and Ruby -VM about your platform. - -For instance, using this Gemfile(5): - - source "https://rubygems.org" - - ruby "1.9.3" - - gem "rack" - -If you run `bundle platform` on Ruby 1.9.3, it will display the following output: - - Your platform is: x86_64-linux - - Your app has gems that work on these platforms: - * ruby - - Your Gemfile specifies a Ruby version requirement: - * ruby 1.9.3 - - Your current platform satisfies the Ruby version requirement. - -`platform` will list all the platforms in your `Gemfile.lock` as well as the -`ruby` directive if applicable from your Gemfile(5). It will also let you know -if the `ruby` directive requirement has been met. If `ruby` directive doesn't -match the running Ruby VM, it will tell you what part does not. - -## OPTIONS - -* `--ruby`: - It will display the ruby directive information, so you don't have to - parse it from the Gemfile(5). diff --git a/man/bundle-pristine.1 b/man/bundle-pristine.1 index 0a1790655e..4561081746 100644 --- a/man/bundle-pristine.1 +++ b/man/bundle-pristine.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-PRISTINE" "1" "October 2020" "" "" +.TH "BUNDLE\-PRISTINE" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-pristine\fR \- Restores installed gems to their pristine condition diff --git a/man/bundle-pristine.1.ronn b/man/bundle-pristine.1.ronn deleted file mode 100644 index e2d6b6a348..0000000000 --- a/man/bundle-pristine.1.ronn +++ /dev/null @@ -1,34 +0,0 @@ -bundle-pristine(1) -- Restores installed gems to their pristine condition -=========================================================================== - -## SYNOPSIS - -`bundle pristine` - -## DESCRIPTION - -`pristine` restores the installed gems in the bundle to their pristine condition -using the local gem cache from RubyGems. For git gems, a forced checkout will be performed. - -For further explanation, `bundle pristine` ignores unpacked files on disk. In other -words, this command utilizes the local `.gem` cache or the gem's git repository -as if one were installing from scratch. - -Note: the Bundler gem cannot be restored to its original state with `pristine`. -One also cannot use `bundle pristine` on gems with a 'path' option in the Gemfile, -because bundler has no original copy it can restore from. - -When is it practical to use `bundle pristine`? - -It comes in handy when a developer is debugging a gem. `bundle pristine` is a -great way to get rid of experimental changes to a gem that one may not want. - -Why use `bundle pristine` over `gem pristine --all`? - -Both commands are very similar. -For context: `bundle pristine`, without arguments, cleans all gems from the lockfile. -Meanwhile, `gem pristine --all` cleans all installed gems for that Ruby version. - -If a developer forgets which gems in their project they might -have been debugging, the Rubygems `gem pristine [GEMNAME]` command may be inconvenient. -One can avoid waiting for `gem pristine --all`, and instead run `bundle pristine`. diff --git a/man/bundle-remove.1 b/man/bundle-remove.1 index ee24f676a6..b649f62673 100644 --- a/man/bundle-remove.1 +++ b/man/bundle-remove.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-REMOVE" "1" "October 2020" "" "" +.TH "BUNDLE\-REMOVE" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-remove\fR \- Removes gems from the Gemfile diff --git a/man/bundle-remove.1.ronn b/man/bundle-remove.1.ronn deleted file mode 100644 index 40a239b4a2..0000000000 --- a/man/bundle-remove.1.ronn +++ /dev/null @@ -1,23 +0,0 @@ -bundle-remove(1) -- Removes gems from the Gemfile -=========================================================================== - -## SYNOPSIS - -`bundle remove [GEM [GEM ...]] [--install]` - -## DESCRIPTION - -Removes the given gems from the Gemfile while ensuring that the resulting Gemfile is still valid. If a gem cannot be removed, a warning is printed. If a gem is already absent from the Gemfile, and error is raised. - -## OPTIONS - -* `--install`: - Runs `bundle install` after the given gems have been removed from the Gemfile, which ensures that both the lockfile and the installed gems on disk are also updated to remove the given gem(s). - -Example: - -bundle remove rails - -bundle remove rails rack - -bundle remove rails rack --install diff --git a/man/bundle-show.1 b/man/bundle-show.1 index f83c810ffe..1b0608f75a 100644 --- a/man/bundle-show.1 +++ b/man/bundle-show.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-SHOW" "1" "October 2020" "" "" +.TH "BUNDLE\-SHOW" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-show\fR \- Shows all the gems in your bundle, or the path to a gem diff --git a/man/bundle-show.1.ronn b/man/bundle-show.1.ronn deleted file mode 100644 index a6a59a1445..0000000000 --- a/man/bundle-show.1.ronn +++ /dev/null @@ -1,21 +0,0 @@ -bundle-show(1) -- Shows all the gems in your bundle, or the path to a gem -========================================================================= - -## SYNOPSIS - -`bundle show` [GEM] - [--paths] - -## DESCRIPTION - -Without the [GEM] option, `show` will print a list of the names and versions of -all gems that are required by your [`Gemfile(5)`][Gemfile(5)], sorted by name. - -Calling show with [GEM] will list the exact location of that gem on your -machine. - -## OPTIONS - -* `--paths`: - List the paths of all gems that are required by your [`Gemfile(5)`][Gemfile(5)], - sorted by gem name. diff --git a/man/bundle-update.1 b/man/bundle-update.1 index 002f2e69b9..f9922f6618 100644 --- a/man/bundle-update.1 +++ b/man/bundle-update.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-UPDATE" "1" "October 2020" "" "" +.TH "BUNDLE\-UPDATE" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-update\fR \- Update your gems to the latest available versions diff --git a/man/bundle-update.1.ronn b/man/bundle-update.1.ronn deleted file mode 100644 index 397fecadcb..0000000000 --- a/man/bundle-update.1.ronn +++ /dev/null @@ -1,350 +0,0 @@ -bundle-update(1) -- Update your gems to the latest available versions -===================================================================== - -## SYNOPSIS - -`bundle update` <*gems> [--all] - [--group=NAME] - [--source=NAME] - [--local] - [--ruby] - [--bundler[=VERSION]] - [--full-index] - [--jobs=JOBS] - [--quiet] - [--patch|--minor|--major] - [--redownload] - [--strict] - [--conservative] - -## DESCRIPTION - -Update the gems specified (all gems, if `--all` flag is used), ignoring -the previously installed gems specified in the `Gemfile.lock`. In -general, you should use [bundle install(1)](bundle-install.1.html) to install the same exact -gems and versions across machines. - -You would use `bundle update` to explicitly update the version of a -gem. - -## OPTIONS - -* `--all`: - Update all gems specified in Gemfile. - -* `--group=<name>`, `-g=[<name>]`: - Only update the gems in the specified group. For instance, you can update all gems - in the development group with `bundle update --group development`. You can also - call `bundle update rails --group test` to update the rails gem and all gems in - the test group, for example. - -* `--source=<name>`: - The name of a `:git` or `:path` source used in the Gemfile(5). For - instance, with a `:git` source of `http://github.com/rails/rails.git`, - you would call `bundle update --source rails` - -* `--local`: - Do not attempt to fetch gems remotely and use the gem cache instead. - -* `--ruby`: - Update the locked version of Ruby to the current version of Ruby. - -* `--bundler`: - Update the locked version of bundler to the invoked bundler version. - -* `--full-index`: - Fall back to using the single-file index of all gems. - -* `--jobs=[<number>]`, `-j[<number>]`: - Specify the number of jobs to run in parallel. The default is `1`. - -* `--retry=[<number>]`: - Retry failed network or git requests for <number> times. - -* `--quiet`: - Only output warnings and errors. - -* `--redownload`: - Force downloading every gem. - -* `--patch`: - Prefer updating only to next patch version. - -* `--minor`: - Prefer updating only to next minor version. - -* `--major`: - Prefer updating to next major version (default). - -* `--strict`: - Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`. - -* `--conservative`: - Use bundle install conservative update behavior and do not allow shared dependencies to be updated. - -## UPDATING ALL GEMS - -If you run `bundle update --all`, bundler will ignore -any previously installed gems and resolve all dependencies again -based on the latest versions of all gems available in the sources. - -Consider the following Gemfile(5): - - source "https://rubygems.org" - - gem "rails", "3.0.0.rc" - gem "nokogiri" - -When you run [bundle install(1)](bundle-install.1.html) the first time, bundler will resolve -all of the dependencies, all the way down, and install what you need: - - Fetching gem metadata from https://rubygems.org/......... - Resolving dependencies... - Installing builder 2.1.2 - Installing abstract 1.0.0 - Installing rack 1.2.8 - Using bundler 1.7.6 - Installing rake 10.4.0 - Installing polyglot 0.3.5 - Installing mime-types 1.25.1 - Installing i18n 0.4.2 - Installing mini_portile 0.6.1 - Installing tzinfo 0.3.42 - Installing rack-mount 0.6.14 - Installing rack-test 0.5.7 - Installing treetop 1.4.15 - Installing thor 0.14.6 - Installing activesupport 3.0.0.rc - Installing erubis 2.6.6 - Installing activemodel 3.0.0.rc - Installing arel 0.4.0 - Installing mail 2.2.20 - Installing activeresource 3.0.0.rc - Installing actionpack 3.0.0.rc - Installing activerecord 3.0.0.rc - Installing actionmailer 3.0.0.rc - Installing railties 3.0.0.rc - Installing rails 3.0.0.rc - Installing nokogiri 1.6.5 - - Bundle complete! 2 Gemfile dependencies, 26 gems total. - Use `bundle show [gemname]` to see where a bundled gem is installed. - -As you can see, even though you have two gems in the Gemfile(5), your application -needs 26 different gems in order to run. Bundler remembers the exact versions -it installed in `Gemfile.lock`. The next time you run [bundle install(1)](bundle-install.1.html), bundler skips -the dependency resolution and installs the same gems as it installed last time. - -After checking in the `Gemfile.lock` into version control and cloning it on another -machine, running [bundle install(1)](bundle-install.1.html) will _still_ install the gems that you installed -last time. You don't need to worry that a new release of `erubis` or `mail` changes -the gems you use. - -However, from time to time, you might want to update the gems you are using to the -newest versions that still match the gems in your Gemfile(5). - -To do this, run `bundle update --all`, which will ignore the `Gemfile.lock`, and resolve -all the dependencies again. Keep in mind that this process can result in a significantly -different set of the 25 gems, based on the requirements of new gems that the gem -authors released since the last time you ran `bundle update --all`. - -## UPDATING A LIST OF GEMS - -Sometimes, you want to update a single gem in the Gemfile(5), and leave the rest of the -gems that you specified locked to the versions in the `Gemfile.lock`. - -For instance, in the scenario above, imagine that `nokogiri` releases version `1.4.4`, and -you want to update it _without_ updating Rails and all of its dependencies. To do this, -run `bundle update nokogiri`. - -Bundler will update `nokogiri` and any of its dependencies, but leave alone Rails and -its dependencies. - -## OVERLAPPING DEPENDENCIES - -Sometimes, multiple gems declared in your Gemfile(5) are satisfied by the same -second-level dependency. For instance, consider the case of `thin` and -`rack-perftools-profiler`. - - source "https://rubygems.org" - - gem "thin" - gem "rack-perftools-profiler" - -The `thin` gem depends on `rack >= 1.0`, while `rack-perftools-profiler` depends -on `rack ~> 1.0`. If you run bundle install, you get: - - Fetching source index for https://rubygems.org/ - Installing daemons (1.1.0) - Installing eventmachine (0.12.10) with native extensions - Installing open4 (1.0.1) - Installing perftools.rb (0.4.7) with native extensions - Installing rack (1.2.1) - Installing rack-perftools_profiler (0.0.2) - Installing thin (1.2.7) with native extensions - Using bundler (1.0.0.rc.3) - -In this case, the two gems have their own set of dependencies, but they share -`rack` in common. If you run `bundle update thin`, bundler will update `daemons`, -`eventmachine` and `rack`, which are dependencies of `thin`, but not `open4` or -`perftools.rb`, which are dependencies of `rack-perftools_profiler`. Note that -`bundle update thin` will update `rack` even though it's _also_ a dependency of -`rack-perftools_profiler`. - -In short, by default, when you update a gem using `bundle update`, bundler will -update all dependencies of that gem, including those that are also dependencies -of another gem. - -To prevent updating shared dependencies, prior to version 1.14 the only option -was the `CONSERVATIVE UPDATING` behavior in [bundle install(1)](bundle-install.1.html): - -In this scenario, updating the `thin` version manually in the Gemfile(5), -and then running [bundle install(1)](bundle-install.1.html) will only update `daemons` and `eventmachine`, -but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section -of [bundle install(1)](bundle-install.1.html). - -Starting with 1.14, specifying the `--conservative` option will also prevent shared -dependencies from being updated. - -## PATCH LEVEL OPTIONS - -Version 1.14 introduced 4 patch-level options that will influence how gem -versions are resolved. One of the following options can be used: `--patch`, -`--minor` or `--major`. `--strict` can be added to further influence resolution. - -* `--patch`: - Prefer updating only to next patch version. - -* `--minor`: - Prefer updating only to next minor version. - -* `--major`: - Prefer updating to next major version (default). - -* `--strict`: - Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`. - -When Bundler is resolving what versions to use to satisfy declared -requirements in the Gemfile or in parent gems, it looks up all -available versions, filters out any versions that don't satisfy -the requirement, and then, by default, sorts them from newest to -oldest, considering them in that order. - -Providing one of the patch level options (e.g. `--patch`) changes the -sort order of the satisfying versions, causing Bundler to consider the -latest `--patch` or `--minor` version available before other versions. -Note that versions outside the stated patch level could still be -resolved to if necessary to find a suitable dependency graph. - -For example, if gem 'foo' is locked at 1.0.2, with no gem requirement -defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0 -all exist, the default order of preference by default (`--major`) will -be "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2". - -If the `--patch` option is used, the order of preference will change to -"1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0". - -If the `--minor` option is used, the order of preference will change to -"1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0". - -Combining the `--strict` option with any of the patch level options -will remove any versions beyond the scope of the patch level option, -to ensure that no gem is updated that far. - -To continue the previous example, if both `--patch` and `--strict` -options are used, the available versions for resolution would be -"1.0.4, 1.0.3, 1.0.2". If `--minor` and `--strict` are used, it would -be "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2". - -Gem requirements as defined in the Gemfile will still be the first -determining factor for what versions are available. If the gem -requirement for `foo` in the Gemfile is '~> 1.0', that will accomplish -the same thing as providing the `--minor` and `--strict` options. - -## PATCH LEVEL EXAMPLES - -Given the following gem specifications: - - foo 1.4.3, requires: ~> bar 2.0 - foo 1.4.4, requires: ~> bar 2.0 - foo 1.4.5, requires: ~> bar 2.1 - foo 1.5.0, requires: ~> bar 2.1 - foo 1.5.1, requires: ~> bar 3.0 - bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0 - -Gemfile: - - gem 'foo' - -Gemfile.lock: - - foo (1.4.3) - bar (~> 2.0) - bar (2.0.3) - -Cases: - - # Command Line Result - ------------------------------------------------------------ - 1 bundle update --patch 'foo 1.4.5', 'bar 2.1.1' - 2 bundle update --patch foo 'foo 1.4.5', 'bar 2.1.1' - 3 bundle update --minor 'foo 1.5.1', 'bar 3.0.0' - 4 bundle update --minor --strict 'foo 1.5.0', 'bar 2.1.1' - 5 bundle update --patch --strict 'foo 1.4.4', 'bar 2.0.4' - -In case 1, bar is upgraded to 2.1.1, a minor version increase, because -the dependency from foo 1.4.5 required it. - -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. - -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 -of bar. - -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 -it's a major increment. - -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 -move is up to 1.4.4 and 2.0.4. - -## RECOMMENDED WORKFLOW - -In general, when working with an application managed with bundler, you should -use the following workflow: - -* After you create your Gemfile(5) for the first time, run - - $ bundle install - -* Check the resulting `Gemfile.lock` into version control - - $ git add Gemfile.lock - -* When checking out this repository on another development machine, run - - $ bundle install - -* When checking out this repository on a deployment machine, run - - $ bundle install --deployment - -* After changing the Gemfile(5) to reflect a new or update dependency, run - - $ bundle install - -* Make sure to check the updated `Gemfile.lock` into version control - - $ git add Gemfile.lock - -* If [bundle install(1)](bundle-install.1.html) reports a conflict, manually update the specific - gems that you changed in the Gemfile(5) - - $ bundle update rails thin - -* If you want to update all the gems to the latest possible versions that - still match the gems listed in the Gemfile(5), run - - $ bundle update --all diff --git a/man/bundle-viz.1 b/man/bundle-viz.1 index cb2fcde537..2f68f644bf 100644 --- a/man/bundle-viz.1 +++ b/man/bundle-viz.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE\-VIZ" "1" "October 2020" "" "" +.TH "BUNDLE\-VIZ" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\-viz\fR \- Generates a visual dependency graph for your Gemfile diff --git a/man/bundle-viz.1.ronn b/man/bundle-viz.1.ronn deleted file mode 100644 index 701df5415e..0000000000 --- a/man/bundle-viz.1.ronn +++ /dev/null @@ -1,30 +0,0 @@ -bundle-viz(1) -- Generates a visual dependency graph for your Gemfile -===================================================================== - -## SYNOPSIS - -`bundle viz` [--file=FILE] - [--format=FORMAT] - [--requirements] - [--version] - [--without=GROUP GROUP] - -## DESCRIPTION - -`viz` generates a PNG file of the current `Gemfile(5)` as a dependency graph. -`viz` requires the ruby-graphviz gem (and its dependencies). - -The associated gems must also be installed via [`bundle install(1)`](bundle-install.1.html). - -## OPTIONS - -* `--file`, `-f`: - The name to use for the generated file. See `--format` option -* `--format`, `-F`: - This is output format option. Supported format is png, jpg, svg, dot ... -* `--requirements`, `-R`: - Set to show the version of each required dependency. -* `--version`, `-v`: - Set to show each gem version. -* `--without`, `-W`: - Exclude gems that are part of the specified named group. diff --git a/man/bundle.1 b/man/bundle.1 index 86d0aec497..232752e914 100644 --- a/man/bundle.1 +++ b/man/bundle.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BUNDLE" "1" "October 2020" "" "" +.TH "BUNDLE" "1" "November 2020" "" "" . .SH "NAME" \fBbundle\fR \- Ruby Dependency Management diff --git a/man/bundle.1.ronn b/man/bundle.1.ronn deleted file mode 100644 index 5b1712394a..0000000000 --- a/man/bundle.1.ronn +++ /dev/null @@ -1,111 +0,0 @@ -bundle(1) -- Ruby Dependency Management -======================================= - -## SYNOPSIS - -`bundle` COMMAND [--no-color] [--verbose] [ARGS] - -## DESCRIPTION - -Bundler manages an `application's dependencies` through its entire life -across many machines systematically and repeatably. - -See [the bundler website](https://bundler.io) for information on getting -started, and Gemfile(5) for more information on the `Gemfile` format. - -## OPTIONS - -* `--no-color`: - Print all output without color - -* `--retry`, `-r`: - Specify the number of times you wish to attempt network commands - -* `--verbose`, `-V`: - Print out additional logging information - -## BUNDLE COMMANDS - -We divide `bundle` subcommands into primary commands and utilities: - -## PRIMARY COMMANDS - -* [`bundle install(1)`](bundle-install.1.html): - Install the gems specified by the `Gemfile` or `Gemfile.lock` - -* [`bundle update(1)`](bundle-update.1.html): - Update dependencies to their latest versions - -* [`bundle package(1)`](bundle-package.1.html): - Package the .gem files required by your application into the - `vendor/cache` directory - -* [`bundle exec(1)`](bundle-exec.1.html): - Execute a script in the current bundle - -* [`bundle config(1)`](bundle-config.1.html): - Specify and read configuration options for Bundler - -* `bundle help(1)`: - Display detailed help for each subcommand - -## UTILITIES - -* [`bundle add(1)`](bundle-add.1.html): - Add the named gem to the Gemfile and run `bundle install` - -* [`bundle binstubs(1)`](bundle-binstubs.1.html): - Generate binstubs for executables in a gem - -* [`bundle check(1)`](bundle-check.1.html): - Determine whether the requirements for your application are installed - and available to Bundler - -* [`bundle show(1)`](bundle-show.1.html): - Show the source location of a particular gem in the bundle - -* [`bundle outdated(1)`](bundle-outdated.1.html): - Show all of the outdated gems in the current bundle - -* `bundle console(1)`: - Start an IRB session in the current bundle - -* [`bundle open(1)`](bundle-open.1.html): - Open an installed gem in the editor - -* [`bundle lock(1)`](bundle-lock.1.html): - Generate a lockfile for your dependencies - -* [`bundle viz(1)`](bundle-viz.1.html): - Generate a visual representation of your dependencies - -* [`bundle init(1)`](bundle-init.1.html): - Generate a simple `Gemfile`, placed in the current directory - -* [`bundle gem(1)`](bundle-gem.1.html): - Create a simple gem, suitable for development with Bundler - -* [`bundle platform(1)`](bundle-platform.1.html): - Display platform compatibility information - -* [`bundle clean(1)`](bundle-clean.1.html): - Clean up unused gems in your Bundler directory - -* [`bundle doctor(1)`](bundle-doctor.1.html): - Display warnings about common problems - -* [`bundle remove(1)`](bundle-remove.1.html): - Removes gems from the Gemfile - -## PLUGINS - -When running a command that isn't listed in PRIMARY COMMANDS or UTILITIES, -Bundler will try to find an executable on your path named `bundler-<command>` -and execute it, passing down any extra arguments to it. - -## OBSOLETE - -These commands are obsolete and should no longer be used: - -* `bundle cache(1)` -* `bundle show(1)` diff --git a/man/gemfile.5 b/man/gemfile.5 index 401487c688..f501db2b66 100644 --- a/man/gemfile.5 +++ b/man/gemfile.5 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "GEMFILE" "5" "October 2020" "" "" +.TH "GEMFILE" "5" "November 2020" "" "" . .SH "NAME" \fBGemfile\fR \- A format for describing gem dependencies for Ruby programs diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn deleted file mode 100644 index 994f0d66bd..0000000000 --- a/man/gemfile.5.ronn +++ /dev/null @@ -1,517 +0,0 @@ -Gemfile(5) -- A format for describing gem dependencies for Ruby programs -======================================================================== - -## SYNOPSIS - -A `Gemfile` describes the gem dependencies required to execute associated -Ruby code. - -Place the `Gemfile` in the root of the directory containing the associated -code. For instance, in a Rails application, place the `Gemfile` in the same -directory as the `Rakefile`. - -## SYNTAX - -A `Gemfile` is evaluated as Ruby code, in a context which makes available -a number of methods used to describe the gem requirements. - -## GLOBAL SOURCES - -At the top of the `Gemfile`, add a line for the `Rubygems` source that contains -the gems listed in the `Gemfile`. - - source "https://rubygems.org" - -It is possible, but not recommended as of Bundler 1.7, to add multiple global -`source` lines. Each of these `source`s `MUST` be a valid Rubygems repository. - -Sources are checked for gems following the heuristics described in -[SOURCE PRIORITY][]. If a gem is found in more than one global source, Bundler -will print a warning after installing the gem indicating which source was used, -and listing the other sources where the gem is available. A specific source can -be selected for gems that need to use a non-standard repository, suppressing -this warning, by using the [`:source` option](#SOURCE) or a -[`source` block](#BLOCK-FORM-OF-SOURCE-GIT-PATH-GROUP-and-PLATFORMS). - -### CREDENTIALS - -Some gem sources require a username and password. Use [bundle config(1)](bundle-config.1.html) to set -the username and password for any of the sources that need it. The command must -be run once on each computer that will install the Gemfile, but this keeps the -credentials from being stored in plain text in version control. - - bundle config gems.example.com user:password - -For some sources, like a company Gemfury account, it may be easier to -include the credentials in the Gemfile as part of the source URL. - - source "https://user:password@gems.example.com" - -Credentials in the source URL will take precedence over credentials set using -`config`. - -## RUBY - -If your application requires a specific Ruby version or engine, specify your -requirements using the `ruby` method, with the following arguments. -All parameters are `OPTIONAL` unless otherwise specified. - -### VERSION (required) - -The version of Ruby that your application requires. If your application -requires an alternate Ruby engine, such as JRuby, Rubinius or TruffleRuby, this -should be the Ruby version that the engine is compatible with. - - ruby "1.9.3" - -### ENGINE - -Each application _may_ specify a Ruby engine. If an engine is specified, an -engine version _must_ also be specified. - -What exactly is an Engine? - - A Ruby engine is an implementation of the Ruby language. - - - For background: the reference or original implementation of the Ruby - programming language is called - [Matz's Ruby Interpreter](https://en.wikipedia.org/wiki/Ruby_MRI), or MRI - for short. This is named after Ruby creator Yukihiro Matsumoto, - also known as Matz. MRI is also known as CRuby, because it is written in C. - MRI is the most widely used Ruby engine. - - - [Other implementations](https://www.ruby-lang.org/en/about/) of Ruby exist. - Some of the more well-known implementations include - [Rubinius](https://rubinius.com/), and [JRuby](http://jruby.org/). - Rubinius is an alternative implementation of Ruby written in Ruby. - JRuby is an implementation of Ruby on the JVM, short for Java Virtual Machine. - -### ENGINE VERSION - -Each application _may_ specify a Ruby engine version. If an engine version is -specified, an engine _must_ also be specified. If the engine is "ruby" the -engine version specified _must_ match the Ruby version. - - ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7" - -### PATCHLEVEL - -Each application _may_ specify a Ruby patchlevel. - - ruby "2.0.0", :patchlevel => "247" - -## GEMS - -Specify gem requirements using the `gem` method, with the following arguments. -All parameters are `OPTIONAL` unless otherwise specified. - -### NAME (required) - -For each gem requirement, list a single _gem_ line. - - gem "nokogiri" - -### VERSION - -Each _gem_ `MAY` have one or more version specifiers. - - gem "nokogiri", ">= 1.4.2" - gem "RedCloth", ">= 4.1.0", "< 4.2.0" - -### REQUIRE AS - -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 the file -you want `required` has the same name as _gem_ or `false` to -prevent any file from being autorequired. - - gem "redis", :require => ["redis/connection/hiredis", "redis"] - gem "webmock", :require => false - gem "byebug", :require => true - -The argument defaults to the name of the gem. For example, these are identical: - - gem "nokogiri" - gem "nokogiri", :require => "nokogiri" - gem "nokogiri", :require => true - -### GROUPS - -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` group. - - gem "rspec", :group => :test - gem "wirble", :groups => [:development, :test] - -The Bundler runtime allows its two main methods, `Bundler.setup` and -`Bundler.require`, to limit their impact to particular groups. - - # setup adds gems to Ruby's load path - Bundler.setup # defaults to all groups - require "bundler/setup" # same as Bundler.setup - Bundler.setup(:default) # only set up the _default_ group - Bundler.setup(:test) # only set up the _test_ group (but `not` _default_) - Bundler.setup(:default, :test) # set up the _default_ and _test_ groups, but no others - - # require requires all of the gems in the specified groups - Bundler.require # defaults to the _default_ group - Bundler.require(:default) # identical - Bundler.require(:default, :test) # requires the _default_ and _test_ groups - Bundler.require(:test) # requires the _test_ group - -The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should -not install with the `without` configuration. - -To specify multiple groups to ignore, specify a list of groups separated by spaces. - - bundle config set --local without test - bundle config set --local without development test - -Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"` -will setup all groups except for the ones you excluded via `--without` (since they -are not available). - -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 and their dependencies. -This means that you cannot list different versions of the same gems in different -groups. For more details, see [Understanding Bundler](https://bundler.io/rationale.html). - -### PLATFORMS - -If a gem should only be used in a particular platform or set of platforms, you can -specify them. Platforms are essentially identical to groups, except that you do not -need to use the `--without` install-time flag to exclude groups of gems for other -platforms. - -There are a number of `Gemfile` platforms: - - * `ruby`: - C Ruby (MRI), Rubinius or TruffleRuby, but `NOT` Windows - * `mri`: - Same as _ruby_, but only C Ruby (MRI) - * `mingw`: - Windows 32 bit 'mingw32' platform (aka RubyInstaller) - * `x64_mingw`: - Windows 64 bit 'mingw32' platform (aka RubyInstaller x64) - * `rbx`: - Rubinius - * `jruby`: - JRuby - * `truffleruby`: - TruffleRuby - * `mswin`: - Windows - -You can restrict further by platform and version for all platforms *except* for -`rbx`, `jruby`, `truffleruby` and `mswin`. - -To specify a version in addition to a platform, append the version 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: - - ruby_23 - -The full list of platforms and supported versions includes: - - * `ruby`: - 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 - * `mri`: - 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 - * `mingw`: - 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 - * `x64_mingw`: - 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 - -As with groups, you can specify one or more platforms: - - gem "weakling", :platforms => :jruby - gem "ruby-debug", :platforms => :mri_18 - gem "nokogiri", :platforms => [:mri_18, :jruby] - -All operations involving groups ([`bundle install`](bundle-install.1.html), `Bundler.setup`, -`Bundler.require`) behave exactly the same as if any groups not -matching the current platform were explicitly excluded. - -### SOURCE - -You can select an alternate Rubygems repository for a gem using the ':source' -option. - - gem "some_internal_gem", :source => "https://gems.example.com" - -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 not exist in this source, -it will not be installed. - -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, it will fall -back on global sources using the ordering described in [SOURCE PRIORITY][]. - -Selecting a specific source repository this way also suppresses the ambiguous -gem warning described above in -[GLOBAL SOURCES (#source)](#GLOBAL-SOURCES). - -Using the `:source` option for an individual gem will also make that source -available as a possible global source for any other gems which do not specify -explicit sources. Thus, when adding gems with explicit sources, it is -recommended that you also ensure all other gems in the Gemfile are using -explicit sources. - -### GIT - -If necessary, you can specify that a gem is located at a particular -git repository using the `:git` parameter. The repository can be accessed via -several protocols: - - * `HTTP(S)`: - gem "rails", :git => "https://github.com/rails/rails.git" - * `SSH`: - gem "rails", :git => "git@github.com:rails/rails.git" - * `git`: - gem "rails", :git => "git://github.com/rails/rails.git" - -If using SSH, the user that you use to run `bundle install` `MUST` have the -appropriate keys available in their `$HOME/.ssh`. - -`NOTE`: `http://` and `git://` URLs should be avoided if at all possible. These -protocols are unauthenticated, so a man-in-the-middle attacker can deliver -malicious code and compromise your system. HTTPS and SSH are strongly -preferred. - -The `group`, `platforms`, and `require` options are available and behave -exactly the same as they would for a normal gem. - -A git repository `SHOULD` have at least one file, at the root of the -directory containing the gem, with the extension `.gemspec`. This file -`MUST` contain a valid gem specification, as expected by the `gem build` -command. - -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 extension compilation instructions. As a result, it may fail to properly -integrate into your application. - -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 -only valid if the `.gemspec` specifies a version matching the version -specifier. If not, bundler will print a warning. - - gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git" - # bundle install will fail, because the .gemspec in the rails - # repository's master branch specifies version 3.0.0 - -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 -version in the simple `.gemspec` it creates. - -Git repositories support a number of additional options. - - * `branch`, `tag`, and `ref`: - You `MUST` only specify at most one of these options. The default - is `:branch => "master"`. For example: - - gem "rails", :git => "https://github.com/rails/rails.git", :branch => "5-0-stable" - - gem "rails", :git => "https://github.com/rails/rails.git", :tag => "v5.0.0" - - gem "rails", :git => "https://github.com/rails/rails.git", :ref => "4aded" - - * `submodules`: - For reference, a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) - lets you have another git repository within a subfolder of your repository. - Specify `:submodules => true` to cause bundler to expand any - submodules included in the git repository - -If a git repository contains multiple `.gemspecs`, each `.gemspec` -represents a gem located at the same place in the file system as -the `.gemspec`. - - |~rails [git root] - | |-rails.gemspec [rails gem located here] - |~actionpack - | |-actionpack.gemspec [actionpack gem located here] - |~activesupport - | |-activesupport.gemspec [activesupport gem located here] - |... - -To install a gem located in a git repository, bundler changes to -the directory containing the gemspec, runs `gem build name.gemspec` -and then installs the resulting gem. The `gem build` command, -which comes standard with Rubygems, evaluates the `.gemspec` in -the context of the directory in which it is located. - -### GIT SOURCE - -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 argument and interpolates it into a -string to return the full repo address: - - git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" } - gem 'rails', :stash => 'forks/rails' - -In addition, if you wish to choose a specific branch: - - gem "rails", :stash => "forks/rails", :branch => "branch_name" - -### GITHUB - -`NOTE`: This shorthand should be avoided until Bundler 2.0, since it -currently expands to an insecure `git://` URL. This allows a -man-in-the-middle attacker to compromise your system. - -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 username and repository name (without the -trailing ".git"), separated by a slash. If both the username and repository name are the -same, you can omit one. - - gem "rails", :github => "rails/rails" - gem "rails", :github => "rails" - -Are both equivalent to - - gem "rails", :git => "git://github.com/rails/rails.git" - -Since the `github` method is a specialization of `git_source`, it accepts a `:branch` named argument. - -### GIST - -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 (without the trailing ".git"). - - gem "the_hatch", :gist => "4815162342" - -Is equivalent to: - - gem "the_hatch", :git => "https://gist.github.com/4815162342.git" - -Since the `gist` method is a specialization of `git_source`, it accepts a `:branch` named argument. - -### BITBUCKET - -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 username and repository name (without the -trailing ".git"), separated by a slash. If both the username and repository name are the -same, you can omit one. - - gem "rails", :bitbucket => "rails/rails" - gem "rails", :bitbucket => "rails" - -Are both equivalent to - - gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git" - -Since the `bitbucket` method is a specialization of `git_source`, it accepts a `:branch` named argument. - -### PATH - -You can specify that a gem is located in a particular location -on the file system. Relative paths are resolved relative to the -directory containing the `Gemfile`. - -Similar to the semantics of the `:git` option, the `:path` -option requires that the directory in question either contains -a `.gemspec` for the gem, or that you specify an explicit -version that bundler should use. - -Unlike `:git`, bundler does not compile C extensions for -gems specified as paths. - - gem "rails", :path => "vendor/rails" - -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 gem's files. This will automatically load gemspec files from subdirectories. - - path 'components' do - gem 'admin_ui' - gem 'public_ui' - end - -## BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS - -The `:source`, `:git`, `:path`, `:group`, and `:platforms` options may be -applied to a group of gems by using block form. - - source "https://gems.example.com" do - gem "some_internal_gem" - gem "another_internal_gem" - end - - git "https://github.com/rails/rails.git" do - gem "activesupport" - gem "actionpack" - end - - platforms :ruby do - gem "ruby-debug" - gem "sqlite3" - end - - group :development, :optional => true do - gem "wirble" - gem "faker" - end - -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` -option given to the `bundle install` command. - -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 the block will inherit those options. - -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 specify -explicit sources. Thus, when defining source blocks, it is -recommended that you also ensure all other gems in the Gemfile are using -explicit sources, either via source blocks or `:source` directives on -individual gems. - -## INSTALL_IF - -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 used if certain -software is installed or some other conditions are met. - - install_if -> { RUBY_PLATFORM =~ /darwin/ } do - gem "pasteboard" - end - -## GEMSPEC - -The [`.gemspec`](http://guides.rubygems.org/specification-reference/) file is where - you provide metadata about your gem to Rubygems. Some required Gemspec - attributes include the name, description, and homepage of your gem. This is - also where you specify the dependencies your gem needs to run. - -If you wish to use Bundler to help install dependencies for a gem while it is -being developed, use the `gemspec` method to pull in the dependencies listed in -the `.gemspec` file. - -The `gemspec` method adds any runtime dependencies as gem requirements in the -default group. It also adds development dependencies as gem requirements in the -`development` group. Finally, it adds a gem requirement on your project (`:path -=> '.'`). In conjunction with `Bundler.setup`, this allows you to require project -files in your test code as you would if the project were installed as a gem; you -need not manipulate the load path manually or require project files via relative -paths. - -The `gemspec` method supports optional `:path`, `:glob`, `:name`, and `:development_group` -options, which control where bundler looks for the `.gemspec`, the glob it uses to look -for the gemspec (defaults to: "{,*,*/*}.gemspec"), what named `.gemspec` it uses -(if more than one is present), and which group development dependencies are included in. - -When a `gemspec` dependency encounters version conflicts during resolution, the -local version under development will always be selected -- even if there are -remote versions that better match other requirements for the `gemspec` gem. - -## SOURCE PRIORITY - -When attempting to locate a gem to satisfy a gem requirement, -bundler uses the following priority order: - - 1. The source explicitly attached to the gem (using `:source`, `:path`, or - `:git`) - 2. For implicit gems (dependencies of explicit gems), any source, git, or path - repository declared on the parent. This results in bundler prioritizing the - ActiveSupport gem from the Rails git repository over ones from - `rubygems.org` - 3. The sources specified via global `source` lines, searching each source in - your `Gemfile` from last added to first added. |