= gem Command Reference

 The <tt>gem</tt> command is the main user interface to the RubyGems packaging
 system. This document provides a reference to the <tt>gem</tt> command and its
 options.

== Overview

=== Introduction

 gem is the command-line interface to RubyGems. With it, you can install gems
 locally or remotely, see what you have installed, search for gems, and more.

 It works on the following basis: you specify an operation and optionally some
 modifiers. Finally, you can have a configuration file to specify commonly-used
 command-line arguments and other settings.

 See the QuickIntroduction for a task-driven hands-on overview of gem's main
 features.

 This reference covers 'gem' version 0.8.7.

=== Getting Help

 <tt>gem</tt> is based on ''commands'', like <tt>build</tt>, <tt>install</tt>,
 and <tt>search</tt>. See the Table of Contents for a full list.

 Each command takes ''arguments'' and/or ''options''. For example, if you run

 gem install rake --remote

 then <tt>install</tt> is the command, <tt>rake</tt> is the argument, and
 <tt>--remote</tt> is an option. (By the way, this command installs rake
 remotely.)

 <tt>gem</tt> provides most of the help you need inline. * <b>To see a list of
 commands</b>, run <tt>gem help commands</tt>. * <b>To get help on the
 <em>install</em> command</b>, run <tt>gem help install</tt>. * <b>To see some
 examples of common usage</b>, run <tt>gem help examples</tt>. * <b>For a
 reminder of all this</b>, just run <tt>gem help</tt>.

 The help on each command is also included in this document.

== Command Reference

=== <tt>gem build</tt> -- Build a gem file from a specification

 The build command is used by developers to package their Ruby software into a
 single gem file that can be distributed. The build command requires a gemspec
 file to describe the metadata in the packge. You can see a good example of
 using build in CreateAGemInTenMinutes. A yaml file containing the
 Gem::Specification object built by a gemspec (instead of a gemspec file) may
 also be also be used with the build command. h3. Usage <pre> Usage: gem build
 GEMSPEC_FILE [options] Common Options: --source URL Use URL as the remote
 source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: GEMSPEC_FILE name of gemspec file
 used to build the gem Summary: Build a gem from a gemspec </pre> h3. Examples
 This example builds a the rake package from a gemspec file. <pre> $ gem build
 rake.gemspec Attempting to build gem spec 'rake.gemspec' Successfully built
 RubyGem Name: rake Version: 0.4.0 File: rake-0.4.0.gem </pre> Of course, rake
 isn't normally built from a gemspec. It uses a special gem building task to
 build the gem directly from the rakefile. See CreateAGemUsingRake for more
 details. <pre> $ rake gem (in /home/jim/working/rubyforge/rake) Successfully
 built RubyGem Name: rake Version: 0.4.0 File: rake-0.4.0.gem </pre>

 <hr/>

=== <tt>gem cert</tt> -- Support signing and managing signed gems

 The cert command manages the certificates needed to sign gems. h3. Usage <pre>
 Usage: gem cert [options] Options: -a, --add CERT Add a trusted certificate.
 -l, --list List trusted certificates. -r, --remove STRING Remove trusted
 certificates containing STRING. -b, --build EMAIL_ADDR Build private key and
 self-signed certificate for EMAIL_ADDR. -C, --certificate CERT Certificate for
 --sign command. -K, --private-key KEY Private key for --sign command. -s,
 --sign NEWCERT Sign a certificate with my key and certificate. Common Options:
 --source URL Use URL as the remote source for gems -p, --[no-]http-proxy [URL]
 Use HTTP proxy for remote operations -h, --help Get help on this command
 --config-file FILE Use this config file instead of default --backtrace Show
 stack backtrace on errors --debug Turn on Ruby debugging Summary: Adjust
 RubyGems certificate settings. </pre> See the "chapter on signing
 gems":http://docs.rubygems.org/read/chapter/21 in the :Ruby Users
 Guide":http://docs.rubygems.org/read/book/1 for details. h3. Examples Build a
 private key and certificate for gemmaster@example.com. Substitute your own
 email address for your own certificates. <pre>$ gem cert --build
 gemmaster@example.com</pre> Add a certificate to the list of trusted
 certificates. The trusted certificate list will be consulted when installing
 signed gems. <pre>$ gem cert --add gem-public_cert.pem</pre> Sign a certificate
 with the specified key and certificate (note that this modifies
 client_cert.pem!) <pre> $ gem cert \ -K /mnt/floppy/issuer-priv_key.pem \ -C
 issuer-pub_cert.pem \ --sign client_cert.pem </pre> <hr/>

