From c405b80951202d1cb6085442df3a40c6e7b5771c Mon Sep 17 00:00:00 2001 From: Samuel Giddins Date: Sat, 12 Dec 2015 18:17:56 -0800 Subject: [PATCH 1/3] Add v1.11 --- source/shared/_whats_new.haml | 3 +- source/v1.11/bundle_binstubs.haml | 18 ++ source/v1.11/bundle_check.haml | 23 ++ source/v1.11/bundle_clean.haml | 16 ++ source/v1.11/bundle_config.haml | 275 +++++++++++++++++++ source/v1.11/bundle_console.haml | 15 + source/v1.11/bundle_exec.haml | 26 ++ source/v1.11/bundle_gem.haml | 38 +++ source/v1.11/bundle_help.haml | 10 + source/v1.11/bundle_init.haml | 17 ++ source/v1.11/bundle_inject.haml | 18 ++ source/v1.11/bundle_install.haml | 122 +++++++++ source/v1.11/bundle_open.haml | 12 + source/v1.11/bundle_outdated.haml | 23 ++ source/v1.11/bundle_package.haml | 75 +++++ source/v1.11/bundle_platform.haml | 39 +++ source/v1.11/bundle_show.haml | 16 ++ source/v1.11/bundle_update.haml | 218 +++++++++++++++ source/v1.11/bundle_version.haml | 8 + source/v1.11/bundle_viz.haml | 27 ++ source/v1.11/bundler_setup.haml | 103 +++++++ source/v1.11/bundler_sharing.haml | 60 ++++ source/v1.11/bundler_workflow.haml | 198 +++++++++++++ source/v1.11/commands.haml | 124 +++++++++ source/v1.11/deploying.haml | 155 +++++++++++ source/v1.11/faq.haml | 167 +++++++++++ source/v1.11/gemfile.haml | 155 +++++++++++ source/v1.11/gemfile_ruby.haml | 44 +++ source/v1.11/git.haml | 192 +++++++++++++ source/v1.11/groups.haml | 137 +++++++++ source/v1.11/index.haml | 140 ++++++++++ source/v1.11/rails23.haml | 104 +++++++ source/v1.11/rails3.haml | 76 +++++ source/v1.11/rationale.haml | 427 +++++++++++++++++++++++++++++ source/v1.11/rubygems.haml | 51 ++++ source/v1.11/rubymotion.haml | 36 +++ source/v1.11/sinatra.haml | 28 ++ source/v1.11/updating_gems.haml | 116 ++++++++ source/v1.11/whats_new.haml | 39 +++ 39 files changed, 3350 insertions(+), 1 deletion(-) create mode 100644 source/v1.11/bundle_binstubs.haml create mode 100644 source/v1.11/bundle_check.haml create mode 100644 source/v1.11/bundle_clean.haml create mode 100644 source/v1.11/bundle_config.haml create mode 100644 source/v1.11/bundle_console.haml create mode 100644 source/v1.11/bundle_exec.haml create mode 100644 source/v1.11/bundle_gem.haml create mode 100644 source/v1.11/bundle_help.haml create mode 100644 source/v1.11/bundle_init.haml create mode 100644 source/v1.11/bundle_inject.haml create mode 100644 source/v1.11/bundle_install.haml create mode 100644 source/v1.11/bundle_open.haml create mode 100644 source/v1.11/bundle_outdated.haml create mode 100644 source/v1.11/bundle_package.haml create mode 100644 source/v1.11/bundle_platform.haml create mode 100644 source/v1.11/bundle_show.haml create mode 100644 source/v1.11/bundle_update.haml create mode 100644 source/v1.11/bundle_version.haml create mode 100644 source/v1.11/bundle_viz.haml create mode 100644 source/v1.11/bundler_setup.haml create mode 100644 source/v1.11/bundler_sharing.haml create mode 100644 source/v1.11/bundler_workflow.haml create mode 100644 source/v1.11/commands.haml create mode 100644 source/v1.11/deploying.haml create mode 100644 source/v1.11/faq.haml create mode 100644 source/v1.11/gemfile.haml create mode 100644 source/v1.11/gemfile_ruby.haml create mode 100644 source/v1.11/git.haml create mode 100644 source/v1.11/groups.haml create mode 100644 source/v1.11/index.haml create mode 100644 source/v1.11/rails23.haml create mode 100644 source/v1.11/rails3.haml create mode 100644 source/v1.11/rationale.haml create mode 100644 source/v1.11/rubygems.haml create mode 100644 source/v1.11/rubymotion.haml create mode 100644 source/v1.11/sinatra.haml create mode 100644 source/v1.11/updating_gems.haml create mode 100644 source/v1.11/whats_new.haml diff --git a/source/shared/_whats_new.haml b/source/shared/_whats_new.haml index 7bc33dc81c..fa867a8836 100644 --- a/source/shared/_whats_new.haml +++ b/source/shared/_whats_new.haml @@ -1,6 +1,7 @@ %h1 What's New in each Release .buttons - = link_to 'v1.10', '/v1.10/whats_new.html' + = link_to 'v1.11', '/v1.11/whats_new.html' + = link_to 'v1.10', '/v1.10/whats_new.html#version110' = link_to 'v1.9', '/v1.9/whats_new.html#version19' = link_to 'v1.8', '/v1.8/whats_new.html#version18' = link_to 'v1.7', '/v1.7/whats_new.html#version17' diff --git a/source/v1.11/bundle_binstubs.haml b/source/v1.11/bundle_binstubs.haml new file mode 100644 index 0000000000..1bd4e824ab --- /dev/null +++ b/source/v1.11/bundle_binstubs.haml @@ -0,0 +1,18 @@ +%h2 bundle binstubs + +.contents + .bullet + .description + Installs the binstubs of the listed gem + :code + $ bundle binstubs [GEM] [--force] [--path=PATH] + .notes + %p + Options: + %p + --force: Overwrite existing binstubs if they exist. + %p + --path: Binstub destination directory (default bin) + .description + Generate binstubs for executables in [GEM]. Binstubs are put into bin, + or the --binstubs directory if one has been set. diff --git a/source/v1.11/bundle_check.haml b/source/v1.11/bundle_check.haml new file mode 100644 index 0000000000..606f48b541 --- /dev/null +++ b/source/v1.11/bundle_check.haml @@ -0,0 +1,23 @@ +%h2 bundle check + +.contents + .bullet + .description + Checks if the dependencies listed in Gemfile are satisfied by currently installed gems + :code + $ bundle check [--dry-run] [--gemfile=FILE] [--path=PATH] + .notes + %p + Options: + %p + --dry-run: Locks the Gemfile. + %p + --gemfile: Use the specified gemfile instead of Gemfile. + %p + --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. + .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. diff --git a/source/v1.11/bundle_clean.haml b/source/v1.11/bundle_clean.haml new file mode 100644 index 0000000000..9ca8ef3993 --- /dev/null +++ b/source/v1.11/bundle_clean.haml @@ -0,0 +1,16 @@ +%h2 bundle clean + +.contents + .bullet + .description + Cleans up unused gems in your bundler directory + :code + $ bundle clean [--dry-run] [--force] + .notes + %p + Options: + %p + --dry-run: Only print out changes, do not actually clean + gems + %p + --force: Forces clean even if --path is set diff --git a/source/v1.11/bundle_config.haml b/source/v1.11/bundle_config.haml new file mode 100644 index 0000000000..ae17158ca1 --- /dev/null +++ b/source/v1.11/bundle_config.haml @@ -0,0 +1,275 @@ +%h2 bundle config + +.contents + .bullet + .description + Retrieve or set a configuration value + :code + $ bundle config [NAME [VALUE]] [--local] [--global] [--delete] + .notes + %p + Options: + %p + --local: Get/set local configuration + %p + --global: Get/set global configuration + %p + --delete: Delete NAME value + .description + %p + Retrieves or sets a configuration value. If only parameter is provided, + retrieve the value. If two parameters are provided, replace the existing + value with the newly provided one. + %p + By default, setting a configuration value sets it for all projects on + the machine. + %p + If a global setting is superceded by local configuration, this command + will show the current value, as well as any superceded values and where + they were specified. + + .bullet#config + .description + Get your bundle configuration. + .how + :code + $ bundle config + .notes + Executing bundle config with no parameters will print a + list of all bundler configuration for the current bundle, and where + that configuration was set. + + .bullet#get + .description + Get your bundle configuration for NAME variable. + .how + :code + $ bundle config NAME + .notes + Will print the value of that configuration setting for + NAME, and where it was set. Will print both local and + global configuration. + + .bullet#set + .description + Set your bundle configuration for NAME variable to + VALUE. + .how + :code + $ bundle config NAME VALUE + .notes + Will set NAME to VALUE for all bundles + executed as the current user (i.e. global setting). The configuration + will be stored in ~/.bundle/config. If NAME + already is set, NAME will be overridden and user will be + warned. + + .bullet#global + .description + Set your bundle global/user configuration for NAME variable + to VALUE. + .how + :code + $ bundle config --global NAME VALUE + .notes + Works the same as the command above. + + .bullet#local + .description + Set your bundle local configuration for NAME variable to + VALUE. + .how + :code + $ bundle config --local NAME VALUE + .notes + Works the same as the two command above but for the local application. + The configuration will be stored in app/.bundle/config. + + .bullet#delete + .description + Delete the configuration for NAME in both local and global sources. + .how + :code + $ bundle config --delete NAME + .notes + Will delete the configuration for NAME variable in both local and global sources. Not compatible with --global or --local flag. + +%h2 Build options +.contents + .bullet#build_options + .description + %p + 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. + + %p + 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. + + .how + :code + $ gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config + + %p + Since the specific location of that executable can change from machine + to machine, you can specify these flags on a per-machine basis. + + .how + :code + $ bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config + %p + After running this command, every time bundler needs to install the + mysql gem, it will pass along the flags you specified. + + +%h2 Configuration keys +.contents + .bullet#configuration_keys + .description + %p + Configuration keys in bundler have two forms: the canonical form and + the environment variable form. + + %p + For instance, passing the --without flag to + bundle install prevents Bundler from installing + certain groups specified in the Gemfile. 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 remember this setting and + skip those groups. + + %p + 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. + +%h2 List of available keys +.contents + .bullet#available_keys + .description + %p + The following is a list of all configuration keys and their purpose. + You can learn more about their operation in + bundle install. + %ul + %li + auto_install (1): Setting auto_install config + to 1 or any other truthy value will enable automatic installing of gems + instead of raising an error. This behavior applies to the following + commands: show, binstubs, + outdated, exec, open, + console, license, clean. + %li + path (BUNDLE_PATH): The location on disk + to install gems. Defaults to $GEM_HOME in development + and vendor/bundle when --deployment is used. + %li + frozen (BUNDLE_FROZEN): Disallow changes to + the Gemfile. Defaults to true when + --deployment is used. + %li + without (BUNDLE_WITHOUT): A + :-separated list of groups whose gems bundler should not + installer + %li + bin (BUNDLE_BIN): Install executables from + gems in the bundle to the specified directory. Defaults to + false. + %li + 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. + %li + 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. + %li + ssl_client_cert (BUNDLE_SSL_CLIENT_CERT): + Path to a designated file containing a X.509 client certificate + and key in PEM format. + %li + cache_path (BUNDLE_CACHE_PATH): The directory + that bundler will place cached gems in when running bundle + package and that bundler will look in when installing with the + --deployment option. + %li + disable_multisource (BUNDLE_DISABLE_MULTISOURCE): + When set, Gemfiles containing multiple sources will produce an error + instead of a warning. Use bundle config --delete + disable_multisource to unset. + + %p + In general, you should set these settings per-application by using the + applicable flag to the bundle install or bundle + package command. + + %p + 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. + +%h2 Local git repositories +.contents + .bullet#local_git_repos + .description + %p + 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: + + :code + $ bundle config local.GEM_NAME /path/to/local/git/repository + + %p + For example, in order to use a local Rack repository, a developer + could call: + + :code + $ bundle config local.rack ~/Work/git/rack + + %p + 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. + + %p + 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. + + %p + 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. + +%h2 Gem Source Mirrors +.contents + .bullet#gem-source-mirrors + .description + %p + If your environment contains a local mirror of the rubygems.org server, + use the mirror.URL configuration option to supply the URL + of the mirror. At that point, Bundler will download gems and gemspecs + from that mirror instead of the source listed in the Gemfile. + + :code + $ bundle config mirror.https://rubygems.org https://localgems.lan diff --git a/source/v1.11/bundle_console.haml b/source/v1.11/bundle_console.haml new file mode 100644 index 0000000000..9efd8a0527 --- /dev/null +++ b/source/v1.11/bundle_console.haml @@ -0,0 +1,15 @@ +%h2 bundle console + +.contents + .bullet + .description + Start an interactive Ruby console session in the context of the current bundle + :code + $ bundle console [GROUP] + + .description + bundle console uses irb by default. Alternatives like Pry and Ripl can be used with bundle console by adjusting the console Bundler setting. Also make sure that pry or ripl is in your Gemfile. + :code + $ bundle config console pry + $ bundle console + [1] pry(main)> diff --git a/source/v1.11/bundle_exec.haml b/source/v1.11/bundle_exec.haml new file mode 100644 index 0000000000..3f8de13cd1 --- /dev/null +++ b/source/v1.11/bundle_exec.haml @@ -0,0 +1,26 @@ +%h2 bundle exec + +.contents + .bullet + .description + Run the command in context of the bundle + :code + $ bundle exec [--keep-file-descriptors] + .notes + %p + Options: + %p + --keep-file-descriptors: For Ruby versions less than 2.0, + keeps non-standard file descriptors on Kernel#exec + + .description + This command executes the command, making all gems specified in the + 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 and installed via bundle install, 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. diff --git a/source/v1.11/bundle_gem.haml b/source/v1.11/bundle_gem.haml new file mode 100644 index 0000000000..ae8406a0fa --- /dev/null +++ b/source/v1.11/bundle_gem.haml @@ -0,0 +1,38 @@ +%h2 bundle gem + +.contents + .bullet + .description + Creates a skeleton for creating a rubygem + :code + $ bundle gem GEM [--bin or -b] [--test=TESTFRAMEWORK] [--edit=TEXTEDITOR] [--ext] + .notes + %p + Options: + %p + --bin or -b: Generate a binary for your library. + %p + --coc: Generate a code of conduct file. + %p + --edit: Open generated gemspec in the specified editor (defaults to $EDITOR or $BUNDLER_EDITOR) + %p + --ext: Generate a skeleton for a C-extension. + %p + --mit: Generate an MIT license file. + %p + --test: Generate a test directory for your library: + rspec is the default, but minitest is also supported. + .notes + %p + When run for the first time, bundle gem will ask for your preferences regarding test framework, code of conduct, and MIT license. These preferences will be stored in ~/.bundle/config for future runs. + .bullet + .description + The generated project will contain all the necessary boilerplate, including a README and a gemspec template. Also included will be a Rakefile with tasks suitable for gem development: + .how + :code + $ rake -T + rake build # Build GEM-0.1.0.gem into the pkg directory + rake install # Build and install GEM-0.1.0.gem into system gems + rake install:local # Build and install GEM-0.1.0.gem into system gems without network access + rake release # Create tag v0.1.0 and build and push GEM-0.1.0.gem to Rubygems + rake test # Run tests diff --git a/source/v1.11/bundle_help.haml b/source/v1.11/bundle_help.haml new file mode 100644 index 0000000000..fd09a4b50a --- /dev/null +++ b/source/v1.11/bundle_help.haml @@ -0,0 +1,10 @@ +%h2 bundle help + +.contents + .bullet + .description + Displays detailed help for each subcommand on your command line + :code + $ bundle help + .notes + #{ link_to 'View the same man pages here', './man/bundle.1.html'} diff --git a/source/v1.11/bundle_init.haml b/source/v1.11/bundle_init.haml new file mode 100644 index 0000000000..18e7d7bd3b --- /dev/null +++ b/source/v1.11/bundle_init.haml @@ -0,0 +1,17 @@ +%h2 bundle init + +.contents + .bullet + .description + Generates a Gemfile into the current working directory + :code + $ bundle init [--gemspec=FILE] + .notes + %p + Options: + %p + --gemspec: Use the specified .gemspec to create the Gemfile + .description + Init generates a default Gemfile in the current working directory. When adding a + Gemfile to a gem with a gemspec, the --gemspec option will automatically add each + dependency listed in the gemspec file to the newly created Gemfile. diff --git a/source/v1.11/bundle_inject.haml b/source/v1.11/bundle_inject.haml new file mode 100644 index 0000000000..51fd112a33 --- /dev/null +++ b/source/v1.11/bundle_inject.haml @@ -0,0 +1,18 @@ +%h2 bundle inject + +.contents + .bullet + .description + Add the named gem(s), with version requirements, to the resolved Gemfile + :code + $ bundle inject [GEM] [VERSION] + + .bullet + .description + When injecting a gem, it adds it to both your Gemfile and Gemfile.lock if + it doesn't yet exist in them. Example below: + :code + $ bundle install + + $ bundle inject 'rack' '> 0' + # Injects rack gem greater than version 0 in your Gemfile and Gemfile.lock diff --git a/source/v1.11/bundle_install.haml b/source/v1.11/bundle_install.haml new file mode 100644 index 0000000000..ad8958ec21 --- /dev/null +++ b/source/v1.11/bundle_install.haml @@ -0,0 +1,122 @@ +%h2 bundle install + +.contents + .bullet + .description + Make sure all dependencies in your Gemfile are available to your application. + :code + $ bundle install [--binstubs=PATH] [--clean] [--deployment] [--frozen] + [--full-index] [--gemfile=FILE] [--local] [--no-cache] + [--no-prune] [--path=PATH] [--quiet] [--shebang=STRING] + [--standalone[=GROUP [GROUP...]] [--system] + [--without=GROUP[ GROUP...]] [--retry=NUMBER] + [--trust-policy=SECURITYLEVEL] + .notes + %p + Options: + %p + --binstubs: Generate bin stubs for bundled gems to ./bin + %p + --clean: Run bundle clean automatically after install + %p + --deployment: Install using defaults tuned for deployment and CI environments + %p + --frozen: Do not allow the Gemfile.lock to be updated after this install + %p + --full-index: Use the rubygems modern index instead of the API endpoint + %p + --gemfile: Use the specified gemfile instead of Gemfile + %p + --jobs: Install gems using parallel workers. + %p + --local: Do not attempt to fetch gems remotely and use the gem cache instead + %p + --no-cache: Don't update the existing gem cache. + %p + --no-prune: Don't remove stale gems from the cache. + %p + --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 + %p + --quiet: Only output warnings and errors. + %p + --retry: Retry network and git requests that have failed. + %p + --shebang: Specify a different shebang executable name than the default (usually 'ruby') + %p + --standalone: Make a bundle that can work without the Bundler runtime + %p + --system: Install to the system location ($BUNDLE_PATH or $GEM_HOME) even if the bundle was previously installed somewhere else for this application + %p + --trust-policy: Sets level of security when dealing with signed gems. Accepts `LowSecurity`, `MediumSecurity` and `HighSecurity` as values. + %p + --without: Exclude gems that are part of the specified named group. + .notes + %p + Gems will be installed to your default system location for gems. If your + system gems are stored in a root-owned location (such as in Mac OSX), + bundle will ask for your root password to install them there. + %p + While installing gems, Bundler will check vendor/cache and then + your system's gems. If a gem isn't cached or installed, Bundler will try to + install it from the sources you have declared in your Gemfile. + %p + The --system option is the default. Pass it to switch back after + using the --path option as described below. + + .bullet#path + .description + Install your dependencies, even gems that are already installed + to your system gems, to a location other than your system's gem + repository. In this case, install them to vendor/bundle. + .how + :code + $ bundle install --path vendor/bundle + .notes + Further bundle commands or calls to Bundler.setup or + Bundler.require will remember this location. + = link_to 'Learn More: Bundler.setup', './bundler_setup.html' + = link_to 'Learn More: Bundler.require', './groups.html' + + .bullet#without + .description + Install all dependencies except those in groups that are explicitly excluded. + :code + $ bundle install --without development test + = link_to 'Learn More: Groups', './groups.html' + + .bullet#deployment + .description + Install all dependencies onto a production or CI server. + Do not use this flag on a development machine. + :code + $ bundle install --deployment + .notes + %p + The --deployment flag activates a number of deployment- and + CI-friendly conventions: + + %ul + %li + Isolate all gems into vendor/bundle + (equivalent to --path vendor/bundle) + %li + Require an up-to-date Gemfile.lock + (equivalent to --frozen) + %li Disable ANSI color output + %li + If bundle package was run, do not fetch gems + from rubygems.org. Instead, only use gems in the checked + in vendor/cache + = link_to 'Learn More: Deploying', './deploying.html' + + .bullet#jobs + .description + Install gems parallely by starting the number of workers specificed. + :code + $ bundle install --jobs 4 + + .bullet#retry + .description + Retry failed network or git requests. + :code + $ bundle install --retry 3 diff --git a/source/v1.11/bundle_open.haml b/source/v1.11/bundle_open.haml new file mode 100644 index 0000000000..bcdcc0b01e --- /dev/null +++ b/source/v1.11/bundle_open.haml @@ -0,0 +1,12 @@ +%h2 bundle open + +.contents + .bullet + .description + Opens the source directory of the given bundled gem + :code + $ bundle open GEM + .description + %p + 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. diff --git a/source/v1.11/bundle_outdated.haml b/source/v1.11/bundle_outdated.haml new file mode 100644 index 0000000000..ccfd040f56 --- /dev/null +++ b/source/v1.11/bundle_outdated.haml @@ -0,0 +1,23 @@ +%h2 bundle outdated + +.contents + .bullet + .description + List installed gems with newer versions available + :code + $ bundle outdated [GEM] [--local] [--pre] [--source] [--strict] + .notes + %p + Options: + %p + --local: Do not attempt to fetch gems remotely and use the gem cache instead + %p + --pre: Check for newer pre-release gems + %p + --source: Check against a specific source + %p + --strict: Display outdated gems that match the dependency requirements. + .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. By default, available prerelease gems will be ignored. diff --git a/source/v1.11/bundle_package.haml b/source/v1.11/bundle_package.haml new file mode 100644 index 0000000000..bf0d402b50 --- /dev/null +++ b/source/v1.11/bundle_package.haml @@ -0,0 +1,75 @@ +%h2 bundle package + +.contents + .bullet + .description + Locks and then caches the gems into ./vendor/cache. + :code + $ bundle package [--all] [--all-platforms] [--gemfile=GEMFILE] [--no-prune] + [--path=PATH] [--quiet] + .notes + %p + Options: + %p + --all: package :git, :path, and .gem dependencies. Once used, the --all option will be remembered. + %p + --all-platforms: package dependencies for all known platforms, not only the one that bundle package is run on. This option will be remembered in your local Bundler configuration. + %p + --gemfile: Use the specified gemfile instead of Gemfile. + %p + --no-install: Don't actually install the gems, just package. + %p + --no-prune: Don't remove stale gems from the cache. + %p + --path: Specify a different path than the system default. + %p + --quiet: Only output warnings and errors. + .description + %p + The package command will copy the .gem files for your gems in the + bundle into ./vendor/cache. Afterward, when you run bundle install, Bundler will use the gems in the cache in preference to the ones on rubygems.org. + + %p + Additionally, if you then check that directory into your source control repository, others who check out your source will be able to install the bundle without having to download any additional gems. + + .bullet + .description + Lock and cache gems from RubyGems into ./vendor/cache. + + .how + :code + $ bundle package + + .notes + %p + By default, if you simply run bundle install after running + bundle package, Bundler will still connect to rubygems.org to check + whether a platform-specific gem exists for any of the gems in vendor/cache. + + %p + This behavior can be avoided by instead running bundle install --local. + Note that this requires you to have the correctly platformed version for all of your gems + already cached. The easiest way to achieve this is to run bundle package + on an identical machine and then check in those vendored gems. + + .bullet#no-prune + .description + Lock and cache gems from RubyGems into ./vendor/cache, and don't remove any stale gems from the existing cache. + + .how + :code + $ bundle package --no-prune + + .bullet#all + .description + Lock and cache all gems into ./vendor/cache, including :git, :path, and .gem dependencies. + + .how + :code + $ bundle package --all + .notes + %p + Once used, the --all option will be remembered. + + %p + This will be the default on Bundler 2.0. diff --git a/source/v1.11/bundle_platform.haml b/source/v1.11/bundle_platform.haml new file mode 100644 index 0000000000..f77674bfe9 --- /dev/null +++ b/source/v1.11/bundle_platform.haml @@ -0,0 +1,39 @@ +%h2 bundle platform + +.contents + .bullet + .description + Displays platform compatibility information + :code + $ bundle platform [--ruby] + .notes + %p + Options: + %p + --ruby: only display ruby related platform information + + .bullet + .description + When not passed any options, platform will display information from your Gemfile, Gemfile.lock, and Ruby VM about your platform. You'll see output like the following: + :code + $ bundle platform + 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. + .description + When the ruby directive doesn't match the running Ruby VM, it will tell you what part does not. + :code + Your Ruby version is 1.9.3, but your Gemfile specified 1.8.7 + + .bullet#ruby + .description + When using the --ruby flag, it will just display the ruby directive information, so you don't have to parse it from the Gemfile. + :code + $ bundle platform --ruby + ruby 1.9.3 (jruby 1.6.7) diff --git a/source/v1.11/bundle_show.haml b/source/v1.11/bundle_show.haml new file mode 100644 index 0000000000..72080427ed --- /dev/null +++ b/source/v1.11/bundle_show.haml @@ -0,0 +1,16 @@ +%h2 bundle show + +.contents + .bullet + .description + Shows all gems that are part of the bundle, or the path to a given gem + :code + $ bundle show [GEM] [--paths] + .notes + %p + Options: + %p + --paths: List the paths of all gems that are required by your Gemfile. + .description + Show lists the names and versions of all gems that are required by your Gemfile. + Calling show with [GEM] will list the exact location of that gem on your machine. diff --git a/source/v1.11/bundle_update.haml b/source/v1.11/bundle_update.haml new file mode 100644 index 0000000000..c8f0cf7898 --- /dev/null +++ b/source/v1.11/bundle_update.haml @@ -0,0 +1,218 @@ +%h2 bundle update + +.contents + .bullet + .description + Update the current environment + + :code + $ bundle update [GEM] [--full-index] [--group=GROUP] [--jobs=NUMBER] [--local] + [--quiet] [--source=SOURCE] + .notes + %p + Options: + %p + --full-index: Use the rubygems modern index instead of + the API endpoint + %p + --group: Update one or more gem groups + %p + --jobs: Specify the number of jobs to run in parallel + %p + --local: Do not attempt to fetch gems remotely and use + the gem cache instead + %p + --quiet: Only output warnings and errors. + %p + --source: Update a specific source (and all gems + associated with it) + + .description + %p + Update the gems specified (all gems, if none are specified), ignoring + the previously installed gems specified in the Gemfile.lock. + In general, you should use bundle install to install the + same exact gems and versions across machines. + + %p + You would use bundle update to explicitly update the + version of a gem. + + .bullet + .description + Update the current environment. + .how + :code + $ bundle update + .notes + If you run bundle update with no parameters, bundler will + ignore any previously installed gems and resolve all dependencies again + based on the latest versions of all gems available in the sources. + + .bullet#source + .description + Update a specific source (and all gems associated with it) + .how + :code + $ bundle update --source=SOURCE + .notes + The name of a :git or :path source used in the + Gemfile. For instance, with a :git source of + http://github.com/rails/rails.git, you would call + bundle update --source rails. + +%h2 Update all gems +.contents + .bullet#update_all_extended + .description + %p + If you run bundle update with no parameters, bundler will + ignore any previously installed gems and resolve all dependencies again + based on the latest versions of all gems available in the sources. + + %p + Consider the following Gemfile: + + :code + # lang: ruby + source 'https://rubygems.org' + gem 'rails', '3.0.0.rc' + gem 'nokogiri' + %p + When you run bundle install the first time, bundler will + resolve all of the dependencies, all the way down, and install what you + need: + :code + Fetching source index for https://rubygems.org/ + Installing rake (0.8.7) + Installing abstract (1.0.0) + Installing activesupport (3.0.0.rc) + Installing builder (2.1.2) + Installing i18n (0.4.1) + Installing activemodel (3.0.0.rc) + Installing erubis (2.6.6) + Installing rack (1.2.1) + Installing rack-mount (0.6.9) + Installing rack-test (0.5.4) + Installing tzinfo (0.3.22) + Installing actionpack (3.0.0.rc) + Installing mime-types (1.16) + Installing polyglot (0.3.1) + Installing treetop (1.4.8) + Installing mail (2.2.5) + Installing actionmailer (3.0.0.rc) + Installing arel (0.4.0) + Installing activerecord (3.0.0.rc) + Installing activeresource (3.0.0.rc) + Installing bundler (1.0.0.rc.3) + Installing nokogiri (1.4.3.1) with native extensions + Installing thor (0.14.0) + Installing railties (3.0.0.rc) + Installing rails (3.0.0.rc) + + Your bundle is complete! Use `bundle show [gemname]` to see where a + bundled gem is installed. + %p + As you can see, even though you have just two gems in the + Gemfile, your application actually needs 25 different gems + in order to run. Bundler remembers the exact versions it installed in + Gemfile.lock. The next time you run + bundle install, bundler skips the dependency resolution and + installs the same gems as it installed last time. + + %p + After checking in the Gemfile.lock into version control and + cloning it on another machine, running bundle install 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. + + %p + 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. + + %p + To do this, run bundle update, which will ignore the + Gemfile.lock, and resolve all the dependencies again. Keep + in mind that this process can result in a significantly 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. + +%h2 Update a list of gems. +.contents + .bullet#update_list_of_gems + .description + %p + Sometimes, you want to update a single gem in the Gemfile, + and leave the rest of the gems that you specified locked to the + versions in the Gemfile.lock. + + %p + 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 + + :code + bundle update nokogiri + + %p + Bundler will update nokogiri and any of its dependencies, + but leave alone Rails and its dependencies. + +%h2 Overlapping dependencies +.contents + .bullet#overlapping_dependencies + .description + %p + Sometimes, multiple gems declared in your Gemfile are + satisfied by the same second-level dependency. For instance, consider the + case of thin and rack-perftools-profiler. + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'thin' + gem 'rack-perftools-profiler' + + %p + The thin gem depends on rack >= 1.0, while + rack-perftools-profiler depends on rack ~> 1.0. + If you run bundle install, you get: + + :code + 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) + + %p + 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. + + %p + In short, when you update a gem using + bundle update, bundler will update all dependencies of that + gem, including those that are also dependencies of another gem. + + %p + In this scenario, updating the thin version manually in the + Gemfile, and then running bundle install will + only update daemons and eventmachine, but not + rack. + -# For more information, see the CONSERVATIVE UPDATING + -#section of bundle install. diff --git a/source/v1.11/bundle_version.haml b/source/v1.11/bundle_version.haml new file mode 100644 index 0000000000..54c1e71dc1 --- /dev/null +++ b/source/v1.11/bundle_version.haml @@ -0,0 +1,8 @@ +%h2 bundle version + +.contents + .bullet + .description + Prints the bundler's version information + :code + $ bundle version diff --git a/source/v1.11/bundle_viz.haml b/source/v1.11/bundle_viz.haml new file mode 100644 index 0000000000..f7b4cafb26 --- /dev/null +++ b/source/v1.11/bundle_viz.haml @@ -0,0 +1,27 @@ +%h2 bundle viz + +.contents + .bullet + .description + Generates a visual dependency graph + :code + $ bundle viz [--file=FILE] [--format=FORMAT] [--requirements] [--version] + [--without=GROUP GROUP] + .notes + %p + Options: + %p + --file or -f: The name to use for the generated file. see format option + %p + --format or -F: This is output format option. Supported format is png, jpg, svg, dot ... + %p + --requirements or -r: Set to show the version of each required dependency. + %p + --version or -v: Set to show each gem version. + %p + --without: Exclude gems that are part of the specified named group. + = link_to 'Learn More: Groups', './groups.html' + .description + Viz generates a PNG file of the current Gemfile as a dependency graph. + Viz requires the ruby-graphviz gem (and its dependencies). + The associated gems must also be installed via 'bundle install'. diff --git a/source/v1.11/bundler_setup.haml b/source/v1.11/bundler_setup.haml new file mode 100644 index 0000000000..82276cb26f --- /dev/null +++ b/source/v1.11/bundler_setup.haml @@ -0,0 +1,103 @@ +%h2 Bundler.setup + +.contents + .bullet + .description + Configure the load path so all dependencies in + your Gemfile can be required + :code + # lang: ruby + require 'rubygems' + require 'bundler/setup' + require 'nokogiri' + + .bullet + .description + Only add gems from specified groups to the + load path. If you want the gems in the + default group, make sure to include it + :code + # lang: ruby + require 'rubygems' + require 'bundler' + Bundler.setup(:default, :ci) + require 'nokogiri' + = link_to 'Learn More: Groups', './groups.html' + +%h2 Compatibility + +.contents + .bullet + .description + Ruby 2.0 and RubyGems 2.0 both require Bundler 1.3 or later. If you have questions about compatibility between Bundler and your system, please check the compatibility list. + = link_to 'Learn More: Compatibility', '/compatibility.html' + + %h2#setting-up-your-application-to-use-bundler + Setting Up Your Application to Use Bundler + + .bullet + .description + Bundler makes sure that Ruby can find all of the gems in the Gemfile + (and all of their dependencies). If your app is a Rails 3 app, your default application + already has the code necessary to invoke bundler. If it is a Rails 2.3 app, please see: + Setting up Bundler in Rails 2.3 + + .bullet + .description + For another kind of application (such as a Sinatra application), you will need to set up + bundler before trying to require any gems. At the top of the first file that your + application loads (for Sinatra, the file that calls require 'sinatra'), put + the following code: + + :code + # lang: ruby + require 'rubygems' + require 'bundler/setup' + + .bullet + .description + This will automatically discover your Gemfile, and make all of the gems in + your Gemfile available to Ruby (in technical terms, it puts the gems "on the + load path"). You can think of it as an adding some extra powers to require + 'rubygems'. + + .bullet + .description + Now that your code is available to Ruby, you can require the gems that you need. For + instance, you can require 'sinatra'. If you have a lot of dependencies, you + might want to say "require all of the gems in my Gemfile". To do this, put + the following code immediately following require 'bundler/setup': + + :code + # lang: ruby + Bundler.require(:default) + + For our example Gemfile, this line is exactly equivalent to: + + :code + # lang: ruby + require 'rails' + require 'rack-cache' + require 'nokogiri' + + .bullet + .description + Astute readers will notice that the correct way to require the rack-cache + gem is require 'rack/cache', not require 'rack-cache'. To tell + bundler to use require 'rack/cache', update your Gemfile: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'rails', '3.0.0.rc' + gem 'rack-cache', :require => 'rack/cache' + gem 'nokogiri', '~> 1.4.2' + + .bullet + .description + For such a small Gemfile, we'd advise you to skip + Bundler.require and just require the gems by hand (especially given the + need to put in a :require directive in the Gemfile). For much + larger Gemfiles, using Bundler.require allows you to skip + repeating a large stack of requirements. diff --git a/source/v1.11/bundler_sharing.haml b/source/v1.11/bundler_sharing.haml new file mode 100644 index 0000000000..8734945302 --- /dev/null +++ b/source/v1.11/bundler_sharing.haml @@ -0,0 +1,60 @@ +%h2#sharing + Sharing +.contents + .bullet + .description + %h3#checking-your-code-into-version-control + Checking Your Code into Version Control + + %p + After developing your application for a while, check in the application together with the + Gemfile and Gemfile.lock snapshot. Now, your repository has a + record of the exact versions of all of the gems that you used the last time you know for + sure that the application worked. Keep in mind that while your Gemfile + lists only three gems (with varying degrees of version strictness), your application + depends on dozens of gems, once you take into consideration all of the implicit + requirements of the gems you depend on. + + %p.description + This is important: the Gemfile.lock makes your application a single + package of both your own code and the third-party code it ran the last time you know for + sure that everything worked. Specifying exact versions of the third-party code + you depend on in your Gemfile would not provide the same guarantee, because + gems usually declare a range of versions for their dependencies. + + %p.description + The next time you run bundle install on the same machine, bundler will see + that it already has all of the dependencies you need, and skip the installation process. + + %p.description + Do not check in the .bundle directory, or any of the files inside it. Those + files are specific to each particular machine, and are used to persist installation options + between runs of the bundle install command. + + %p.description + If you have run bundle pack, the gems (although not the git gems) required + by your bundle will be downloaded into vendor/cache. Bundler can run without + connecting to the internet (or the RubyGems server) if all the gems you need are present + in that folder and checked in to your source control. This is an optional + step, and not recommended, due to the increase in size of your source control repository. + + .bullet + %h3#sharing-your-application-with-other-developers + Sharing Your Application With Other Developers + + %p.description + When your co-developers (or you on another machine) check out your code, it will come + with the exact versions of all the third-party code your application used on the machine + that you last developed on (in the Gemfile.lock). When **they** run + bundle install, bundler will find the Gemfile.lock and skip + the dependency resolution step. Instead, it will install all of the same gems that you + used on the original machine. + + %p.description + In other words, you don't have to guess which versions of the dependencies you should + install. In the example we've been using, even though rack-cache declares a + dependency on rack >= 0.4, we know for sure it works with rack + 1.2.1. Even if the Rack team releases rack 1.2.2, bundler will + always install 1.2.1, the exact version of the gem that we know works. This + relieves a large maintenance burden from application developers, because all machines + always run the exact same third-party code. diff --git a/source/v1.11/bundler_workflow.haml b/source/v1.11/bundler_workflow.haml new file mode 100644 index 0000000000..b05de90b5d --- /dev/null +++ b/source/v1.11/bundler_workflow.haml @@ -0,0 +1,198 @@ +%h2 Recommended Workflow with Version Control +.contents + .bullet#recommended_workflow + .description + %p + In general, when working with an application managed with bundler, you + should use the following workflow: + %p + After you create your Gemfile for the first time, run + :code + $ bundle install + %p + Check the resulting Gemfile.lock into version control + :code + $ git add Gemfile.lock + %p + When checking out this repository on another development machine, run + :code + $ bundle install + %p + When checking out this repository on a deployment machine, run + :code + $ bundle install --deployment + %p + After changing the Gemfile to reflect a new or update + dependency, run + :code + $ bundle install + %p + Make sure to check the updated Gemfile.lock into version + control + :code + $ git add Gemfile.lock + %p + If bundle install reports a conflict, manually update the + specific gems that you changed in the Gemfile + :code + $ bundle update rails thin + %p + If you want to update all the gems to the latest possible versions that + still match the gems listed in the Gemfile, run + :code + $ bundle update + +%h2 A Thorough Bundler Workflow + +.contents + .bullet + .description + Getting started with bundler is easy! Open a terminal window and run this command: + :code + $ gem install bundler + .notes + %li + When you first create a Rails application, it already comes with a + Gemfile. For another kind of application (such as Sinatra), run: + + :code + $ bundle init + + %li + The bundle init command creates a simple Gemfile which you + can edit. + + .bullet + .description + Specify your dependencies in the root of your application, called the Gemfile. + It looks something like this: + :code + # lang: ruby + source 'https://rubygems.org' + gem 'nokogiri' + gem 'rack', '~>1.1' + gem 'rspec', :require => 'spec' + + .notes + This Gemfile says a few things. First, it says that bundler should + look for gems declared in the Gemfile at https://rubygems.org by default. + = link_to 'Learn More: Gemfiles', './gemfile.html' + + .bullet + .description + %p + After declaring your first set of dependencies, you tell bundler to go get them: + + :code + $ bundle install # bundle is a shortcut for bundle install + + %p + Bundler will connect to rubygems.org (and any other sources that you declared), + and find a list of all of the required gems that meet the requirements you specified. + Because all of the gems in your Gemfile have dependencies of their own + (and some of those have their own dependencies), running bundle install on the + Gemfile above will install quite a few gems. + + :code + $ bundle install + Fetching gem metadata from https://rubygems.org/ + Resolving dependencies... + Using rake (0.8.7) + Using abstract (1.0.0) + Installing activesupport (3.0.0.rc) + Using builder (2.1.2) + Using i18n (0.4.1) + Installing activemodel (3.0.0.rc) + Using erubis (2.6.6) + Using rack (1.2.1) + Installing rack-mount (0.6.9) + Using rack-test (0.5.4) + Using tzinfo (0.3.22) + Installing actionpack (3.0.0.rc) + Using mime-types (1.16) + Using polyglot (0.3.1) + Using treetop (1.4.8) + Using mail (2.2.5) + Installing actionmailer (3.0.0.rc) + Using arel (0.4.0) + Installing activerecord (3.0.0.rc) + Installing activeresource (3.0.0.rc) + Using bundler (1.0.0.rc.3) + Installing nokogiri (1.4.3.1) with native extensions + Installing rack-cache (0.5.2) + Installing thor (0.14.0) + Installing railties (3.0.0.rc) + Installing rails (3.0.0.rc) + Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed. + + %p + If any of the needed gems are already installed, Bundler will use them. After installing + any needed gems to your system, bundler writes a snapshot of all of the gems and + versions that it installed to Gemfile.lock. + + .notes + + %li + If bundle install reports a conflict between your Gemfile and + Gemfile.lock, run: + + :code + $ bundle update sinatra + + %li + This will update just the Sinatra gem, as well as any of its dependencies. + + %p + %li + To update all of the gems in your Gemfile to the latest possible versions, run: + + :code + $ bundle update + + %li + Whenever your Gemfile.lock changes, always check it in to version control. + It keeps a history of the exact versions of all third-party code that you used to successfully + run your application. + + %li + The git add Gemfile* command adds the Gemfile and Gemfile.lock to your repository. This ensures that + other developers on your app, as well as your deployment environment, will all use the same + third-party code that you are using now. + .buttons + = link_to 'Learn More: bundle install', './bundle_install.html' + = link_to 'Learn More: bundle update', './bundle_update.html' + .bullet + .description + Inside your app, load up the bundled environment: + :code + # lang: ruby + require 'rubygems' + require 'bundler/setup' + + # require your gems as usual + require 'nokogiri' + = link_to 'Learn More: Bundler.setup', './bundler_setup.html' + .bullet + .description + Run an executable that comes with a gem in your bundle: + :code + $ bundle exec rspec spec/models + .notes + %p + In some cases, running executables without bundle exec + may work, if the executable happens to be installed in your system + and does not pull in any gems that conflict with your bundle. + %p + However, this is unreliable and is the source of considerable pain. + Even if it looks like it works, it may not work in the future or + on another machine. + .bullet + .description + Finally, if you want a way to get a shortcut to gems in your bundle: + :code + $ bundle install --binstubs + $ bin/rspec spec/models + .notes + The executables installed into bin are scoped to the + bundle, and will always work. + = link_to 'Learn More: Executables', './man/bundle-exec.1.html' diff --git a/source/v1.11/commands.haml b/source/v1.11/commands.haml new file mode 100644 index 0000000000..e937aae548 --- /dev/null +++ b/source/v1.11/commands.haml @@ -0,0 +1,124 @@ +%h2 Command Line Reference + +#command_reference + %table{:cellspacing => 0} + %tr + %th + command + %th + applicable options + = command_table_row do |command| + - command.name = 'binstubs' + - command.desc = 'Installs the binstubs of the listed gem' + - command.option = 'force' + - command.option = 'path' + = command_table_row do |command| + - command.name = 'check' + - command.desc = 'Checks if the dependencies listed in Gemfile are satisfied by currently installed gems' + - command.option = 'dry-run' + - command.option = 'gemfile' + - command.option = 'path' + = command_table_row do |command| + - command.name = 'clean' + - command.desc = 'Cleans up unused gems in your bundler directory' + - command.option = 'dry-run' + - command.option = 'force' + = command_table_row do |command| + - command.name = 'config' + - command.desc = 'Retrieve or set a configuration value' + - command.option = 'local' + - command.option = 'global' + - command.option = 'delete' + = command_table_row do |command| + - command.name = 'console' + - command.desc = 'Opens an IRB session with the bundle pre-loaded' + = command_table_row do |command| + - command.name = 'exec' + - command.desc = 'Run the command in context of the bundle' + - command.option = 'keep-file-descriptors' + = command_table_row do |command| + - command.name = 'gem' + - command.desc = 'Creates a skeleton for creating a rubygem' + - command.option = 'bin or -b' + - command.option = 'edit' + - command.option = 'ext' + - command.option = 'test' + = command_table_row do |command| + - command.name = 'help' + - command.desc = 'Displays detailed help for each subcommand' + = command_table_row do |command| + - command.name = 'init' + - command.desc = 'Generates a Gemfile into the current working directory' + - command.option = 'gemspec' + = command_table_row do |command| + - command.name = 'inject' + - command.desc = 'Add the named gem(s), with version requirements, to the resolved Gemfile' + = command_table_row do |command| + - command.name = 'install' + - command.desc = 'Install the current environment to the system' + - command.option = 'binstubs' + - command.option = 'clean' + - command.option = 'deployment' + - command.option = 'frozen' + - command.option = 'full-index' + - command.option = 'gemfile' + - command.option = 'jobs' + - command.option = 'local' + - command.option = 'no-cache' + - command.option = 'no-prune' + - command.option = 'path' + - command.option = 'quiet' + - command.option = 'retry' + - command.option = 'shebang' + - command.option = 'standalone' + - command.option = 'system' + - command.option = 'trust-policy' + - command.option = 'without' + = command_table_row do |command| + - command.name = 'open' + - command.desc = 'Opens the source directory of the given bundled gem' + = command_table_row do |command| + - command.name = 'outdated' + - command.desc = 'List installed gems with newer versions available' + - command.option = 'local' + - command.option = 'pre' + - command.option = 'source' + - command.option = 'strict' + = command_table_row do |command| + - command.name = 'package' + - command.desc = 'Locks and then caches all of the gems into vendor/cache' + - command.option = 'all' + - command.option = 'all-platforms' + - command.option = 'gemfile' + - command.option = 'no-install' + - command.option = 'no-prune' + - command.option = 'path' + - command.option = 'quiet' + = command_table_row do |command| + - command.name = 'platform' + - command.desc = 'Displays platform compatibility information' + - command.option = 'ruby' + = command_table_row do |command| + - command.name = 'show' + - command.desc = 'Shows all gems that are part of the bundle, or the path to a given gem' + - command.option = 'paths' + = command_table_row do |command| + - command.name = 'update' + - command.desc = 'Update the current environment' + - command.option = 'full-index' + - command.option = 'group' + - command.option = 'jobs' + - command.option = 'local' + - command.option = 'quiet' + - command.option = 'source' + = command_table_row do |command| + - command.name = 'version' + - command.desc = 'Prints version information' + = command_table_row do |command| + - command.name = 'viz' + - command.desc = 'Generates a visual dependency graph' + - command.option = 'file or -f' + - command.option = 'format or -F' + - command.option = 'requirements or -r' + - command.option = 'version or -v' + - command.option = 'without' diff --git a/source/v1.11/deploying.haml b/source/v1.11/deploying.haml new file mode 100644 index 0000000000..fc6502db1e --- /dev/null +++ b/source/v1.11/deploying.haml @@ -0,0 +1,155 @@ +%h2 Deploying bundled applications +.contents + .bullet + .description + Before deploying an app that uses Bundler, Add your Gemfile + and Gemfile.lock to source control, but ignore the + .bundle folder, which is specific to each machine. + :code + $ echo ".bundle" >> .gitignore + $ git add Gemfile Gemfile.lock .gitignore + $ git commit -m "Add Bundler support" + .notes + Once you have done that, there are two ways to deploy using Bundler: + manually or automatically. + + .bullet + .description + %h3 Manual deployment + In your deploy script, after updating to the latest + code, install your bundle to the vendor/bundle + directory, ensuring all your dependencies are met. + :code + $ bundle install --deployment + .notes + %p + Start your application servers as usual, and your + application will use your bundled environment + with the exact same gems you use in development. + + %p + If you have run bundle package, the cached + gems will be used automatically. + + = link_to 'Learn More: Packing', './bundle_package.html' + + .bullet + %h3 Automatic deployment with Capistrano + .description + To pull in the Bundler Cap task, just add this to your + deploy.rb file: + :code + # lang: ruby + require 'bundler/capistrano' + .notes + That's it! Running cap deploy will now automatically run + bundle install on the remote server with deployment-friendly + options. A list of options that can be changed is available in the help + for the cap task. To see it, run cap -e bundle:install. + + .bullet + .description + %h3 Automatic deployment with Vlad + There is a default Vlad task available. To make it available, add this line + to the Vlad deploy.rb. + :code + # lang: ruby + require 'bundler/vlad' + .notes + Once you have done that, the vlad:bundle:install task will be + available for use. Make sure it is run as part of your deploy. For example: + :code + # lang: ruby + task "vlad:deploy" => %w[ + vlad:update vlad:bundle:install vlad:start_app vlad:cleanup + ] + + .bullet + .description + %h3 After deploying + Make sure to use bundle exec to run any executables + from gems in the bundle + :code + $ bundle exec rake db:setup + .notes + Alternatively, you can use the --binstubs option on the + install command to generate executable binaries that can be used instead of + bundle exec. + = link_to 'Learn More: Executables', './man/bundle-exec.1.html' + + .bullet + .description + %h3 Heroku + When you deploy to Heroku, Bundler will be run automatically as long as a Gemfile is present. If you check in your Gemfile.lock, Heroku will run `bundle install --deployment`. If you want to exclude certain groups using the --without option, you need to use `heroku config`. + :code + $ heroku config:add BUNDLE_WITHOUT="test development" --app app_name + = link_to 'Heroku Bundler Documentation', 'http://docs.heroku.com/bundler' + + %h2#deploying-your-application + Deploying Your Application + + .bullet + .description + When you run bundle install, bundler will (by default), install your gems + to your system repository of gems. This means that they will show up in gem + list. Additionally, if you are developing a number of applications, you will not + need to download and install gems in common for each application. This is nice for + development, but somewhat problematic for deployment. + + %p.description + In a deployment scenario, the Unix user you deploy with may not have access to install + gems to a system location. Even if the user does (or you use sudo), the + user that boots the application may not have access to them. For instance, Passenger + runs its Ruby subprocesses with the user nobody, a somewhat restricted + user. The tradeoffs in a deployment environment lean more heavily in favor of isolation + (even at the cost of a somewhat slower deploy-time bundle install when some + third-party dependencies have changed). + + %p.description + As a result, bundler comes with a --deployment flag that encapsulates the + best practices for using bundler in a deployment environment. These practices are based + on significant feedback we have received during the development of bundler, as well as a + number of bug reports that mostly reflected a misunderstanding of how to best configure + bundler for deployment. The --deployment flags adds the following defaults: + + .description + %ul + %li + Instead of installing gems to the system location, bundler will install gems to + vendor/bundle inside your application. Bundler will transparently remember + this location when you invoke it inside your application (with + Bundler.setup and Bundler.require). + %li + Bundler will not use gems already installed to your system, even if they exist. + %li + If you have run bundle pack, checked in the vendor/cache + directory, and do not have any git gems, Bundler will not contact the internet while + installing your bundle. + %li + Bundler will require a Gemfile.lock snapshot, and fail if you did not + provide one. + %li + Bundler will not transparently update your Gemfile.lock if it is out of + date with your Gemfile + + %p.description + If you use Capistrano, you should symlink vendor/bundle to + shared/vendor_bundle so that bundler will share your installed gems between + deployments (making things zippy if you didn't make any changes), but still give you the + benefits of isolation from other applications. + + %p.description + By defaulting the bundle directory to vendor/bundle, and installing your + bundle as part of your deployment process, you can be sure that the same Unix user that + checked out your application also installed the third-party code your application needs. + This means that if Passenger (or Unicorn) can see your application, it can also see its + dependencies. + + %p.description + The --deployment flag requires an up-to-date Gemfile.lock to + ensure that the testing you have done (in development and staging) actually reflects the + code you put into production. You can run bundle check before deploying + your application to make sure that your Gemfile.lock is up-to-date. Note + that it will always be up-to-date if you have run bundle install, + successfully booted your application (or run your tests) since the last time you changed + your Gemfile. diff --git a/source/v1.11/faq.haml b/source/v1.11/faq.haml new file mode 100644 index 0000000000..9ba637e411 --- /dev/null +++ b/source/v1.11/faq.haml @@ -0,0 +1,167 @@ +%h2#faq + FAQ - Frequently Asked Questions +.contents + .bullet + .description + %h3 + Why Can't I Just Specify Only = Dependencies? + %p + Q: I understand the value of locking my gems down + to specific versions, but why can't I just specify = versions + for all my dependencies in the Gemfile and forget about + the Gemfile.lock? + + %p + A: Many of your gems will have their own + dependencies, and they are unlikely to specify = dependencies. + Moreover, it is probably unwise for gems to lock down all of *their* + dependencies so strictly. The Gemfile.lock allows you to + specify the versions of the dependencies that your application needs in + the Gemfile, while remembering all of the exact versions of + third-party code that your application used when it last worked correctly. + + %p + By specifying looser dependencies in your Gemfile + (such as nokogiri ~> 1.4.2), you gain the ability to run + bundle update nokogiri, and let bundler handle updating **only** + nokogiri and its dependencies to the latest version that still + satisfied the ~> 1.4.2 version requirement. This also allows you + to say "I want to use the current version of nokogiri" (gem 'nokogiri' + in your Gemfile) without having to look up the exact version number, + while still getting the benefits of ensuring that your application always runs with + exactly the same versions of all third-party code. + + %h3 + Why Can't I Just Submodule Everything? + + %p + Q: I don't understand why I need bundler to manage + my gems in this manner. Why can't I just get the gems I need and stick them + in submodules, then put each of the submodules on the load path? + + %p + A: Unfortunately, that solution requires that you + manually resolve all of the dependencies in your application, including dependencies + of dependencies. And even once you do that successfully, you would need to redo that + work if you wanted to update a particular gem. For instance, if you wanted to update + the rails gem, you would need to find all of the gems that depended on + dependencies of Rails (rack, erubis, i18n, + tzinfo, etc.), and find new versions that satisfy the new versions of + Rails' requirements. + + %p + Frankly, this is the sort of problem that computers are good at, and which you, + a developer, should not need to spend time doing. + + %p + More concerningly, if you made a mistake in the manual dependency resolution + process, you would not get any feedback about conflicts between different dependencies, + resulting in subtle runtime errors. For instance, if you accidentally stuck the wrong + version of rack in a submodule, it would likely break at runtime, when + Rails or another dependency tried to rely on a method that was not present. + + %p + %strong + Bottom line: + + even though it might seem simpler at first glance, it is decidedly significantly + more complex. + + %h3 + Why Is Bundler Downloading Gems From --without Groups? + + %p + Q: I ran bundle install --without production and + bundler is still downloading the gems in the :production group. Why? + + %p + A: Bundler's Gemfile.lock has to contain exact + versions of all dependencies in your Gemfile, regardless of any options + you pass in. If it did not, deploying your application to production might change all + your dependencies, eliminating the benefit of Bundler. You could no longer be sure that + your application uses the same gems in production that you used to develop and test with. + Additionally, adding a dependency in production might result in an application that is + impossible to deploy. + + %p + For instance, imagine you have a production-only gem (let's call it + rack-debugging) that depends on rack =1.1. If we did not evaluate + the production group when you ran bundle install --without production, you + would deploy your application, only to receive an error that rack-debugging + conflicted with rails (which depends on actionpack, which depends + on rack ~> 1.2.1). + + %p + Another example: imagine a simple Rack application that has gem 'rack' + in the Gemfile. Again, imagine that you put rack-debugging in the + :production group. If we did not evaluate the :production group when + you installed via bundle install --without production, your app would use + rack 1.2.1 in development, and you would learn, at deployment time, that + rack-debugging conflicts with the version of Rack that you tested with. + + %p + In contrast, by evaluating the gems in **all** groups when you call bundle install, + regardless of the groups you actually want to use in that environment, we will discover the + rack-debugger requirement, and install rack 1.1, which is also compatible + with the gem 'rack' requirement in your Gemfile. + + %p + %strong + In short, + by always evaluating all of the dependencies in your Gemfile, regardless of the dependencies + you intend to use in a particular environment, you avoid nasty surprises when switching to a different + set of groups in a different environment. And because we just download (but do not install) the gems, + you won't have to worry about the possibility of a difficult **installation** process for a gem that + you only use in production (or in development). + + %h3 + I Have a C Extension That Requires Special Flags to Install + + %p + Q: I have a C extension gem, such as mysql, which requires + special flags in order to compile and install. How can I pass these flags into the installation + process for those gems? + + %p + A: First of all, this problem does not exist for the mysql2 + gem, which is a drop-in replacement for the mysql gem. In general, modern C extensions + properly discover the needed headers. + + %p + If you really need to pass flags to a C extension, you can use the bundle config + command: + + :code + $ bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config + + %p + Bundler will store this configuration in ~/.bundle/config, and bundler will use + the configuration for any bundle install performed by the same user. As a result, once + you specify the necessary build flags for a gem, you can successfully install that gem as many times + as necessary. + + %h3 + I Do Not Have an Internet Connection and Bundler Keeps Trying to Connect to the Gem Server + %p + Q: I do not have an internet connection but I have installed the gem before. + How do I get bundler to use my local gem cache and not connect to the gem server? + + %p + A: Use the --local flag with bundle install. The --local flag tells bundler + to use the local gem cache instead of reaching out to the remote gem server. + + :code + $ bundle install --local + + %h3 + Bundling From RubyGems is Really Slow + + %p + Q: When I bundle from rubygems it is really slow. Is there anything I can do to make it faster? + + %p + A: Add the --full-index flag when bundling from the rubygems server. This downloads + the index all at once instead of making numerous small requests to the api. + + :code + $ bundle install --full-index diff --git a/source/v1.11/gemfile.haml b/source/v1.11/gemfile.haml new file mode 100644 index 0000000000..9f318f99a6 --- /dev/null +++ b/source/v1.11/gemfile.haml @@ -0,0 +1,155 @@ +%h2 In Depth + +.contents + .bullet + .description + Read the manual for an in-depth discussion of all of the options available in the + Gemfile and how to use them. + = link_to 'Gemfile manual', './man/gemfile.5.html' + +%h2 Gemfiles + +.contents + .bullet + .description + Gemfiles require at least one gem source, in the form of the URL for a RubyGems server. Generate a Gemfile with the default rubygems.org source by running bundle init. If you can, use https so your connection to the rubygems.org server will be verified with SSL. + :code + # lang: ruby + source 'https://rubygems.org' + .notes + It is possible, but not recommended as of Bundler 1.7, to add multiple global source lines. These are searched from last to first. + + .bullet + .description + Some gem sources require a username and password. Use + bundle config to set the username and password for any + 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. + :code + $ bundle config https://gems.example.com/ user:password + .description + For some sources, like a company Gemfury account, it may be easier to + simply include the credentials in the Gemfile as part of the source URL. + :code + # lang: ruby + source "https://user:password@gems.example.com" + .description + Credentials in the source URL will take precedence over credentials set + using config. + + .bullet + .description + Declare the gems that you need, including version numbers. Specify versions using the same + syntax that RubyGems supports for dependencies. + :code + # lang: ruby + gem 'nokogiri' + gem 'rails', '3.0.0.beta3' + gem 'rack', '>=1.0' + gem 'thin', '~>1.1' + .notes + Most of the version specifiers, like >= 1.0, are self-explanatory. + The specifier ~> has a special meaning, best shown by example. + ~> 2.0.3 is identical to >= 2.0.3 and < 2.1. + ~> 2.1 is identical to >= 2.1 and < 3.0. + ~> 2.2.beta will match prerelease versions like 2.2.beta.12. + = link_to 'RubyGems version specifiers', 'http://guides.rubygems.org/patterns/#pessimistic-version-constraint' + + .bullet + .description + If a gem's main file is different than the gem name, specify how to require it. + :code + # lang: ruby + gem 'rspec', :require => 'spec' + gem 'sqlite3' + .description + Specify :require => false to prevent bundler from requiring the gem, but still install it and maintain dependencies. + :code + # lang: ruby + gem 'rspec', :require => false + gem 'sqlite3' + .notes + In order to require gems in your Gemfile, you will need to call + Bundler.require in your application. + = link_to 'Learn More: Bundler.require', './groups.html' + + .bullet + .description + If some of your gems need to be fetched from a private gem server, this default source can be overridden for those gems. + + For a gem server that contains a single gem, it is easiest to use the :source option on that gem. + :code + # lang: ruby + gem 'my_gem', '1.0', :source => 'https://gems.example.com' + .description + If several gems come from the same server, you can use a source block to group them together. + :code + # lang: ruby + source 'https://gems.example.com' do + gem 'my_gem', '1.0' + gem 'another_gem', '1.2.1' + end + .description + Credentials for gem servers can be specified either in the URL or using + bundle config, as described above. + + .bullet + .description + Git repositories are also valid gem sources, as long as the repo contains one or + more valid gems. Specify what to check out with :tag, + :branch, or :ref. The default is the master branch. + :code + # lang: ruby + gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git', :branch => '1.4' + .notes + If the git repository does not contain a .gemspec file, bundler + will create a simple one, without any dependencies, executables or C extensions. + This may work for simple gems, but not work for others. If there is no .gemspec, + you probably shouldn't use the gem from git. + = link_to 'Learn more: Git', './git.html' + + .bullet + .description + If you would like to use a unpacked gem directly from the filesystem, simply set the :path option to the path containing the gem's files. + :code + # lang: ruby + gem 'extracted_library', :path => './vendor/extracted_library' + + .bullet + .description + 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. + :code + # lang: ruby + path 'components' do + gem 'admin_ui' + gem 'public_ui' + end + + .bullet + .description + Dependencies can be placed into groups. Groups can be ignored at install-time (using --without) or required all at once (using Bundler.require). + :code + # lang: ruby + gem 'wirble', :group => :development + gem 'debugger', :group => [:development, :test] + + group :test do + gem 'rspec' + end + = link_to 'Learn more: Groups', './groups.html' + + .bullet + .description + You can specify the required version of Ruby in the Gemfile with ruby. If the Gemfile is loaded on a different Ruby version, Bundler will raise an exception with an explanation. + :code + # lang: ruby + ruby '1.9.3' + + .bullet + .description + What this means is that this app has a dependency to a Ruby VM that is ABI compatible with 1.9.3. If the version check does not match, Bundler will raise an exception. This will ensure the running code matches. You can be more specific with the :engine and :engine_version options. + :code + # lang: ruby + ruby '1.9.3', :engine => 'jruby', :engine_version => '1.6.7' + = link_to 'Learn More: Ruby Directive', './gemfile_ruby.html' diff --git a/source/v1.11/gemfile_ruby.haml b/source/v1.11/gemfile_ruby.haml new file mode 100644 index 0000000000..15fc691d2c --- /dev/null +++ b/source/v1.11/gemfile_ruby.haml @@ -0,0 +1,44 @@ +%h2 Specifying a Ruby Version + +.contents + .bullet + .description + Like gems, developers can setup a dependency on Ruby. This makes your app fail faster in case you depend on specific features in a Ruby VM. This way, the Ruby VM on your deployment server will match your local one. You can do this by using the ruby directive in the Gemfile: + :code + # lang: ruby + ruby 'RUBY_VERSION', :engine => 'ENGINE', :engine_version => 'ENGINE_VERSION', + :patchlevel => 'RUBY_PATCHLEVEL' + + .bullet + .description + If you wanted to use JRuby 1.6.7 using Ruby 1.9.3, you would simply do the following: + :code + # lang: ruby + ruby '1.9.3', :engine => 'jruby', :engine_version => '1.6.7' + + .bullet#patchlevel + .description + It's also possible to restrict the patchlevel of the Ruby used by doing the following: + :code + # lang: ruby + ruby '1.9.3', :patchlevel => '448' + + .bullet + .description + Bundler will make checks against the current running Ruby VM to make sure it matches what is specified in the Gemfile. If things don't match, Bundler will raise an Exception explaining what doesn't match. + :code + Your Ruby version is 1.8.7, but your Gemfile specified 1.9.3 + + .bullet + .description + Both :engine and :engine_version are optional. When these options are omitted, this means the app is compatible with a particular Ruby ABI but the engine is irrelevant. When :engine is used, :engine_version must also be specified. + .bullet + .description + Using the platform command with the --ruby flag, you can see what ruby directive is specified in the Gemfile. + :code + ruby 1.9.3 (jruby 1.6.7) + = link_to 'Learn More: bundle platform', './bundle_platform.html' + + .bullet + .description + In the ruby directive, :patchlevel is optional, as patchlevel releases are usually compatible and include important security fixes. The patchlevel option checks the RUBY_PATCHLEVEL constant, and if not specified then bundler will simply ignore it. diff --git a/source/v1.11/git.haml b/source/v1.11/git.haml new file mode 100644 index 0000000000..5a9a0216b0 --- /dev/null +++ b/source/v1.11/git.haml @@ -0,0 +1,192 @@ +%h2 Gems from git repositories + +.contents + .bullet + .description + Bundler adds the ability to use gems directly from git repositories. Setting + them up is as easy as adding a gem to your Gemfile. Using the very latest + version of a gem (or even a fork) is just as easy as using an official + release. + .description + Because RubyGems lacks the ability to handle gems from git, any gems + installed from a git repository will not show up in gem list. + They will, however, be available after running Bundler.setup. + + .bullet + .description + Specify that a gem should come from a git + repository with a .gemspec at its root + :code + # lang: ruby + gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git' + + .bullet + .description + If there is no .gemspec at the root of + a git repository, you must specify a version + that bundler should use when resolving + dependencies + :code + # lang: ruby + gem 'deep_merge', '1.0', :git => 'https://github.com/peritor/deep_merge.git' + + .bullet + .description + Specify that a git repository containing + multiple .gemspec files should be treated + as a gem source + :code + # lang: ruby + git 'https://github.com/rails/rails.git' do + gem 'railties' + gem 'action_pack' + gem 'active_model' + end + + .bullet + .description + Specify that a git repository should use + a particular ref, branch, or tag + :code + # lang: ruby + :git => 'https://github.com/rails/rails.git', :ref => '4aded' + :git => 'https://github.com/rails/rails.git', :branch => '2-3-stable' + :git => 'https://github.com/rails/rails.git', :tag => 'v2.3.5' + + .bullet + .description + Specifying a ref, branch, or tag for a + git repository specified inline works + exactly the same way + :code + # lang: ruby + gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git', :ref => '0eec4' + + .bullet + .description + Bundler can use HTTP(S), SSH, or git + :code + # lang: ruby + gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git' + gem 'nokogiri', :git => 'git@github.com:tenderlove/nokogiri.git' + gem 'nokogiri', :git => 'git://github.com/tenderlove/nokogiri.git' + + .bullet + .description + Specify that the submodules from a git repository + also should be expanded by bundler + :code + # lang: ruby + gem 'rugged', :git => 'git://github.com/libgit2/rugged.git', :submodules => true + + .bullet + .description + If you are getting your gems from a public GitHub repository, + you can use the shorthand + :code + # lang: ruby + gem 'nokogiri', :github => 'tenderlove/nokogiri' + .description + If the repository name is the same as the GitHub account hosting it, + you can omit it + :code + # lang: ruby + gem 'rails', :github => 'rails' + .description + NB: This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write: + :code + # lang: ruby + gem 'rails', :git => 'https://github.com/rails/rails' + .description + All of the usual :git options apply, like :branch and :ref. + :code + # lang: ruby + gem 'rails', :github => 'rails', :ref => 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56' + .description + There are analogous shortcuts for Bitbucket (:bitbucket) and GitHub Gists (:gist). + :code + # lang: ruby + gem 'capistrano-sidekiq', :github => 'seuros/capistrano-sidekiq' + gem 'keystone', :bitbucket => 'musicone/keystone' + + +%h2 Custom git sources +.contents + .bullet + .description + The :github shortcut used above is one of Bundler's built in git sources. Bundler comes + with shortcuts for :github, :gist, and :bitbucket, but you can + also add your own. + + .description + If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts + by calling git_source before you use your custom option. Here's an example for Stash: + + :code + # lang: ruby + git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" } + gem 'rails', :stash => 'forks/rails' + +%h2 Security +.contents + .bullet + .description + http:// and git:// URLs are insecure. A + man-in-the-middle attacker could tamper with the code as you check it out, + and potentially supply you with malicious code instead of the code you meant to + check out. Because the :github shortcut uses a git:// + URL in Bundler 1.x versions, we recommend using using HTTPS URLs or overriding + the :github shortcut with your own HTTPS git source. + +%h2#local Local Git Repos +.contents + .bullet + .description + 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: + :code + bundle config local.GEM_NAME /path/to/local/git/repository + + .bullet + .description + For example, in order to use a local Rack repository, a developer could call: + :code + bundle config local.rack ~/Work/git/rack + .description + and setup the git repo pointing to a branch: + :code + # lang: ruby + gem 'rack', :github => 'rack/rack', :branch => 'master' + + .bullet + .description + %p + 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. + + %p + 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. + + %p + 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. + + .bullet + .description + %p If you do not want bundler to make these branch checks, you can override it by setting this option: + :code + bundle config disable_local_branch_check true diff --git a/source/v1.11/groups.haml b/source/v1.11/groups.haml new file mode 100644 index 0000000000..d176cff654 --- /dev/null +++ b/source/v1.11/groups.haml @@ -0,0 +1,137 @@ +%h2 Using Groups + +.contents + .bullet + .description + Grouping your dependencies allows you + to perform operations on the entire + group. + :code + # lang: ruby + # These gems are in the :default group + gem 'nokogiri' + gem 'sinatra' + + gem 'wirble', :group => :development + + group :test do + gem 'faker' + gem 'rspec' + end + + group :test, :development do + gem 'capybara' + gem 'rspec-rails' + end + + gem 'cucumber', :group => [:cucumber, :test] + + .bullet + .description + Install all gems, except those in the + listed groups. Gems in at least one + non-excluded group will still be installed. + :code + $ bundle install --without test development + + .bullet + .description + Require the gems in particular groups, + noting that gems outside of a named group + are in the :default group + :code + # lang: ruby + Bundler.require(:default, :development) + + .bullet + .description + Require the default gems, plus the gems + in a group named the same as the current + Rails environment + :code + # lang: ruby + Bundler.require(:default, Rails.env) + + .bullet + .description + Restrict the groups of gems that you + want to add to the load path. Only gems + in these groups will be require'able + :code + # lang: ruby + require 'rubygems' + require 'bundler' + Bundler.setup(:default, :ci) + require 'nokogiri' + = link_to 'Learn More: Bundler.setup', './bundler_setup.html' + + %h2#grouping-your-dependencies + Grouping Your Dependencies + .bullet + .description + You'll sometimes have groups of gems that only make sense in particular environments. + For instance, you might develop your app (at an early stage) using SQLite, but deploy it + using mysql2 or pg. In this example, you might not have MySQL + or Postgres installed on your development machine, and want bundler to skip it. + + To do this, you can group your dependencies: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'rails', '3.2.2' + gem 'rack-cache', :require => 'rack/cache' + gem 'nokogiri', '~> 1.4.2' + + group :development do + gem 'sqlite3' + end + + group :production do + gem 'pg' + end + + .bullet + .description + Now, in development, you can instruct bundler to skip the production group: + + :code + $ bundle install --without production + + .bullet + .description + Bundler will remember that you installed the gems using --without + production. For curious readers, bundler stores the flag in + APP_ROOT/.bundle/config. You can see all of the settings that bundler saved + there by running bundle config, which will also print out global settings + (stored in ~/.bundle/config), and settings set via environment variables. + For more information on configuring bundler, please see: + #{link_to 'bundle config', './bundle_config.html'} + + .bullet + %p.description + If you run bundle install later, without any flags, bundler will remember + that you last called bundle install --without production, and use that flag + again. When you require 'bundler/setup', bundler will ignore gems in these + groups. + + %p.description + You can also specify which groups to automatically require through the parameters to + Bundler.require. The :default group includes all gems not + listed under any group. If you call Bundler.require(:default, :development), + bundler will require all the gems in the :default group, as + well as the gems in the :development group. + + %p.description + By default, a Rails generated app calls Bundler.require(:default, + Rails.env) in your application.rb, which links the groups in your + Gemfile to the Rails environment. If you use other groups (not linked to a + Rails environment), you can add them to the call to Bundler.require, if you + want them to be automatically required. + + %p.description + Remember that you can always leave groups of gems out of Bundler.require, + and then require them manually using Ruby's require at the appropriate + place in your app. You might do this because requiring a certain gem takes some time, + and you don't need it every time you boot your application. diff --git a/source/v1.11/index.haml b/source/v1.11/index.haml new file mode 100644 index 0000000000..170e2f1d04 --- /dev/null +++ b/source/v1.11/index.haml @@ -0,0 +1,140 @@ +%h2 What is Bundler? + +%p#intro + Bundler provides a consistent environment for Ruby projects by tracking + and installing the exact gems and versions that are needed. + %br + %br + Bundler is an exit from dependency hell, and ensures that the gems + you need are present in development, staging, and production. + Starting work on a project is as simple as bundle install. + +.buttons + = link_to 'What\'s new in Bundler', './whats_new.html' + = link_to 'Why Bundler exists', './rationale.html' + +%h2#getting-started + Getting Started + +.contents + .bullet + .description + %p + Getting started with bundler is easy! Open a terminal window and run this command: + :code + $ gem install bundler + + .bullet + .description + %p + Specify your dependencies in a Gemfile in your project's root: + :code + # lang: ruby + source 'https://rubygems.org' + gem 'nokogiri' + gem 'rack', '~>1.1' + gem 'rspec', :require => 'spec' + = link_to 'Learn More: Gemfiles', './gemfile.html' + + .bullet + .description + %p + Install all of the required gems from your specified sources: + :code + $ bundle install + $ git add Gemfile Gemfile.lock + = link_to 'Learn More: bundle install', './bundle_install.html' + .notes + %p + The second command adds the Gemfile and Gemfile.lock to your repository. This ensures + that other developers on your app, as well as your deployment environment, will all use + the same third-party code that you are using now. + + .bullet + .description + %p + Inside your app, load up the bundled environment: + :code + # lang: ruby + require 'rubygems' + require 'bundler/setup' + + # require your gems as usual + require 'nokogiri' + = link_to 'Learn More: Bundler.setup', './bundler_setup.html' + .bullet + .description + %p + Run an executable that comes with a gem in your bundle: + :code + $ bundle exec rspec spec/models + .notes + %p + In some cases, running executables without bundle exec + may work, if the executable happens to be installed in your system + and does not pull in any gems that conflict with your bundle. + %p + However, this is unreliable and is the source of considerable pain. + Even if it looks like it works, it may not work in the future or + on another machine. + + .description + %p + Finally, if you want a way to get a shortcut to gems in your bundle: + :code + $ bundle install --binstubs + $ bin/rspec spec/models + .notes + %p + The executables installed into bin are scoped to the + bundle, and will always work. + = link_to 'Learn More: Executables', './man/bundle-exec.1.html' + +%h2#create-gem Create a rubygem with Bundler + +%p + Bundler is also an easy way to create new gems. Just like you might create a standard Rails project using rails new, you can create a standard gem project with bundle gem. + +.bullet + .description + %p + Create a new gem with a README, .gemspec, Rakefile, directory structure, and all the basic boilerplate you need to describe, test, and publish a gem: + :code + $ bundle gem my_gem + Creating gem 'my_gem'... + create my_gem/Gemfile + create my_gem/.gitignore + create my_gem/lib/my_gem.rb + create my_gem/lib/my_gem/version.rb + create my_gem/my_gem.gemspec + create my_gem/Rakefile + create my_gem/README.md + create my_gem/bin/console + create my_gem/bin/setup + create my_gem/CODE_OF_CONDUCT.md + create my_gem/LICENSE.txt + create my_gem/.travis.yml + create my_gem/test/test_helper.rb + create my_gem/test/my_gem_test.rb + Initializing git repo in ./my_gem + + = link_to 'Learn More: bundle gem', './bundle_gem.html' + +%h2#use-bundler Use Bundler with +.buttons + = link_to 'Rails 3', './rails3.html' + = link_to 'Rails 2.3', './rails23.html' + = link_to 'Sinatra', './sinatra.html' + = link_to 'RubyGems', './rubygems.html' + = link_to 'RubyMotion', './rubymotion.html' + +%h2#get-involved Get involved +%p + Bundler has a lot of contributors and users, and they all talk to each other quite a bit. If you have questions, try #{link_to 'the IRC channel', 'http://webchat.freenode.net/?channels=bundler'} or #{link_to 'mailing list', 'http://groups.google.com/group/ruby-bundler'}. If you're interested in contributing to the project (no programming skills needed), read #{link_to 'the contributing guide', 'https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md'}. While participating in the Bundler project, please keep the #{link_to 'code of conduct', '/conduct.html'} in mind, and be inclusive and friendly towards everyone. If you have sponsorship or security questions, please contact the core team directly. + +.buttons + = link_to 'Code of Conduct', '/conduct.html' + = link_to '#bundler on IRC', 'http://webchat.freenode.net/?channels=bundler' + = link_to 'Mailing list', 'http://groups.google.com/group/ruby-bundler' + = link_to 'Contributing', 'https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md' + = link_to 'Email core team', 'mailto:team@bundler.io' diff --git a/source/v1.11/rails23.haml b/source/v1.11/rails23.haml new file mode 100644 index 0000000000..280641fa08 --- /dev/null +++ b/source/v1.11/rails23.haml @@ -0,0 +1,104 @@ +#intro + Rails 2.3 comes with its own gem handling. We're going to + override that and replace it with support for Bundler. + .notes + NB: This may work with Rails versions lower than 2.3. + The Bundler team has not tested those versions, and will not provide + support for anyone on Rails older than 2.3, but feel free to try it. :) + + +%h2 Using Bundler with Rails 2.3 + +.contents + + .bullet + .description + If you don't have a Rails 2.3 app yet, generate one + :code + $ rails myapp + $ cd myapp + + .bullet + .description + Insert the following code at the bottom of config/boot.rb, + right above the line `Rails.boot!` + :code + # lang: ruby + class Rails::Boot + def run + load_initializer + + Rails::Initializer.class_eval do + def load_gems + @bundler_loaded ||= Bundler.require :default, Rails.env + end + end + + Rails::Initializer.run(:set_load_path) + end + end + + .bullet + .description + Create a new file, config/preinitializer.rb, + and insert the following. That is config NOT + config/initializers. + :code + # lang: ruby + begin + require 'rubygems' + require 'bundler' + rescue LoadError + raise "Could not load the bundler gem. Install it with `gem install bundler`." + end + + if Gem::Version.new(Bundler::VERSION) <= Gem::Version.new("0.9.24") + raise RuntimeError, "Your bundler version is too old for Rails 2.3.\n" + + "Run `gem install bundler` to upgrade." + end + + begin + # Set up load paths for all bundled gems + ENV["BUNDLE_GEMFILE"] = File.expand_path("../../Gemfile", __FILE__) + Bundler.setup + rescue Bundler::GemNotFound + raise RuntimeError, "Bundler couldn't find some gems.\n" + + "Did you run `bundle install`?" + end + + .bullet + .description + Get all config.gem declarations from your application, and place + them into the Gemfile. If you have declarations in development.rb, + for instance, place them in a named group. Make sure to include + Rails itself and a default gem source. + :code + # lang: ruby + source 'https://rubygems.org' + gem 'rails', '~> 2.3.5' + gem 'sqlite3-ruby', :require => 'sqlite3' + + # bundler requires these gems in all environments + # gem 'nokogiri', '1.4.2' + # gem 'geokit' + + group :development do + # bundler requires these gems in development + # gem 'rails-footnotes' + end + + group :test do + # bundler requires these gems while running tests + # gem 'rspec' + # gem 'faker' + end + = link_to 'Learn More: Groups', './groups.html' + + .bullet + .description + Once you have everything set up, you can use script/console, + script/server, and other Rake tasks as usual. From this point + on, you can follow the instructions in the Rails 3 guide + :code + $ bundle exec rake db:migrate + = link_to 'Learn More: Rails 3', './rails3.html#shared_with_23' diff --git a/source/v1.11/rails3.haml b/source/v1.11/rails3.haml new file mode 100644 index 0000000000..e68b6599b6 --- /dev/null +++ b/source/v1.11/rails3.haml @@ -0,0 +1,76 @@ +#intro + Rails 3 comes with baked in support with bundler. + +%h2 Using Bundler with Rails 3 + +.contents + .bullet + .description + Install Rails as you normally would. Use sudo + if you would normally use sudo to install gems. + .how + :code + $ gem install rails + .notes + We recommend using rvm for dependable Ruby + installations, especially if you are switching + between different versions of Ruby + + .bullet + .description + Generate a Rails app as usual + :code + $ rails new myapp + $ cd myapp + + .bullet + .description + Run the server. Bundler is transparently managing + your dependencies! + :code + $ rails server + + .bullet + .description + Add new dependencies to your Gemfile as you + need them. + :code + # lang: ruby + gem 'nokogiri' + gem 'geokit' + + .bullet + .description + If you want a dependency to be loaded only in + a certain Rails environment, place it in a group + named after that Rails environment + :code + # lang: ruby + group :test do + gem 'rspec' + gem 'faker' + end + + .bullet#shared_with_23 + .description + You can place a dependency in multiple groups + at once as well + :code + # lang: ruby + group :development, :test do + gem 'wirble' + gem 'ruby-debug' + end + = link_to 'Learn More: Groups', './groups.html' + + .bullet + .description + After adding a dependency, if it is not yet + installed, install it + .how + :code + $ bundle install + .notes + This will update all dependencies in your + Gemfile to the latest versions that do not + conflict with other dependencies diff --git a/source/v1.11/rationale.haml b/source/v1.11/rationale.haml new file mode 100644 index 0000000000..ff935ea63a --- /dev/null +++ b/source/v1.11/rationale.haml @@ -0,0 +1,427 @@ +#intro + If you just want to know our recommended workflow, and don't care about the rationale, feel + free to jump to the summary below. +%br + +#standalone + %h2#bundlers-purpose-and-rationale + Bundler's Purpose and Rationale + %p + First, you declare these dependencies in a file at the root of your application, called + Gemfile. It looks something like this: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'rails', '4.1.0.rc2' + gem 'rack-cache' + gem 'nokogiri', '~> 1.6.1' + + %p + This Gemfile says a few things. First, it says that bundler should look for gems + declared in the Gemfile at https://rubygems.org by default. If some + of your gems need to be fetched from a private gem server, this default source can be overridden + for those gems. + + %p + Next, you declare a few dependencies: + + %ul + %li on version 4.1.0.rc2 of rails + %li on any version of rack-cache + %li on a version of nokogiri that is >= 1.6.1 but < 1.7.0 + + %p + After declaring your first set of dependencies, you tell bundler to go get them: + + :code + $ bundle install # 'bundle' is a shortcut for 'bundle install' + + %p + Bundler will connect to rubygems.org (and any other sources that you declared), + and find a list of all of the required gems that meet the requirements you specified. Because + all of the gems in your Gemfile have dependencies of their own (and some of + those have their own dependencies), running bundle install on the + Gemfile above will install quite a few gems. + + :code + $ bundle install + Fetching gem metadata from https://rubygems.org/......... + Fetching additional metadata from https://rubygems.org/.. + Resolving dependencies... + Using rake 10.3.1 + Using json 1.8.1 + Installing minitest 5.3.3 + Installing i18n 0.6.9 + Installing thread_safe 0.3.3 + Installing builder 3.2.2 + Installing rack 1.5.2 + Installing erubis 2.7.0 + Installing mime-types 1.25.1 + Using bundler 1.6.2 + Installing polyglot 0.3.4 + Installing arel 5.0.1.20140414130214 + Installing hike 1.2.3 + Installing mini_portile 0.5.3 + Installing multi_json 1.9.3 + Installing thor 0.19.1 + Installing tilt 1.4.1 + Installing tzinfo 1.1.0 + Installing rack-test 0.6.2 + Installing rack-cache 1.2 + Installing treetop 1.4.15 + Installing sprockets 2.12.1 + Installing activesupport 4.1.0.rc2 + Installing mail 2.5.4 + Installing actionview 4.1.0.rc2 + Installing activemodel 4.1.0.rc2 + Installing actionpack 4.1.0.rc2 + Installing activerecord 4.1.0.rc2 + Installing actionmailer 4.1.0.rc2 + Installing sprockets-rails 2.0.1 + Installing railties 4.1.0.rc2 + Installing rails 4.1.0.rc2 + Installing nokogiri 1.6.1 + Your bundle is complete! + Use `bundle show [gemname]` to see where a bundled gem is installed. + + %p + If any of the needed gems are already installed, Bundler will use them. After installing + any needed gems to your system, bundler writes a snapshot of all of the gems and + versions that it installed to Gemfile.lock. + + %h2#setting-up-your-application-to-use-bundler + Setting Up Your Application to Use Bundler + + %p + Bundler makes sure that Ruby can find all of the gems in the Gemfile + (and all of their dependencies). If your app is a Rails 3+ app, your default application + already has the code necessary to invoke bundler. If it is a Rails 2.3 app, please see + Setting up Bundler in Rails 2.3. + + %p + For another kind of application (such as a Sinatra application), you will need to set up + bundler before trying to require any gems. At the top of the first file that your + application loads (for Sinatra, the file that calls require 'sinatra'), put + the following code: + + :code + # lang: ruby + require 'rubygems' + require 'bundler/setup' + + %p + This will automatically discover your Gemfile, and make all of the gems in + your Gemfile available to Ruby (in technical terms, it puts the gems "on the + load path"). You can think of it as an adding some extra powers to require + 'rubygems'. + + %p + Now that your code is available to Ruby, you can require the gems that you need. For + instance, you can require 'sinatra'. If you have a lot of dependencies, you + might want to say "require all of the gems in my Gemfile". To do this, put + the following code immediately following require 'bundler/setup': + + :code + # lang: ruby + Bundler.require(:default) + + For our example Gemfile, this line is exactly equivalent to: + + :code + # lang: ruby + require 'rails' + require 'rack-cache' + require 'nokogiri' + + %p + Astute readers will notice that the correct way to require the rack-cache + gem is require 'rack/cache', not require 'rack-cache'. To tell + bundler to use require 'rack/cache', update your Gemfile: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'rails', '4.1.0.rc2' + gem 'rack-cache', require: 'rack/cache' + gem 'nokogiri', '~> 1.6.1' + + %p + For such a small Gemfile, we'd advise you to skip + Bundler.require and just require the gems by hand (especially given the + need to put in a :require directive in the Gemfile). For much + larger Gemfiles, using Bundler.require allows you to skip + repeating a large stack of requirements. + + %h2#checking-your-code-into-version-control + Checking Your Code into Version Control + + %p + After developing your application for a while, check in the application together with + the Gemfile and Gemfile.lock snapshot. Now, your repository + has a record of the exact versions of all of the gems that you used the last time you + know for sure that the application worked. Keep in mind that while your + Gemfile lists only three gems (with varying degrees of version strictness), + your application depends on dozens of gems, once you take into consideration all of the + implicit requirements of the gems you depend on. + + %p + This is important: the Gemfile.lock makes your application a single + package of both your own code and the third-party code it ran the last time you know for + sure that everything worked. Specifying exact versions of the third-party code + you depend on in your Gemfile would not provide the same guarantee, because + gems usually declare a range of versions for their dependencies. + + %p + The next time you run bundle install on the same machine, bundler will see + that it already has all of the dependencies you need, and skip the installation process. + + %p + Do not check in the .bundle directory, or any of the files inside it. Those + files are specific to each particular machine, and are used to persist installation options + between runs of the bundle install command. + + %p + If you have run bundle pack, the gems (although not the git gems) required + by your bundle will be downloaded into vendor/cache. Bundler can run without + connecting to the internet (or the RubyGems server) if all the gems you need are present + in that folder and checked in to your source control. This is an optional + step, and not recommended, due to the increase in size of your source control repository. + + %h2#sharing-your-application-with-other-developers + Sharing Your Application With Other Developers + + %p + When your co-developers (or you on another machine) check out your code, it will come + with the exact versions of all the third-party code your application used on the machine + that you last developed on (in the Gemfile.lock). When **they** run + bundle install, bundler will find the Gemfile.lock and skip + the dependency resolution step. Instead, it will install all of the same gems that you + used on the original machine. + + %p + In other words, you don't have to guess which versions of the dependencies you should + install. In the example we've been using, even though rack-cache declares a + dependency on rack >= 0.4, we know for sure it works with rack + 1.5.2. Even if the Rack team releases rack 1.5.3, bundler will + always install 1.5.2, the exact version of the gem that we know works. This + relieves a large maintenance burden from application developers, because all machines + always run the exact same third-party code. + + %h2#updating-a-dependency + Updating a Dependency + + %p + Of course, at some point, you might want to update the version of a particular + dependency your application relies on. For instance, you might want to update + rails to 4.1.0 final. Importantly, just because you're + updating one dependency, it doesn't mean you want to re-resolve all of your dependencies + and use the latest version of everything. In our example, you only have three + dependencies, but even in this case, updating everything can cause complications. + + %p + To illustrate, the rails 4.1.0.rc2 gem depends on actionpack + 4.1.0.rc2 gem, which depends on rack ~> 1.5.2 (which means >= + 1.5.2 and < 1.6.0). The rack-cache gem depends on + rack >= 0.4. Let's assume that the rails 4.1.0 final gem also + depends on rack ~> 1.5.2, and that since the release of rails + 4.1.0, the Rack team released rack 1.5.3. + + %p + If we naïvely update all of our gems in order to update Rails, we'll get rack + 1.5.3, which satisfies the requirements of both rails 4.1.0 and + rack-cache. However, we didn't specifically ask to update + rack-cache, which may not be compatible with rack 1.5.3 (for + whatever reason). And while an update from rack 1.5.2 to rack + 1.5.3 probably won't break anything, similar scenarios can happen that involve + much larger jumps. (see [1] below for a larger discussion) + + %p + In order to avoid this problem, when you update a gem, bundler will not update a + dependency of that gem if another gem still depends on it. In this example, since + rack-cache still depends on rack, bundler will not update the + rack gem. This ensures that updating rails doesn't + inadvertently break rack-cache. Since rails 4.1.0's dependency + actionpack 4.1.0 remains compatible with rack 1.5.2, bundler + leaves it alone, and rack-cache continues to work even in the face of an + incompatibility with rack 1.5.3. + + %p + Since you originally declared a dependency on rails 4.1.0.rc2, if you want + to update to rails 4.1.0, simply update your Gemfile to + gem 'rails', '4.1.0' and run: + + :code + $ bundle install + + %p + As described above, the bundle install command always does a conservative + update, refusing to update gems (or their dependencies) that you have not explicitly + changed in the Gemfile. This means that if you do not modify + rack-cache in your Gemfile, bundler will treat it **and its + dependencies** (rack) as a single, unmodifiable unit. If rails + 3.0.0 was incompatible with rack-cache, bundler will report a + conflict between your snapshotted dependencies (Gemfile.lock) and your + updated Gemfile. + + %p + If you update your Gemfile, and your system already has all of the needed + dependencies, bundler will transparently update the Gemfile.lock when you + boot your application. For instance, if you add mysql to your + Gemfile, and have already installed it in your system, you can boot your + application without running bundle install, and bundler will persist the + "last known good" configuration to the Gemfile.lock snapshot. + + %p + This can come in handy when adding or updating gems with minimal dependencies (database + drivers, wirble, ruby-debug). It will probably fail if you + update gems with significant dependencies (rails), or that a lot of gems + depend on (rack). If a transparent update fails, your application will fail + to boot, and bundler will print out an error instructing you to run bundle + install. + + %h2#updating-a-gem-without-modyfying-the-gemfile + Updating a Gem Without Modifying the Gemfile + + %p + Sometimes, you want to update a dependency without modifying the Gemfile. For example, + you might want to update to the latest version of rack-cache. Because you + did not declare a specific version of rack-cache in the + Gemfile, you might want to periodically get the latest version of + rack-cache. To do this, you want to use the bundle update + command: + + :code + $ bundle update rack-cache + + %p + This command will update rack-cache and its dependencies to the latest + version allowed by the Gemfile (in this case, the latest version + available). It will not modify any other dependencies. + + %p + It will, however, update dependencies of other gems if necessary. For instance, if the + latest version of rack-cache specifies a dependency on rack >= + 1.5.2, bundler will update rack to 1.5.2 even though + you have not asked bundler to update rack. If bundler needs to update a + gem that another gem depends on, it will let you know after the update has completed. + + %p + If you want to update every gem in the Gemfile to the latest possible versions, run: + + :code + $ bundle update + + %p + This will resolve dependencies from scratch, ignoring the Gemfile.lock. If + you do this, keep git reset --hard and your test suite in your back pocket. + Resolving all dependencies from scratch can have surprising results, especially if a + number of the third-party packages you depend on have released new versions since you + last did a full update. + + %h2#summary + Summary + %h2 A Simple Bundler Workflow + + %ul + %li + %p + When you first create a Rails application, it already comes with a + Gemfile. For another kind of application (such as Sinatra), run: + + :code + $ bundle init + + %p + The bundle init command creates a simple Gemfile which you + can edit. + + %li + %p + Next, add any gems that your application depends on. If you care which version of a + particular gem that you need, be sure to include an appropriate version restriction: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'sinatra', '~> 1.3.6' + gem 'rack-cache' + gem 'rack-bug' + + %li + %p + If you don't have the gems installed in your system yet, run: + + :code + $ bundle install + + %li + %p + To update a gem's version requirements, first modify the Gemfile: + + :code + # lang: ruby + source 'https://rubygems.org' + + gem 'sinatra', '~> 1.4.5' + gem 'rack-cache' + gem 'rack-bug' + + %p + and then run: + + :code + $ bundle install + + %li + %p + If bundle install reports a conflict between your Gemfile + and Gemfile.lock, run: + + :code + $ bundle update sinatra + + %p + This will update just the Sinatra gem, as well as any of its dependencies. + + %li + %p + To update all of the gems in your Gemfile to the latest possible + versions, run: + + :code + $ bundle update + + %li + Whenever your Gemfile.lock changes, always check it in to version + control. It keeps a history of the exact versions of all third-party code that you + used to successfully run your application. + + %li + %p + When deploying your code to a staging or production server, first run your tests (or + boot your local development server), make sure you have checked in your + Gemfile.lock to version control. On the remote server, run: + + :code + $ bundle install --deployment + + %h2#notes + Notes + + %p + [1] For instance, if rails 4.1.0 depended on rack 2.0, that + gem would still satisfy the requirement of rack-cache, which declares + >= 0.4 as a dependency. Of course, you could argue that + rack-cache is silly for depending on open-ended versions, but these + situations exist (extensively) in the wild, and projects often find themselves between a + rock and a hard place when deciding what version to depend on. Constrain the dependency + too much (rack =1.5.1) and you make it hard to use your project in other + compatible projects. Constrain it too little (rack >= 1.0) and a new + release of Rack may break your code. Using dependencies like rack ~> 1.5.2 + and versioning code in a SemVer compliant way mostly solves this problem, but it assumes + universal compliance. Since RubyGems has over 100,000 packages, this assumption simply + doesn't hold in practice. diff --git a/source/v1.11/rubygems.haml b/source/v1.11/rubygems.haml new file mode 100644 index 0000000000..b57581a3aa --- /dev/null +++ b/source/v1.11/rubygems.haml @@ -0,0 +1,51 @@ +%h2 Using Bundler with Rubygem gemspecs + +.contents + .bullet + .description + If you're creating a gem from scratch, you can use bundler's built in gem skeleton to create a base gem for you to edit. + .how + :code + $ bundle gem my_gem + .notes + This will create a new directory named my_gem with your new gem skeleton. + + .bullet + .description + If you already have a gem with a gemspec, you can generate a Gemfile for your gem. + :code + $ bundle init + .notes + Then, add the following to your new Gemfile + :code + # lang: ruby + gemspec + + .bullet + .description + Runtime dependencies in your gemspec are treated like base dependencies, and development dependencies are added by default to the group, :development. You can change that group with the :development_group option + :code + # lang: ruby + gemspec :development_group => :dev + + .bullet + .description + As well, you can point to a specific gemspec using :path. If your gemspec is in /gemspec/path, use + :code + # lang: ruby + gemspec :path => '/gemspec/path' + + .bullet + .description + If you have multiple gemspecs in the same directory, specify which one you'd like to reference using :name + :code + # lang: ruby + gemspec :name => 'my_awesome_gem' + .notes + This will use my_awesome_gem.gemspec + + .bullet + .description + That's it! Use bundler when developing your gem, and otherwise, use gemspecs normally! + :code + $ gem build my_gem.gemspec diff --git a/source/v1.11/rubymotion.haml b/source/v1.11/rubymotion.haml new file mode 100644 index 0000000000..8d3cbdc3d1 --- /dev/null +++ b/source/v1.11/rubymotion.haml @@ -0,0 +1,36 @@ +%h2 Using Bundler with RubyMotion +.contents + .bullet + .description + If you don't have a RubyMotion app yet, generate one. + :code + $ motion create myapp + $ cd myapp + .bullet + .description + You'll need to create a Gemfile. Here we're using bubblewrap. + :code + # lang: ruby + gem 'bubble-wrap' + + .bullet + .description + Then, set up your Rakefile to require your bundled gems at compile time. + Add this to the top of the file, right beneath the line `require 'motion/project'` + :code + # lang: ruby + require 'bundler' + + Bundler.require + + .bullet + .description + Next, install your dependencies: + :code + $ bundle install + + .bullet + .description + Now you can just compile your app as normal. + :code + $ bundle exec rake diff --git a/source/v1.11/sinatra.haml b/source/v1.11/sinatra.haml new file mode 100644 index 0000000000..f5d934182d --- /dev/null +++ b/source/v1.11/sinatra.haml @@ -0,0 +1,28 @@ +%h2 Using Bundler with Sinatra + +.contents + .bullet + .description + To use bundler with a Sinatra application, you only need to do two things. First, create a Gemfile. + :code + # lang: ruby + gem 'sinatra' + + .bullet + .description + Then, set up your config.ru file to load the bundle before it loads your Sinatra app. + :code + # lang: ruby + require 'rubygems' + require 'bundler' + + Bundler.require + + require './my_sinatra_app' + run MySinatraApp + + .bullet + .description + Start your development server with rackup, and Sinatra will be loaded via Bundler. + :code + $ bundle exec rackup diff --git a/source/v1.11/updating_gems.haml b/source/v1.11/updating_gems.haml new file mode 100644 index 0000000000..37fc25ead7 --- /dev/null +++ b/source/v1.11/updating_gems.haml @@ -0,0 +1,116 @@ +%h2 Updating Gems +.contents + .bullet + .description + %h3#updating-a-dependency + Updating a Dependency + + %p.description + Of course, at some point, you might want to update the version of a particular + dependency your application relies on. For instance, you might want to update + rails to 3.0.0 final. Importantly, just because you're + updating one dependency, it doesn't mean you want to re-resolve all of your dependencies + and use the latest version of everything. In our example, you only have three + dependencies, but even in this case, updating everything can cause complications. + + %p.description + To illustrate, the rails 3.0.0.rc gem depends on actionpack + 3.0.0.rc gem, which depends on rack ~> 1.2.1 (which means >= + 1.2.1 and < 1.3.0). The rack-cache gem depends on + rack >= 0.4. Let's assume that the rails 3.0.0 final gem also + depends on rack ~> 1.2.1, and that since the release of rails + 3.0.0, the Rack team released rack 1.2.2. + + %p.description + If we naïvely update all of our gems in order to update Rails, we'll get rack + 1.2.2, which satisfies the requirements of both rails 3.0.0 and + rack-cache. However, we didn't specifically ask to update + rack-cache, which may not be compatible with rack 1.2.2 (for + whatever reason). And while an update from rack 1.2.1 to rack + 1.2.2 probably won't break anything, similar scenarios can happen that involve + much larger jumps. (see [1] below for a larger discussion) + + %p.description + In order to avoid this problem, when you update a gem, bundler will not update a + dependency of that gem if another gem still depends on it. In this example, since + rack-cache still depends on rack, bundler will not update the + rack gem. This ensures that updating rails doesn't + inadvertently break rack-cache. Since rails 3.0.0's dependency + actionpack 3.0.0 remains compatible with rack 1.2.1, bundler + leaves it alone, and rack-cache continues to work even in the face of an + incompatibility with rack 1.2.2. + + %p.description + Since you originally declared a dependency on rails 3.0.0.rc, if you want + to update to rails 3.0.0, simply update your Gemfile to + gem 'rails', '3.0.0' and run: + + :code + $ bundle install + + %p.description + As described above, the bundle install command always does a conservative + update, refusing to update gems (or their dependencies) that you have not explicitly + changed in the Gemfile. This means that if you do not modify + rack-cache in your Gemfile, bundler will treat it **and its + dependencies** (rack) as a single, unmodifiable unit. If rails + 3.0.0 was incompatible with rack-cache, bundler will report a + conflict between your snapshotted dependencies (Gemfile.lock) and your + updated Gemfile. + + %p.description + If you update your Gemfile, and your system already has all of the needed + dependencies, bundler will transparently update the Gemfile.lock when you + boot your application. For instance, if you add mysql to your + Gemfile, and have already installed it in your system, you can boot your + application without running bundle install, and bundler will persist the + "last known good" configuration to the Gemfile.lock snapshot. + + %p.description + This can come in handy when adding or updating gems with minimal dependencies (database + drivers, wirble, ruby-debug). It will probably fail if you + update gems with significant dependencies (rails), or that a lot of gems + depend on (rack). If a transparent update fails, your application will fail + to boot, and bundler will print out an error instructing you to run bundle + install. + + .bullet + .description + %h3#updating-a-gem-without-modifying-the-gemfile + Updating a Gem Without Modifying the Gemfile + + %p + Sometimes, you want to update a dependency without modifying the Gemfile. For example, + you might want to update to the latest version of rack-cache. Because you + did not declare a specific version of rack-cache in the + Gemfile, you might want to periodically get the latest version of + rack-cache. To do this, you want to use the bundle update + command: + + :code + $ bundle update rack-cache + + %p + This command will update rack-cache and its dependencies to the latest + version allowed by the Gemfile (in this case, the latest version + available). It will not modify any other dependencies. + + %p + It will, however, update dependencies of other gems if necessary. For instance, if the + latest version of rack-cache specifies a dependency on rack >= + 1.2.2, bundler will update rack to 1.2.2 even though + you have not asked bundler to update rack. If bundler needs to update a + gem that another gem depends on, it will let you know after the update has completed. + + %p + If you want to update every gem in the Gemfile to the latest possible versions, run: + + :code + $ bundle update + + %p + This will resolve dependencies from scratch, ignoring the Gemfile.lock. If + you do this, keep git reset --hard and your test suite in your back pocket. + Resolving all dependencies from scratch can have surprising results, especially if a + number of the third-party packages you depend on have released new versions since you + last did a full update. diff --git a/source/v1.11/whats_new.haml b/source/v1.11/whats_new.haml new file mode 100644 index 0000000000..0552610ad1 --- /dev/null +++ b/source/v1.11/whats_new.haml @@ -0,0 +1,39 @@ += partial "shared/whats_new" + +%h2#version111 What's New in v1.11 + +%h2#version110 What's New in v1.10 + +.contents + .bullet + .description + %p + Bundler 1.10 comes with a new `lock` command, support for inline gemfiles in scripts, the ability to disable post-install messages, optional groups, conditional gem installation, dramatically improved `outdated` output, and the option to force installed gems to be downloaded and installed again. + %p + In this section, you’ll find the major features introduced in this release. All the changes are documented in the Bundler 1.11 changelog. + = link_to 'Full 1.10 changelog', 'https://github.com/bundler/bundler/blob/1-11-stable/CHANGELOG.md' + +%h2#error-messages Improved error messages + +.contents + .bullet + .description + %p + Bundler now provides more helpful error messages in 90% of known error cases, avoiding showing a backtrace whenever possible. + +%h2#git-credentials Git Credentials + +.contents + .bullet + .description + %p + Bundler now allows specifying custom git credentials via bundle config. + +.contents + .bullet + .description + Bundler 1.11 also includes: + %ul + %li faster dependency resolution + %li timeouts and retries are now configurable + = link_to 'Full 1.10 changelog', 'https://github.com/bundler/bundler/blob/1-10-stable/CHANGELOG.md' From 330e947e79e045a8b9bec54687f316598a578c0c Mon Sep 17 00:00:00 2001 From: Andre Arko Date: Sun, 13 Dec 2015 11:35:30 +0800 Subject: [PATCH 2/3] add 1.11 to the layout etc --- Rakefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Rakefile b/Rakefile index 64c6578043..735d1059c0 100644 --- a/Rakefile +++ b/Rakefile @@ -9,7 +9,7 @@ task :update_vendor => ["vendor/bundler"] do Dir.chdir("vendor/bundler") { sh "git fetch" } end -VERSIONS = %w(v1.0 v1.1 v1.2 v1.3 v1.5 v1.6 v1.7 v1.8 v1.9 v1.10).freeze +VERSIONS = %w(v1.0 v1.1 v1.2 v1.3 v1.5 v1.6 v1.7 v1.8 v1.9 v1.10 v1.11).freeze desc "Print the Bundler versions the site documents" task :versions do puts VERSIONS.join(' ') From 5253e518551e1323aa8f8ccf1f13957c27ed94a8 Mon Sep 17 00:00:00 2001 From: Andre Arko Date: Sun, 13 Dec 2015 11:35:45 +0800 Subject: [PATCH 3/3] =?UTF-8?q?update=201.11=20what=E2=80=99s=20new?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/v1.11/whats_new.haml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/v1.11/whats_new.haml b/source/v1.11/whats_new.haml index 0552610ad1..bb9dcce1e5 100644 --- a/source/v1.11/whats_new.haml +++ b/source/v1.11/whats_new.haml @@ -2,38 +2,38 @@ %h2#version111 What's New in v1.11 -%h2#version110 What's New in v1.10 +%h3#error-messages Improved permissions errors .contents .bullet .description %p - Bundler 1.10 comes with a new `lock` command, support for inline gemfiles in scripts, the ability to disable post-install messages, optional groups, conditional gem installation, dramatically improved `outdated` output, and the option to force installed gems to be downloaded and installed again. - %p - In this section, you’ll find the major features introduced in this release. All the changes are documented in the Bundler 1.11 changelog. - = link_to 'Full 1.10 changelog', 'https://github.com/bundler/bundler/blob/1-11-stable/CHANGELOG.md' + Bundler now provides a helpful error message for all sorts of permissions errors that used to cause an exception and show a backtrace. -%h2#error-messages Improved error messages +%h3#git-credentials Git Credentials .contents .bullet .description %p - Bundler now provides more helpful error messages in 90% of known error cases, avoiding showing a backtrace whenever possible. + Bundler now allows specifying custom git credentials via bundle config. -%h2#git-credentials Git Credentials +%h3#lock-update Update gems without installing them .contents .bullet .description %p - Bundler now allows specifying custom git credentials via bundle config. + It is now possible to update the locked version of a gem without also installing it, by running bundle lock --update [GEM [GEM ...]] to update the versions of some gems (or all gems). .contents .bullet .description Bundler 1.11 also includes: %ul - %li faster dependency resolution - %li timeouts and retries are now configurable - = link_to 'Full 1.10 changelog', 'https://github.com/bundler/bundler/blob/1-10-stable/CHANGELOG.md' + %li up to 25x faster dependency resolution + %li vastly improved resolver conflict messages + %li configurable timeouts and retries + %li configurable git remote and gem server for `rake release` + %li many, many, many bugfixes + = link_to 'Full 1.11 changelog', 'https://github.com/bundler/bundler/blob/1-11-stable/CHANGELOG.md'