2. Command Reference
2.1 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
2.2 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
2.3 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
$ 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 ...]
2.4 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
2.5 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.
2.6 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'
2.7 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
2.8 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
2.9 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 coplandThis will install local ‘copland-0.2.0’ or remote ‘copland-0.2.0’.
gem install copland-0.2.0This will only succeed if the local file exists. This will not resolve to a remote gem.
gem install copland-0.2.0.gemgem 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
2.10 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 *** ...
2.11 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
2.12 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...
2.13 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.
2.14 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 ......
2.15 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
2.16 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.
2.17 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