=== <tt>gem check</tt> -- Check installed gems for problems

 The check command is used to verify that a gem in is good working order. h3.
 Usage <pre> Usage: gem check [options] Options: -v, --verify FILE Verify gem
 file against its internal checksum -a, --alien Report 'unmanaged' or rogue
 files in the gem repository -t, --test Run unit tests for gem -V, --version
 Specify version for which to run unit tests Common Options: --source URL Use
 URL as the remote source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy
 for remote operations -h, --help Get help on this command --config-file FILE
 Use this config file instead of default --backtrace Show stack backtrace on
 errors --debug Turn on Ruby debugging Summary: Check installed gems </pre> The
 <em>verify</em> option checks a gem file for corruption. If the file is not
 exactly like it was built, verify will complain. (Note: This is a simple
 integrity check. It is not checking for PGP like signatures). The
 <em>alien</em> option checks an installed gem to see if any of the files have
 been tampered with. h3. Examples The following check is run against a valid
 rake gem file. <pre> $ gem check -v pkg/rake-0.4.0.gem Verifying gem:
 'pkg/rake-0.4.0.gem' </pre> The following check shows that the rake gem file is
 invalid. <pre> $ gem check -v pkg/rake-0.4.0.gem Verifying gem:
 'pkg/rake-0.4.0.gem' ERROR: pkg/rake-0.4.0.gem is invalid. </pre> In this
 installation of <nowiki>ActiveRecord</nowiki>, the postgreSQL driver has been
 locally patched after the gem was installed. This is how the alien option
 reports it. <pre> $ gem check --alien Performing the 'alien' operation
 madeleine-0.6 is error-free madeleine-0.6.1 is error-free rake-0.4.0 is
 error-free rake-0.3.2 is error-free copland-0.3.0 is error-free sources-0.0.1
 has 2 problems iterator-0.5 is error-free activerecord-0.8.1 has 2 problems
 lib/active_record/connection_adapters/postgresql_adapter.rb: installed file
 doesn't match original from gem
 /usr/local/lib/ruby/gems/1.8/cache/activerecord-0.8.1.gem: Unmanaged files in
 gem: ["lib/active_record/connection_adapters/postgresql_adapter.rb~"]

 [... remaining output elided ...] </pre> <hr/>

=== <tt>gem cleanup</tt> -- Cleanup old versions in the repository

 (new in version 0.8.7) This command will remove (uninstall) all the versions of
 a gem, except for the latest one. If no gemname is given in the command line,
 cleanup will be run agains all installed gems. h3. Usage <pre> Usage: gem
 cleanup [options] Options: -d, --dryrun Common Options: --source URL Use URL as
 the remote source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for
 remote operations -h, --help Get help on this command --config-file FILE Use
 this config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: GEMNAME(s) name of gem(s) to cleanup
 Summary: Cleanup old versions of installed gems in the local repository
 Defaults: --no-dryrun </pre> h3. Examples <pre> $ gem cleanup Rubygems
 Environment: - VERSION: 0.6 (0.6.1) - INSTALLATION DIRECTORY:
 /usr/local/lib/ruby/gems/1.8 - GEM PATH: - /usr/local/lib/ruby/gems/1.8 -
 REMOTE SOURCES: - http://gems.rubyforge.org </pre> <hr/>

=== <tt>gem contents</tt> -- Display the files contained in an installed gem

 (new in version 0.8.11) The @contents@ command will list the full path names of
 all the files contained in the gem. h3. Usage <pre> Usage: gem contents
 [options] Options: -l, --list List the files inside a Gem -V, --version Specify
 version for gem to view -s, --spec-dir a,b,c Search for gems under specific
 paths -v, --verbose Be verbose when showing status Common Options: --source URL
 Use URL as the remote source for gems -p, --[no-]http-proxy [URL] Use HTTP
 proxy for remote operations -h, --help Get help on this command --config-file
 FILE Use this config file instead of default --backtrace Show stack backtrace
 on errors --debug Turn on Ruby debugging Summary: Disply the contents of the
 installed gems </pre> h3. Examples The following command displays the files
 included in the Rake gem. <pre> $ gem contents rake traken$ gem inspect rake
 /usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/install.rb
 /usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/CHANGES
 /usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/Rakefile
 /usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/README
 /usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/TODO [... truncated ...] </pre>
 h3. Limitations Currently there is no way to specify the version of the gem you
 wish to view. <hr/>

