RubyGems Guides
← Previous Next →

Command Reference

What each gem command does, and how to use it.

gem build

Build a gem from a gemspec

Usage

gem build GEMSPEC_FILE [options]

Common Options:

Arguments

gem cert

Manage RubyGems certificates and signing settings

Usage

gem cert [options]

Options:

Common Options:

gem check

Check installed gems

Usage

gem check [options]

Options:

Common Options:

gem cleanup

Clean up old versions of installed gems in the local repository

Usage

gem cleanup [GEMNAME ...] [options]

Options:

Common Options:

Arguments

Description

The cleanup command removes old gems from GEM_HOME. If an older version is installed elsewhere in GEM_PATH the cleanup command won’t touch it.

gem contents

Display the contents of the installed gems

Usage

gem contents GEMNAME [GEMNAME ...] [options]

Options:

Common Options:

Arguments

gem dependency

Show the dependencies of an installed gem

Usage

gem dependency GEMNAME [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

Arguments

gem environment

Display information about the RubyGems environment

Usage

gem environment [arg] [options]

Common Options:

Arguments

Description

The RubyGems environment can be controlled through command line arguments, gemrc files, environment variables and built-in defaults.

Command line argument defaults and some RubyGems defaults can be set in ~/.gemrc file for individual users and a /etc/gemrc for all users. A gemrc is a YAML file with the following YAML keys:

:sources: A YAML array of remote gem repositories to install gems from
:verbose: Verbosity of the gem command.  false, true, and :really are the
          levels
:update_sources: Enable/disable automatic updating of repository metadata
:backtrace: Print backtrace when RubyGems encounters an error
:gempath: The paths in which to look for gems
gem_command: A string containing arguments for the specified gem command

Example:

:verbose: false
install: --no-wrappers
update: --no-wrappers

RubyGems’ default local repository can be overridden with the GEM_PATH and GEM_HOME environment variables. GEM_HOME sets the default repository to install into. GEM_PATH allows multiple local repositories to be searched for gems.

If you are behind a proxy server, RubyGems uses the HTTP_PROXY, HTTP_PROXY_USER and HTTP_PROXY_PASS environment variables to discover the proxy server.

If you are packaging RubyGems all of RubyGems’ defaults are in lib/rubygems/defaults.rb. You may override these in lib/rubygems/defaults/operating_system.rb

gem fetch

Download a gem and place it in the current directory

Usage

gem fetch GEMNAME [GEMNAME ...] [options]

Options:

Local/Remote Options:

Common Options:

Arguments

gem generate_index

Generates the index files for a gem server directory

Usage

gem generate_index [options]

Options:

RSS Options:

Common Options:

Description

The generate_index command creates a set of indexes for serving gems statically. The command expects a ‘gems’ directory under the path given to the –directory option. The given directory will be the directory you serve as the gem repository.

For gem generate_index --directory /path/to/repo, expose /path/to/repo via your HTTP server configuration (not /path/to/repo/gems).

When done, it will generate a set of files like this:

gems/*.gem                                   # .gem files you want to
                                             # index

specs.<version>.gz                           # specs index
latest_specs.<version>.gz                    # latest specs index
prerelease_specs.<version>.gz                # prerelease specs index
quick/Marshal.<version>/<gemname>.gemspec.rz # Marshal quick index file

# these files support legacy RubyGems
Marshal.<version>
Marshal.<version>.Z                          # Marshal full index

The .Z and .rz extension files are compressed with the inflate algorithm. The Marshal version number comes from ruby’s Marshal::MAJOR_VERSION and Marshal::MINOR_VERSION constants. It is used to ensure compatibility.

If –rss-host and –rss-gem-host are given an RSS feed will be generated at index.rss containing gems released in the last two days.

gem help

Provide help on the ‘gem’ command

Usage

gem help ARGUMENT [options]

Common Options:

Arguments

gem install

Install a gem into the local repository

Usage

gem install GEMNAME [GEMNAME ...] [options] -- --build-flags [options]

Options:

Deprecated Options:

Install/Update Options:

Local/Remote Options:

Common Options:

Arguments

Description

The install command installs local or remote gem into a gem repository.

For gems with executables ruby installs a wrapper file into the executable directory by default. This can be overridden with the –no-wrappers option. The wrapper allows you to choose among alternate gem versions using version.

For example rake _0.7.3_ --version will run rake version 0.7.3 if a newer version is also installed.

If an extension fails to compile during gem installation the gem specification is not written out, but the gem remains unpacked in the repository. You may need to specify the path to the library’s headers and libraries to continue. You can do this by adding a – between RubyGems’ options and the extension’s build options:

$ gem install some_extension_gem
[build fails]
Gem files will remain installed in \
/path/to/gems/some_extension_gem-1.0 for inspection.
Results logged to /path/to/gems/some_extension_gem-1.0/gem_make.out
$ gem install some_extension_gem -- --with-extension-lib=/path/to/lib
[build succeeds]
$ gem list some_extension_gem

*** LOCAL GEMS ***

some_extension_gem (1.0)
$

If you correct the compilation errors by editing the gem files you will need to write the specification by hand. For example:

$ gem install some_extension_gem
[build fails]
Gem files will remain installed in \
/path/to/gems/some_extension_gem-1.0 for inspection.
Results logged to /path/to/gems/some_extension_gem-1.0/gem_make.out
$ [cd /path/to/gems/some_extension_gem-1.0]
$ [edit files or what-have-you and run make]
$ gem spec ../../cache/some_extension_gem-1.0.gem --ruby > \
           ../../specifications/some_extension_gem-1.0.gemspec
$ gem list some_extension_gem

*** LOCAL GEMS ***

some_extension_gem (1.0)
$

gem list

Display gems whose name starts with STRING

Usage

gem list [STRING] [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

Arguments

gem lock

Generate a lockdown list of gems

Usage

gem lock GEMNAME-VERSION [GEMNAME-VERSION ...] [options]

Options:

Common Options:

Arguments

Description

The lock command will generate a list of +gem+ statements that will lock down the versions for the gem given in the command line. It will specify exact versions in the requirements list to ensure that the gems loaded will always be consistent. A full recursive search of all effected gems will be generated.

Example:

gemlock rails-1.0.0 > lockdown.rb

will produce in lockdown.rb:

require "rubygems"
gem 'rails', '= 1.0.0'
gem 'rake', '= 0.7.0.1'
gem 'activesupport', '= 1.2.5'
gem 'activerecord', '= 1.13.2'
gem 'actionpack', '= 1.11.2'
gem 'actionmailer', '= 1.1.5'
gem 'actionwebservice', '= 1.0.0'

Just load lockdown.rb from your application to ensure that the current versions are loaded. Make sure that lockdown.rb is loaded before any other require statements.

Notice that rails 1.0.0 only requires that rake 0.6.2 or better be used. Rake-0.7.0.1 is the most recent version installed that satisfies that, so we lock it down to the exact version.

gem outdated

Display all gems that need updates

Usage

gem outdated [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

gem owner

Manage gem owners on RubyGems.org.

Usage

gem owner [options]

Options:

Local/Remote Options:

Common Options:

Arguments

Description

Manage gem owners on RubyGems.org.

gem pristine

Restores installed gems to pristine condition from files located in the gem cache

Usage

gem pristine [args] [options]

Options:

Common Options:

Arguments

Description

The pristine command compares the installed gems with the contents of the cached gem and restores any files that don’t match the cached gem’s copy.

If you have made modifications to your installed gems, the pristine command will revert them. After all the gem’s files have been checked all bin stubs for the gem are regenerated.

If the cached gem cannot be found, you will need to use gem install to revert the gem.

If –no-extensions is provided pristine will not attempt to restore gems with extensions.

gem push

Push a gem up to RubyGems.org

Usage

gem push GEM [options]

Options:

Local/Remote Options:

Common Options:

Arguments

Description

Push a gem up to RubyGems.org

gem query

Query gem information in local or remote repositories

Usage

gem query [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

gem rdoc

Generates RDoc for pre-installed gems

Usage

gem rdoc [args] [options]

Options:

Common Options:

Arguments

Description

The rdoc command builds RDoc and RI documentation for installed gems. Use –overwrite to force rebuilding of documentation.

Display all gems whose name contains STRING

Usage

gem search [STRING] [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

Arguments

gem server

Documentation and gem repository HTTP server

Usage

gem server [options]

Options:

Common Options:

Description

The server command starts up a web server that hosts the RDoc for your installed gems and can operate as a server for installation of gems on other machines.

The cache files for installed gems must exist to use the server as a source for gem installation.

To install gems from a running server, use gem install GEMNAME --source http://gem_server_host:8808

You can set up a shortcut to gem server documentation using the URL:

http://localhost:8808/rdoc?q=%s - Firefox
http://localhost:8808/rdoc?q=* - LaunchBar

gem sources

Manage the sources and cache file RubyGems uses to search for gems

Usage

gem sources [options]

Options:

Local/Remote Options:

Common Options:

gem specification

Display gem specification (in yaml)

Usage

gem specification [GEMFILE] [FIELD] [options]

Options:

Deprecated Options:

Local/Remote Options:

Common Options:

Arguments

gem stale

List gems along with access times

Usage

gem stale [options]

Common Options:

gem uninstall

Uninstall gems from the local repository

Usage

gem uninstall GEMNAME [GEMNAME ...] [options]

Options:

Common Options:

Arguments

gem unpack

Unpack an installed gem to the current directory

Usage

gem unpack GEMNAME [options]

Options:

Common Options:

Arguments

gem update

Update the named gems (or all installed gems) in the local repository

Usage

gem update GEMNAME [GEMNAME ...] [options]

Options:

Deprecated Options:

Install/Update Options:

Local/Remote Options:

Common Options:

Arguments

gem which

Find the location of a library file you can require

Usage

gem which FILE [FILE ...] [options]

Options:

Common Options:

Arguments

← Previous Next →