gem Command Reference

The gem command is the main user interface to the RubyGems packaging system. This document provides a reference to the gem 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

gem is based on ’’commands’’, like build, install, and search. 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 install is the command, rake is the argument, and —remote is an option. (By the way, this command installs rake remotely.)

gem provides most of the help you need inline.

To see a list of commands, run gem help commands.
To get help on the install command, run gem help install.
To see some examples of common usage, run gem help examples.
For a reminder of all this, just run gem help.

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

Command Reference

`gem build`—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.

Usage

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

Examples

This example builds a the rake package from a gemspec file.

$ 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

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.

$ rake gem
(in /home/jim/working/rubyforge/rake)
  Successfully built RubyGem
  Name: rake
  Version: 0.4.0
  File: rake-0.4.0.gem

`gem cert`—Support signing and managing signed gems

The cert command manages the certificates needed to sign gems.

Usage

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.

See the chapter on signing gems in the :Ruby Users Guide”:http://docs.rubygems.org/read/book/1 for details.

Examples

Build a private key and certificate for gemmaster@example.com. Substitute your own email address for your own certificates.

$ gem cert --build gemmaster@example.com

Add a certificate to the list of trusted certificates. The trusted certificate list will be consulted when installing signed gems.

$ gem cert --add gem-public_cert.pem

Sign a certificate with the specified key and certificate (note that this modifies client_cert.pem!)

$ gem cert \
     -K /mnt/floppy/issuer-priv_key.pem \
     -C issuer-pub_cert.pem \
     --sign client_cert.pem

`gem check`—Check installed gems for problems

The check command is used to verify that a gem in is good working order.

Usage

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

The verify 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 alien option checks an installed gem to see if any of the files have been tampered with.

Examples

The following check is run against a valid rake gem file.

$ gem check -v pkg/rake-0.4.0.gem 
Verifying gem: 'pkg/rake-0.4.0.gem'

The following check shows that the rake gem file is invalid.

$ 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.

In this installation of ActiveRecord, the postgreSQL driver has been locally patched after the gem was installed. This is how the alien option reports it.

$ 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 ...]

`gem cleanup`—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.

Usage

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

Examples

$ 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

`gem contents`—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.

Usage

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

Examples

The following command displays the files included in the Rake gem.

$ 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 ...]

Limitations

Currently there is no way to specify the version of the gem you wish to view.

`gem dependency`—List the dependencies of a gem

The dependency command displays the declared dependencies of any install gem package.

Usage

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

Examples

Here is the dependencies of the Rails gem.

$ 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)

Adding a --reverse-dependencies option adds the following bit of information:

$ 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))

Finally, the --pipe option for the dependency command puts out the dependencies in a format that could be piped to another command.

$ 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'

`gem environment`—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.

Usage

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

Examples

$ 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

`gem help`—Provide help about gem commands

gem help provides information about the syntax and options available on the gem command.

Usage

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

`gem install`—Installing a gem

gem install 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.

Usage

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

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

  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

Here is an example session where a dependency is automatically downloaded and resolved.

$ 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

`gem list`—List gems starting with a string

gem list will list all gems whose name starts with the given string. If no string is provided, all gems are listed.

Usage

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

Examples

List all remote gems starting with “a”.

$ 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

List all gems, local and remote.

$ gem list --both

*** LOCAL GEMS ***

  ...

*** REMOTE GEMS ***

  ...

`gem query`—Query for a list of gems

gem query will list all gems matching a particular criteria. The domain may be local, remote or both.

Usage

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

Examples

To list all local gems with a digit in the gem name:

$ 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.

To list all remote gems that begin with the letter ‘m’:

$ 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

`gem rdoc`—Generate the RDoc files for an installed gem

gem rdoc 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.

Usage

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'

Examples

The following command generates the RDoc files for the rake-0.5.4 gem.

traken$ sudo gem rdoc rake --version 0.5.4
Installing RDoc documentation for rake-0.5.4...

`gem search`—List gems containing a string

gem search will list all gems whose name contains the given (case-insensitive) string. If no string is provided, all gems will be listed.

Usage

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

Examples

List all remote gems containing “log” in their name.

$ 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.

`gem specification`—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.

Usage

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)'

Examples

Here is the specification from rake 0.4.1.

$ 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
  ......

`gem uninstall`—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.

Usage

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

Examples

The following uninstalls the only copy of copland.

$ gem uninstall copland
Attempting to uninstall gem 'copland'
Successfully uninstalled copland version 0.3.0

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.

$ 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

`gem unpack`—Unpack an installed gem to the current directory

(Not in version 0.7.)

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.

Usage

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'

Examples

$ 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.

`gem update`—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.

Usage

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

Examples

$ 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

Configuration File

Overview

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

There are three things you can specify in the configuration file:

command-line arguments to be used every time gem runs
command-line options for ’’RDoc’’ (used when generating docuemntation)
GEMPATH settings

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

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

The effects of such a config file would be:

gem only runs ’’local’’ operations (unless you specify -remote or -both on the command-line)
gem generates RDocs and runs unit tests every time it installs something (good idea!)
when it generates RDocs, the given arguments will be used
/usr/local/rubygems and /home/gavin/rubygems will be used as your $GEM_PATH setting

Configuration Options

gem

The gem configuration item specifies the command-line options you wish to include every time you run gem.

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 gem 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:

—gen-rdoc to generate documentation on every install
—run-tests to run unit tests on every install
—install-stub to install a library stub on every install
—http-proxy, or some variant, if you have certain proxy requirements

rdoc

The rdoc configuration item specifies the command-line options you would like to pass to rdoc 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 rdoc—help for a full list, but here are some things you might want to use:

—all to include all methods, not just public ones
—charset to specify the HTML charset to use
—diagram, if you can get that to work (requires graphviz)
—line-numbers, if you want source code to have line numbers
—inline-source, if you want methods to have their source code displayed
—template to specify the template to be used (e.g. “kilmer”)
—style to specify your own stylesheet URL

gemhome

gemhome is the location of the gem repository where your gems will be installed.

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

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

gempath

gempath 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 gemhome config setting or GEM_HOME environment setting is found.

This value will override the value of the environment variable GEM_PATH.

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 -gem-rdoc option to generate the documentation when we install a package. The locally specified -line-numbers and —template html will override the options specified in the gem file.

  gem: --gen-rdoc
  rdoc: --line-numbers --template html

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.

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

Environment Variables

GEM Environment Variables

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

GEMCACHE

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

GEM_HOME

Directory containing the master gem repository.

GEM_PATH

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)

GEM_SKIP

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)

HOME

Home directory of the user (see below).

HOMEDRIVE

Drive containing the users home directory.

HOMEPATH

Path to the user’s home directory.

http_proxy or HTTP_PROXY

URL of the HTTP protocol proxy to be used to get out of the firewall. The lower case verion will be used first.

make

Name of the make program that should be used to build extensions.

USERPROFILE

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 HOME if it is defined.
Use USERPROFILE if it is defined.
Use HOMEDRIVE and HOMEPATH 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.

`—config-file FILE`

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

`—install-dir DIR`

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

Normally, installation takes place in the ’’first’’ directory specified in your gem path, which is set by the environment variable GEM_PATH 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 /usr/local/lib/ruby/gems/1.8/.

This modifier applies to installation of gems only.

`—force`

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

This modifier applies to installation of gems only.

`-[no]rdoc`

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.

`—run-tests`

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.

`—version VERSION`

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

1.0.5
> 1.0.5
<= 1.0.5

`—remote, -R`

The operation will be restricted to the ’’remote’’ domain. Fo r example, an —install operation will go directly to the remote servers.

`—both, -B`

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

`-[no]http-proxy [URL], -p`

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

http_proxy
HTTP_PROXY
NO_PROXY

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

If you specify:

nothing or —http-proxy, then the environment will be respected;
—http-proxy URL, then URL will be used, regardless of the environment.
—no-http-proxy, then no proxy will be used, regardless of the environment;

P is a shortcut for -http-proxy. There is no shortcut for —no-http-proxy.

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 half the time, and my solution is to:

set HTTP_PROXY to my proxy URL
in my .gemrc config file (see below), specify —no-http-proxy
when I am behind a proxy, give -P 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.

gem Command Reference

Overview

Introduction

Getting Help

Command Reference

gem build—Build a gem file from a specification

Usage

Examples

gem cert—Support signing and managing signed gems

Usage

Examples

gem check—Check installed gems for problems

Usage

Examples

gem cleanup—Cleanup old versions in the repository

Usage

Examples

gem contents—Display the files contained in an installed gem

Usage

Examples

Limitations

gem dependency—List the dependencies of a gem

Usage

Examples

gem environment—Display information about the gem environment

Usage

Examples

gem help—Provide help about gem commands

Usage

gem install—Installing a gem

Usage

Examples

gem list—List gems starting with a string

Usage

Examples

gem query—Query for a list of gems

Usage

Examples

gem rdoc—Generate the RDoc files for an installed gem

Usage

Examples

gem search—List gems containing a string

Usage

Examples

gem specification—Extract the Gem::Specification from a gem file

Usage

Examples

gem uninstall—Uninstalling a gem

Usage

Examples

gem unpack—Unpack an installed gem to the current directory

Usage

Examples

gem update—Update your installed gems

Usage

Examples

Configuration File

Overview

Configuration Options

gem

rdoc

gemhome

gempath

Examples

Environment Variables

GEM Environment Variables

Finding a Home Directory

Common Command Options

Additional Details on some Gem Command Options

—config-file FILE

—install-dir DIR

—force

-[no]rdoc

—run-tests

—version VERSION

—remote, -R

—both, -B

-[no]http-proxy [URL], -p

`gem build`—Build a gem file from a specification

`gem cert`—Support signing and managing signed gems

`gem check`—Check installed gems for problems

`gem cleanup`—Cleanup old versions in the repository

`gem contents`—Display the files contained in an installed gem

`gem dependency`—List the dependencies of a gem

`gem environment`—Display information about the gem environment

`gem help`—Provide help about gem commands

`gem install`—Installing a gem

`gem list`—List gems starting with a string

`gem query`—Query for a list of gems

`gem rdoc`—Generate the RDoc files for an installed gem

`gem search`—List gems containing a string

`gem specification`—Extract the Gem::Specification from a gem file

`gem uninstall`—Uninstalling a gem

`gem unpack`—Unpack an installed gem to the current directory

`gem update`—Update your installed gems

`—config-file FILE`

`—install-dir DIR`

`—force`

`-[no]rdoc`

`—run-tests`

`—version VERSION`

`—remote, -R`

`—both, -B`

`-[no]http-proxy [URL], -p`