=== <tt>gem dependency</tt> -- List the dependencies of a gem

 The @dependency@ command displays the declared dependencies of any install gem
 package. h3. Usage <pre> Usage: gem dependency GEMNAME [options] Options: -v,
 --version VERSION Specify version of gem to uninstall -r,
 --[no-]reverse-dependencies Include reverse dependencies in the output -p,
 --pipe Pipe Format (name --version ver) Common Options: --source URL Use URL as
 the remote source for gems -h, --help Get help on this command --config-file
 FILE Use this config file instead of default --backtrace Show stack backtrace
 on errors --debug Turn on Ruby debugging Arguments: GEMNAME name of gems to
 show Summary: Show the dependencies of an installed gem Defaults: --version '>
 0' --no-reverse </pre> h3. Examples Here is the dependencies of the Rails gem.
 <pre> $ gem dependency rails -v 0.10.1 Gem rails-0.10.1 Requires rake (>=
 0.4.15) activesupport (= 1.0.1) activerecord (= 1.8.0) actionpack (= 1.5.1)
 actionmailer (= 0.7.1) actionwebservice (= 0.6.0) </pre> Adding a
 @--reverse-dependencies@ option adds the following bit of information: <pre> $
 gem dependency rails -v 0.10.1 --reverse-dependencies Gem rails-0.10.1 Requires
 rake (>= 0.4.15) activesupport (= 1.0.1) activerecord (= 1.8.0) actionpack (=
 1.5.1) actionmailer (= 0.7.1) actionwebservice (= 0.6.0) Used by
 storycards-0.0.2 (rails (>= 0.7.0)) </pre> Finally, the @--pipe@ option for the
 dependency command puts out the dependencies in a format that could be piped to
 another command. <pre> $ gem dependency rails -v 0.10.1 --pipe rake --version
 '>= 0.4.15' activesupport --version '= 1.0.1' activerecord --version '= 1.8.0'
 actionpack --version '= 1.5.1' actionmailer --version '= 0.7.1'
 actionwebservice --version '= 0.6.0' </pre> <hr/>

=== <tt>gem environment</tt> -- Display information about the gem environment

 Gems uses several paths and directories to perform its work. This command will
 display the information the gem command has found. h3. Usage <pre> Usage: gem
 environment [args] [options] Common Options: --source URL Use URL as the remote
 source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: packageversion display the package
 version gemdir display the path where gems are installed gempath display path
 used to search for gems version display the gem format version remotesources
 display the remote gem servers <omitted> display everything Summary: Display
 RubyGems environmental information </pre> h3. Examples <pre> $ gem environment
 Rubygems Environment: - VERSION: 0.6 (0.6.1) - INSTALLATION DIRECTORY:
 /usr/local/lib/ruby/gems/1.8 - GEM PATH: - /usr/local/lib/ruby/gems/1.8 -
 REMOTE SOURCES: - http://gems.rubyforge.org </pre> <hr/>

=== <tt>gem help</tt> -- Provide help about gem commands

 <tt>gem help</tt> provides information about the syntax and options available
 on the gem command. h3. Usage <pre> Usage: gem help ARGUMENT [options] Common
 Options: --source URL Use URL as the remote source for gems -p,
 --[no-]http-proxy [URL] Use HTTP proxy for remote operations -h, --help Get
 help on this command --config-file FILE Use this config file instead of default
 --backtrace Show stack backtrace on errors --debug Turn on Ruby debugging
 Arguments: commands List all 'gem' commands examples Show examples of 'gem'
 usage <command> Show specific help for <command> Summary: Provide help on the
 'gem' command </pre> <hr/>

=== <tt>gem install</tt> -- Installing a gem

 <tt>gem install</tt> will install the named gem. It will attempt a local
 installation (i.e. a .gem file in the current directory), and if that fails, it
 will attempt to download and install the most recent version of the gem you
 want. If a gem is being installed remotely, and it depends on other gems that
 are not installed, then gem will download and install those, after you have
 confirmed the operation. h3. Usage <pre> Usage: gem install GEMNAME [options]
 Options: -v, --version VERSION Specify version of gem to install -l, --local
 Restrict operations to the LOCAL domain (default) -r, --remote Restrict
 operations to the REMOTE domain -b, --both Allow LOCAL and REMOTE operations
 -i, --install-dir DIR -d, --[no-]rdoc Generate RDoc documentation for the gem
 on install -f, --[no-]force Force gem to install, bypassing dependency checks
 -t, --[no-]test Run unit tests prior to installation -w, --[no-]wrappers Use
 bin wrappers for executables Not available on dosish platforms -P,
 --trust-policy POLICY Specify gem trust policy. --ignore-dependencies Do not
 install any required dependent gems -y, --include-dependencies Unconditionally
 install the required dependent gems Common Options: --source URL Use URL as the
 remote source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: GEMNAME name of gem to install
 Summary: Install a gem into the local repository Defaults: --both --version '>
 0' --rdoc --no-force --no-test --install-dir /usr/local/lib/ruby/gems/1.8
 </pre> h3. Examples These examples show how GEMNAME can be specified: This will
 install local 'copland.gem' or remote 'copland-0.3.0' (for instance), but not a
 local file 'copland-0.3.0' gem. gem install copland This will install local
 'copland-0.2.0' or remote 'copland-0.2.0'. gem install copland-0.2.0 This will
 only succeed if the local file exists. This will not resolve to a remote gem.
 gem install copland-0.2.0.gem <pre> gem install --remote copland # shortcut:
 gem ins -R copland gem install copland --version '> 0.2' gem install copland
 --gen-rdoc --run-tests gem install copland --install-stub </pre> Here is an
 example session where a dependency is automatically downloaded and resolved.
 <pre> $ gem install copland Attempting local installation of '' Local gem file
 not found: copland.gem Attempting remote installation of 'copland' Install
 required dependency log4r? [Yn] y Successfully installed copland, version 0.3.0
 </pre> <hr/>

=== <tt>gem list</tt> -- List gems starting with a string

 <tt>gem list</tt> will list all gems whose name <em>starts with</em> the given
 string. If no string is provided, all gems are listed. h3. Usage <pre> Usage:
 gem list [STRING] [options] Options: -d, --[no-]details Display detailed
 information of gem(s) -l, --local Restrict operations to the LOCAL domain
 (default) -r, --remote Restrict operations to the REMOTE domain -b, --both
 Allow LOCAL and REMOTE operations Common Options: --source URL Use URL as the
 remote source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: STRING start of gem name to look for
 Summary: Display all gems whose name starts with STRING Defaults: --local
 --no-details </pre> h3. Examples List all remote gems starting with "a". <pre>
 $ gem list -r a *** REMOTE GEMS *** activerecord (0.8.4, 0.8.3, 0.8.2, 0.8.1,
 0.8.0, 0.7.6, 0.7.5) Implements the ActiveRecord pattern for ORM. arrayfields
 (3.3.0) Allow keyword access to arrays </pre> List all gems, local and remote.
 <pre> $ gem list --both *** LOCAL GEMS *** ... *** REMOTE GEMS *** ... </pre>
 <hr/>

=== <tt>gem query</tt> -- Query for a list of gems

 <tt>gem query</tt> will list all gems matching a particular criteria. The
 domain may be local, remote or both. h3. Usage <pre> Usage: gem query [options]
 Options: -n, --name-matches REGEXP Name of gem(s) to query on maches the
 provided REGEXP -d, --[no-]details Display detailed information of gem(s) -l,
 --local Restrict operations to the LOCAL domain (default) -r, --remote Restrict
 operations to the REMOTE domain -b, --both Allow LOCAL and REMOTE operations
 Common Options: --source URL Use URL as the remote source for gems -p,
 --[no-]http-proxy [URL] Use HTTP proxy for remote operations -h, --help Get
 help on this command --config-file FILE Use this config file instead of default
 --backtrace Show stack backtrace on errors --debug Turn on Ruby debugging
 Summary: Query gem information in local or remote repositories Defaults:
 --local --name-matches '.*' --no-details </pre> h3. Examples To list all local
 gems with a digit in the gem name: <pre> $ gem query -n '[0-9]' --local ***
 LOCAL GEMS *** jabber4r (0.7.0) Jabber4r is a pure-Ruby Jabber client library
 log4r (1.0.5) Log4r is a comprehensive and flexible logging library for Ruby.
 </pre> To list all remote gems that begin with the letter 'm': <pre> $ gem
 query -R -n ^m *** REMOTE GEMS *** madeleine (0.6.1, 0.6) Madeleine is a Ruby
 implementation of Object Prevalence midilib (0.8.0) MIDI file and event
 manipulation library </pre> <hr/>

=== <tt>gem rdoc</tt> -- Generate the RDoc files for an installed gem

 <tt>gem rdoc</tt> will generate the RDoc files for an installed gem. The files
 are put in the standard gem RDoc location so that @gem_server@ can find them.
 h3. Usage <pre> Usage: gem rdoc [args] [options] Options: --all Generate RDoc
 documentation for all installed gems -v, --version VERSION Specify version of
 gem to rdoc Common Options: --source URL Use URL as the remote source for gems
 -p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations -h, --help Get
 help on this command --config-file FILE Use this config file instead of default
 --backtrace Show stack backtrace on errors --debug Turn on Ruby debugging
 Arguments: GEMNAME The gem to generate RDoc for (unless --all) Summary:
 Generates RDoc for pre-installed gems Defaults: --version '> 0.0.0' </pre> h3.
 Examples The following command generates the RDoc files for the rake-0.5.4 gem.
 <pre> traken$ sudo gem rdoc rake --version 0.5.4 Installing RDoc documentation
 for rake-0.5.4... </pre> <hr/>

=== <tt>gem search</tt> -- List gems containing a string

 <tt>gem search</tt> will list all gems whose name <em>contains</em> the given
 (case-insensitive) string. If no string is provided, all gems will be listed.
 h3. Usage <pre> Usage: gem search [STRING] [options] Options: -d,
 --[no-]details Display detailed information of gem(s) -l, --local Restrict
 operations to the LOCAL domain (default) -r, --remote Restrict operations to
 the REMOTE domain -b, --both Allow LOCAL and REMOTE operations Common Options:
 --source URL Use URL as the remote source for gems -p, --[no-]http-proxy [URL]
 Use HTTP proxy for remote operations -h, --help Get help on this command
 --config-file FILE Use this config file instead of default --backtrace Show
 stack backtrace on errors --debug Turn on Ruby debugging Arguments: STRING
 fragment of gem name to look for Summary: Display all gems whose name contains
 STRING Defaults: --local --no-details </pre> h3. Examples List all remote gems
 containing "log" in their name. <pre> $ gem search -r log *** REMOTE GEMS ***
 log4r (1.0.5) Log4r is a comprehensive and flexible logging library for Ruby.
 rublog (0.8.0) RubLog is a simple web log, based around the idea of displaying
 a set of regular files in a log-format. </pre> <hr/>

=== <tt>gem specification</tt> -- Extract the Gem::Specification from a gem file

 The specification command will extract the Gem::Specification from a gem file
 and write to standard output in YAML format. h3. Usage <pre> Usage: gem
 specification GEMFILE [options] Options: -v, --version VERSION Specify version
 of gem to examine -l, --local Restrict operations to the LOCAL domain (default)
 -r, --remote Restrict operations to the REMOTE domain -b, --both Allow LOCAL
 and REMOTE operations --all Output specifications for all versions of the gem
 Common Options: --source URL Use URL as the remote source for gems -p,
 --[no-]http-proxy [URL] Use HTTP proxy for remote operations -h, --help Get
 help on this command --config-file FILE Use this config file instead of default
 --backtrace Show stack backtrace on errors --debug Turn on Ruby debugging
 Arguments: GEMFILE Name of a .gem file to examine Summary: Display gem
 specification (in yaml) Defaults: --local --version '(latest)' </pre> h3.
 Examples Here is the specification from rake 0.4.1. <pre> $ gem spec rake -v
 0.4.1 --- !ruby/object:Gem::Specification rubygems_version: "0.6" name: rake
 version: !ruby/object:Gem::Version version: 0.4.1 date: 2004-07-02
 01:08:54.678603 -04:00 platform: summary: Ruby based make-like utility.
 require_paths: - lib files: - install.rb - CHANGES - Rakefile - README - TODO -
 MIT-LICENSE - bin/rake - lib/rake.rb - lib/rake/clean.rb ...... </pre> <hr/>

=== <tt>gem uninstall</tt> -- Uninstalling a gem

 The uninstall will uninstall the named gem. If multiple versions of a gem are
 installed, you will be prompted to select a single one, or all of them. h3.
 Usage <pre> Usage: gem uninstall GEMNAME [options] Options: -a, --[no-]all
 Uninstall all matching versions -i, --[no-]ignore-dependencies Ignore
 dependency requirements while uninstalling -x, --[no-]executables Uninstall
 applicable executables without confirmation -v, --version VERSION Specify
 version of gem to uninstall Common Options: --source URL Use URL as the remote
 source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: GEMNAME name of gem to uninstall
 Summary: Uninstall a gem from the local repository Defaults: --version '> 0'
 --no-force </pre> h3. Examples The following uninstalls the only copy of
 copland. <pre> $ gem uninstall copland Attempting to uninstall gem 'copland'
 Successfully uninstalled copland version 0.3.0 </pre> The following uninstalls
 all the installed versions of the rake gem. Since rake is an application, it
 has a ApplicationStub installed. The uninstall removes the stub as well. <pre>
 $ sudo gem uninstall rake Attempting to uninstall gem 'rake' Select RubyGem to
 uninstall: 1. rake-0.3.2 2. rake-0.4.0 3. All versions > 3 Successfully
 uninstalled rake version 0.3.2 Successfully uninstalled rake version 0.4.0
 WARNING: About to remove executables and scripts for: rake Proceed? [Y/n] y
 Removing rake </pre> <hr/>

=== <tt>gem unpack</tt> -- Unpack an installed gem to the current directory

 <em>(Not in version 0.7.)</em> The unpack command creates a private copy of the
 named gem's contents into a new directory. This enables you to examine the
 contents without interfering with the gem repository. You can only unpack gems
 that you have installed, and you must specify the gem name exactly. h3. Usage
 <pre> Usage: gem unpack GEMNAME [options] Options: -v, --version VERSION
 Specify version of gem to unpack Common Options: --source URL Use URL as the
 remote source for gems -p, --[no-]http-proxy [URL] Use HTTP proxy for remote
 operations -h, --help Get help on this command --config-file FILE Use this
 config file instead of default --backtrace Show stack backtrace on errors
 --debug Turn on Ruby debugging Arguments: GEMNAME Name of the gem to unpack
 Summary: Unpack an installed gem to the current directory Defaults: --version
 '> 0' </pre> h3. Examples <pre> $ gem unpack rake Unpacked gem: 'rake-0.4.3' $
 ls rake-0.4.3/ CHANGES MIT-LICENSE README Rakefile TODO bin doc install.rb lib
 test $ gem unpack wazoo ERROR: Gem 'wazoo' not installed. </pre> <hr/>

=== <tt>gem update</tt> -- Update your installed gems

 The update command will check the named gem (or all of your installed gems if
 no name is given) and update each one to a newer version if one is available.
 h3. Usage <pre> Usage: gem update [options] Options: -i, --install-dir DIR -d,
 --[no-]rdoc Generate RDoc documentation for the gem on install -f, --[no-]force
 Force gem to install, bypassing dependency checks -t, --[no-]test Run unit
 tests prior to installation -w, --[no-]wrappers Use bin wrappers for
 executables Not available on dosish platforms -P, --trust-policy POLICY Specify
 gem trust policy. --ignore-dependencies Do not install any required dependent
 gems -y, --include-dependencies Unconditionally install the required dependent
 gems --system Update the RubyGems system software Common Options: --source URL
 Use URL as the remote source for gems -p, --[no-]http-proxy [URL] Use HTTP
 proxy for remote operations -h, --help Get help on this command --config-file
 FILE Use this config file instead of default --backtrace Show stack backtrace
 on errors --debug Turn on Ruby debugging Arguments: GEMNAME(s) name of gem(s)
 to update Summary: Upgrade the named gem (or all installed gems) in the local
 repository Defaults: --rdoc --no-force --no-test --install-dir
 /usr/local/lib/ruby/gems/1.8 </pre> h3. Examples <pre> $ gem update Upgrading
 installed gems... Attempting remote upgrade of activerecord Attempting remote
 installation of 'activerecord' Successfully installed activerecord, version
 0.8.4 Attempting remote upgrade of csbattery Attempting remote installation of
 'csbattery' Successfully installed csbattery, version 0.2.2 All gems up to date
 </pre> <hr/>

== Configuration File

=== Overview

 <tt>gem</tt> looks for a configuration file <b><tt>.gemrc</tt></b> in your
 <b>home directory</b>, although you can specify another file on the
 command-line if you wish (with the <tt>--config-file</tt> modifier). Only one
 configuration file will be processed: the rightmost one on the command-line, or
 the default <tt>$HOME/.gemrc</tt>, or none at all.

 There are three things you can specify in the configuration file: *
 command-line arguments to be used every time <tt>gem</tt> runs * command-line
 options for ''RDoc'' (used when generating docuemntation) * GEMPATH settings

 The config file itself is in '''YAML''' format. Here is an example:

 <pre> gem: --local --gen-rdoc --run-tests rdoc: --inline-source --line-numbers
 gempath: - /usr/local/rubygems - /home/gavin/.rubygems </pre>

 The effects of such a config file would be: * <tt>gem</tt> only runs ''local''
 operations (unless you specify <tt>--remote</tt> or <tt>--both</tt> on the
 command-line) * <tt>gem</tt> generates RDocs and runs unit tests every time it
 installs something (good idea!) * when it generates RDocs, the given arguments
 will be used * <tt>/usr/local/rubygems</tt> and <tt>/home/gavin/rubygems</tt>
 will be used as your <tt>$GEM_PATH</tt> setting

=== Configuration Options

 h3. gem

 The <em>gem</em> configuration item specifies the command-line options you wish
 to include <em>every time you run</em> <tt>gem</tt>.

 The effect of including options here is the same as including them at the start
 of the command-line. That means they may be overridden by later options.

 For example, you you have a poor internet connection, then you probably don't
 want <tt>gem</tt> to go to the internet all the time by default. Thus, you
 should include

 gem: --local

 in your configuration file. However, when you ''do'' want to remotely install
 something, you can run

 gem install something --remote

 to override the value in the config file.

 Other good uses for this config item are: * <tt>--gen-rdoc</tt> to generate
 documentation on every install * <tt>--run-tests</tt> to run unit tests on
 every install * <tt>--install-stub</tt> to install a library stub on every
 install * <tt>--http-proxy</tt>, or some variant, if you have certain proxy
 requirements

 h3. rdoc

 The <em>rdoc</em> configuration item specifies the command-line options you
 would like to pass to <tt>rdoc</tt> when it is generating documentation for an
 installed gem.

 The purpose of this is so that you can tailor the output that RDoc generates.
 See <tt>rdoc --help</tt> for a full list, but here are some things you might
 want to use: * <tt>--all</tt> to include <em>all</em> methods, not just public
 ones * <tt>--charset</tt> to specify the HTML charset to use *
 <tt>--diagram</tt>, if you can get that to work (requires <em>graphviz</em>) *
 <tt>--line-numbers</tt>, if you want source code to have line numbers *
 <tt>--inline-source</tt>, if you want methods to have their source code
 displayed * <tt>--template</tt> to specify the template to be used (e.g.
 "kilmer") * <tt>--style</tt> to specify your own stylesheet URL

 h3. gemhome

 <tt>gemhome</tt> is the location of the gem repository where your gems will be
 installed.

 This value will override the <tt>GEM_HOME</tt> environment variable. Both may
 be overridden by the <tt>--install-dir</tt> command line options.

 If not specified, then the first repository in the gem path will be used (see
 <tt>gempath</tt> below).

 h3. gempath

 <tt>gempath</tt> is an array of directories where you have gems installed. The
 first entry will be used as the default gem installation directory (unless an
 explicit <tt>gemhome</tt> config setting or <tt>GEM_HOME</tt> environment
 setting is found.

 This value will override the value of the environment variable
 <tt>GEM_PATH</tt>.

 This is useful if you have gems installed in several places.

 The default value for this is the system wide gem repository in the ruby
 installation directory.

=== Examples

 Here is a simple example. We always specify the <tt>--gem-rdoc</tt> option to
 generate the documentation when we install a package. The locally specified
 <tt>--line-numbers</tt> and <tt>--template html</tt> will override the options
 specified in the gem file.

 <pre> gem: --gen-rdoc rdoc: --line-numbers --template html </pre>

 This user isn't able to install gems into the standard system location, so they
 provide a local gem repository. We make sure that the system wide gem
 repository is still in the path so that gems installed there can be found.

 <pre> gemhome: /home/a_user/.gems gempath: - /usr/local/lib/ruby/gems/1.8
 </pre>

== Environment Variables

=== GEM Environment Variables

 You can control the behavior of RubyGems through the following environment
 variables.

 <b>GEMCACHE</b> * Name of user defined cache file to use when the site wide
 cache file is unwritable. (NOTE: we will probably rename this to
 <b>GEM_CACHE</b> in the next revision to be consistent with the other
 environment variables).

 <b>GEM_HOME</b> * Directory containing the master gem repository.

 <b>GEM_PATH</b> * Path list of directories containing gem repositories to be
 searched in addition to the GEM_HOME directory. The list should be delimited by
 the appropriate path separator (e.g. ':' on Unix and ';' on Windows)

 <b>GEM_SKIP</b> * List of gems should should not be loaded (normally used for
 development). The list should be delimited by the appropriate path separator
 (e.g. ':' on Unix and ';' on Windows)

 <b>HOME</b> * Home directory of the user (see below).

 <b>HOMEDRIVE</b> * Drive containing the users home directory.

 <b>HOMEPATH</b> * Path to the user's home directory.

 <b>http_proxy</b> or <b>HTTP_PROXY</b> * URL of the HTTP protocol proxy to be
 used to get out of the firewall. The lower case verion will be used first.

 <b>make</b> * Name of the make program that should be used to build extensions.

 <b>USERPROFILE</b> * Home directory of the user (used if HOME is not defined).

=== Finding a Home Directory

 Finding the user's home directory can be tricky across different systems. Gems
 tries the following in order until it finds one that works:

 # Use <b>HOME</b> if it is defined. # Use <b>USERPROFILE</b> if it is defined.
 # Use <b>HOMEDRIVE</b> and <b>HOMEPATH</b> together if they are defined. # Use
 the path you get by having Ruby expand "~". # Use "C:/" if you are on a Windows
 machine.

== Common Command Options

=== Additional Details on some Gem Command Options

 The ''Operations'' section listed the modifiers that are relevant to each
 operation. In this section the modifiers are discussed in more detail where
 needed. Most of them apply only to installation of gems.

=== <tt>--config-file <em>FILE</em></tt>

 Specifies a configuration file to use. The default is <tt>.gemrc</tt> in your
 <tt>HOME</tt> directory. Only one configuration file will be read. See
 ConfigurationFile for more details.

=== <tt>--install-dir <em>DIR</em></tt>

 Installation will take place in the given directory. For instance, if
 <em>DIR</em> is <tt>/usr/share/rubygems</tt>, then your gem will be installed
 into <tt>/usr/share/rubygems/gem/<em>gem-name</em></tt>.

 Normally, installation takes place in the ''first'' directory specified in your
 <em>gem path</em>, which is set by the environment variable <tt>GEM_PATH</tt>
 or in the configuration file. If you don't specify a ''gem path'' (and most
 people shouldn't need to), then the base RubyGems installation directory is
 <tt>/usr/local/lib/ruby/gems/1.8/</tt>.

 This modifier applies to installation of gems only.

=== <tt>--force</tt>

 Forces the installation of a gem even if the dependencies are not met.

 This modifier applies to installation of gems only.

=== <tt>--[no-]rdoc</tt>

 RDoc API documentation will be generated after a gem is installed. If the gem
 does not specify that it contains RDoc comments, RDoc will be run anyway.

 This modifier applies to installation of gems only.

=== <tt>--run-tests</tt>

 Unit tests will be run after a gem is installed. If the gem does not contain
 any unit tests, then a message will be printed to that effect.

 This modifier applies to installation of gems only.

=== <tt>--version <em>VERSION</em></tt>

 The operation will limit itself, if appropriate, to gems matching the given
 version requirement string. Examples for <em>VERSION</em> are:

 * <tt>1.0.5</tt> * <tt>> 1.0.5</tt> * <tt><= 1.0.5</tt>

===  <tt>--remote, -R</tt>

 The operation will be restricted to the ''remote'' domain. Fo r example, an
 <tt>--install</tt> operation will go directly to the remote servers.

=== <tt>--both, -B</tt>

 The operation may be performed in the local ''and'' remote domains. This is the
 default behaviour.

=== <tt>--[no-]http-proxy [<em>URL</em>], -p</tt>

 Command-line applications typically set an environment variable to specify an
 HTTP proxy through which to access the Internet. <tt>gem</tt> respects the
 following variables:

 * <tt>http_proxy</tt> * <tt>HTTP_PROXY</tt> * <tt>NO_PROXY</tt>

 A proxy specification must be a full HTTP URL, e.g.
 <tt>http://www-cache:8000</tt>. A <tt>NO_PROXY</tt> setting lists the domains
 (comma-separated) for which no proxy should be used.

 If you specify: * nothing or <tt>--http-proxy</tt>, then the environment will
 be respected; * <tt>--http-proxy <em>URL</em></tt>, then <tt><em>URL</em></tt>
 will be used, regardless of the environment. * <tt>--no-http-proxy</tt>, then
 _no_ proxy will be used, regardless of the environment;

 <tt>-P</tt> is a shortcut for <tt>--http-proxy</tt>. There is no shortcut for
 <tt>--no-http-proxy</tt>.

 Between the environment and the command-line, there are many options available
 for specifying your proxy if you are behind one. Annoyingly, I am behind a
 proxy <em>half</em> the time, and my solution is to:

 * set HTTP_PROXY to my proxy URL * in my <tt>.gemrc</tt> config file (see
 below), specify <tt>--no-http-proxy</tt> * when I <em>am</em> behind a proxy,
 give <tt>-P</tt> on the command line to override the above option

 That solution is the least amount of typing, until I think of a way to
 conditionally set HTTP_PROXY in a smart way.