123456789_123456789_123456789_123456789_123456789_

RubyGems 3.5.22 Command Reference

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

This reference was automatically generated from RubyGems version 3.5.22.

gem build

Build a gem from a gemspec

Usage

gem build GEMSPEC_FILE [options]

Options

Common Options

Arguments

Description

The build command allows you to create a gem from a ruby gemspec.

The best way to build a gem is to use a Rakefile and the ::Gem::PackageTask which ships with RubyGems.

The gemspec can either be created by hand or extracted from an existing gem with gem spec:

$ gem unpack my_gem-1.0.gem
Unpacked gem: '.../my_gem-1.0'
$ gem spec my_gem-1.0.gem --ruby > my_gem-1.0/my_gem-1.0.gemspec
$ cd my_gem-1.0
[edit gem contents]
$ gem build my_gem-1.0.gemspec

Gems can be saved to a specified filename with the output option:

$ gem build my_gem-1.0.gemspec --output=release.gem

gem cert

Manage RubyGems certificates and signing settings

Usage

gem cert [options]

Options

Common Options

Description

The cert command manages signing keys and certificates for creating signed gems. Your signing certificate and private key are typically stored in ~/.gem/gem-public_cert.pem and ~/.gem/gem-private_key.pem respectively.

To build a certificate for signing gems:

gem cert --build you@example

If you already have an RSA key, or are creating a new certificate for an existing key:

gem cert --build you@example --private-key /path/to/key.pem

If you wish to trust a certificate you can add it to the trust list with:

gem cert --add /path/to/cert.pem

You can list trusted certificates with:

gem cert --list

or:

gem cert --list cert_subject_substring

If you wish to remove a previously trusted certificate:

gem cert --remove cert_subject_substring

To sign another gem author's certificate:

gem cert --sign /path/to/other_cert.pem

For further reading on signing gems see ri Gem::Security.

gem check

Check a gem repository for added or missing files

Usage

gem check [OPTIONS] [GEMNAME ...] [options]

Options

Common Options

Arguments

Description

The check command can list and repair problems with installed gems and specifications and will clean up gems that have been partially uninstalled.

gem cleanup

Clean up old versions of installed gems

Usage

gem cleanup [GEMNAME ...] [options]

Options

Deprecated Options

Common Options

Arguments

Description

The cleanup command removes old versions of gems from GEM_HOME that are not required to meet a dependency. If a gem is installed elsewhere in GEM_PATH the cleanup command won't delete it.

If no gems are named all gems in GEM_HOME are cleaned.

gem contents

Display the contents of the installed gems

Usage

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

Options

Common Options

Arguments

Description

The contents command lists the files in an installed gem. The listing can be given as full file names, file names without the installed directory prefix or only the files that are requireable.

gem dependency

Show the dependencies of an installed gem

Usage

gem dependency REGEXP [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Arguments

Description

The dependency commands lists which other gems a given gem depends on. For local gems only the reverse dependencies can be shown (which gems depend on the named gem).

The dependency list can be displayed in a format suitable for piping for use with other commands.

gem environment

Display information about the RubyGems environment

Usage

gem environment [arg] [options]

Common Options

Arguments

Description

The environment command lets you query rubygems for its configuration for use in shell scripts or as a debugging aid.

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 a ~/.gemrc file for individual users and a gemrc in the SYSTEM CONFIGURATION DIRECTORY for all users. These files are YAML files 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
:disable_default_gem_server: Force specification of gem server host on push
<gem_command>: A string containing arguments for the specified gem command

Example:

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

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 would like to push gems to a private gem server the RUBYGEMS_HOST environment variable can be set to the URI for that 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 exec

Run a command from a gem

Usage

gem exec [options --] COMMAND [args] [options]

Options

Install/Update Options

Common Options

Arguments

Description

The exec command handles installing (if necessary) and running an executable from a gem, regardless of whether that gem is currently installed.

The exec command can be thought of as a shortcut to running gem install and then the executable from the installed gem.

For example, gem exec rails new . will run rails new . in the current directory, without having to manually run gem install rails. Additionally, the exec command ensures the most recent version of the gem is used (unless run with --conservative), and that the gem is not installed to the same gem path as user-installed gems.

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

Description

The fetch command fetches gem files that can be stored for later use or unpacked to examine their contents.

See the build command help for an example of unpacking a gem, modifying it, then repackaging it.

gem generate_index

Generates the index files for a gem server directory (requires rubygems-generate_index)

Usage

gem generate_index [options]

Common Options

Description

The generate_index command has been moved to the rubygems-generate_index gem.

gem help

Provide help on the 'gem' command

Usage

gem help ARGUMENT [options]

Common Options

gem info

Show information for the given gem

Usage

gem info GEMNAME [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Arguments

Description

Info prints information about the gem such as name, description, website, license and installed paths

gem install

Install a gem into the local repository

Usage

gem install [options] GEMNAME [GEMNAME ...] -- --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.

Gem Dependency Files

RubyGems can install a consistent set of gems across multiple environments using gem install -g when a gem dependencies file (gem.deps.rb, Gemfile or Isolate) is present. If no explicit file is given RubyGems attempts to find one in the current directory.

When the RUBYGEMS_GEMDEPS environment variable is set to a gem dependencies file the gems from that file will be activated at startup time. Set it to a specific filename or to "-" to have RubyGems automatically discover the gem dependencies file by walking up from the current directory.

NOTE: Enabling automatic discovery on multiuser systems can lead to execution of arbitrary code when used from directories outside your control.

Extension Install Failures

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

Command Alias

You can use i command instead of install.

$ gem i GEMNAME

gem list

Display local gems whose name matches REGEXP

Usage

gem list [REGEXP ...] [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Arguments

Description

The list command is used to view the gems you have installed locally.

The --details option displays additional details including the summary, the homepage, the author, the locations of different versions of the gem.

To search for remote gems use the search command.

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:

gem lock rails-1.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 mirror

Mirror all gem files (requires rubygems-mirror)

Usage

gem mirror [options]

Common Options

Description

The mirror command has been moved to the rubygems-mirror gem.

gem open

Open gem sources in editor

Usage

gem open [-e COMMAND] GEMNAME [options]

Options

Common Options

Arguments

Description

The open command opens gem in editor and changes current path
to gem's source directory.
Editor command can be specified with -e option, otherwise rubygems
will look for editor in $EDITOR, $VISUAL and $GEM_EDITOR variables.

gem outdated

Display all gems that need updates

Usage

gem outdated [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Description

The outdated command lists gems you may wish to upgrade to a newer version.

You can check for dependency mismatches using the dependency command and update the gems with the update or install commands.

gem owner

Manage gem owners of a gem on the push server

Usage

gem owner GEM [options]

Options

Local/Remote Options

Common Options

Arguments

Description

The owner command lets you add and remove owners of a gem on a push server (the default is https://rubygems.org). Multiple owners can be added or removed at the same time, if the flag is given multiple times.

The supported user identifiers are dependent on the push server. For rubygems.org, both e-mail and handle are supported, even though the user identifier field is called "email".

The owner of a gem has the permission to push new versions, yank existing versions or edit the HTML page of the gem. Be careful of who you give push permission to.

gem pristine

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

Usage

gem pristine [GEMNAME ...] [options]

Options

Common Options

Arguments

Description

The pristine command compares an installed gem with the contents of its cached .gem file and restores any files that don't match the cached .gem's copy.

If you have made modifications to an installed gem, the pristine command will revert them. All extensions are rebuilt and all bin stubs for the gem are regenerated after checking for modifications.

If the cached gem cannot be found it will be downloaded.

If --no-extensions is provided pristine will not attempt to restore a gem with an extension.

If --extensions is given (but not --all or gem names) only gems with extensions will be restored.

gem push

Push a gem up to the gem server

Usage

gem push GEM [options]

Options

Local/Remote Options

Common Options

Arguments

Description

The push command uploads a gem to the push server (the default is https://rubygems.org) and adds it to the index.

The gem can be removed from the index and deleted from the server using the yank command. For further discussion see the help for the yank command.

The push command will use ~/.gem/credentials to authenticate to a server, but you can use the RubyGems environment variable GEM_HOST_API_KEY to set the api key to authenticate.

gem query

Query gem information in local or remote repositories

Usage

gem query [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Description

The query command is the basis for the list and search commands.

You should really use the list and search commands instead. This command is too hard to use.

gem rdoc

Generates RDoc for pre-installed gems

Usage

gem rdoc [args] [options]

Options

Common Options

Arguments

Description

The rdoc command builds documentation for installed gems. By default only documentation is built using rdoc, but additional types of documentation may be built through rubygems plugins and the Gem.post_installs hook.

Use --overwrite to force rebuilding of documentation.

gem rebuild

Attempt to reproduce a build of a gem.

Usage

gem rebuild GEM_NAME GEM_VERSION [options]

Options

Common Options

Arguments

Description

The rebuild command allows you to (attempt to) reproduce a build of a gem from a ruby gemspec.

This command assumes the gemspec can be built with the gem build command. If you use any of gem build, rake build, orrake release in the build/release process for a gem, it is a potential candidate.

You will need to match the RubyGems version used, since this is included in the Gem metadata.

If the gem includes lockfiles (e.g. Gemfile.lock) and similar, it will require more effort to reproduce a build. For example, it might require more precisely matched versions of Ruby and/or Bundler to be used.

gem search

Display remote gems whose name matches REGEXP

Usage

gem search [REGEXP] [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Arguments

Description

The search command displays remote gems whose name matches the given regexp.

The --details option displays additional details from the gem but will take a little longer to complete as it must download the information individually from the index.

To list local gems use the list command.

gem server

Starts up a web server that hosts the RDoc (requires rubygems-server)

Usage

gem server [options]

Common Options

Description

The server command has been moved to the rubygems-server gem.

gem signin

Sign in to any gemcutter-compatible host. It defaults to https://rubygems.org

Usage

gem  [options]

Options

Common Options

Description

The signin command executes host sign in for a push server (the default is https://rubygems.org). The host can be provided with the host flag or can be inferred from the provided gem. Host resolution matches the resolution strategy for the push command.

gem signout

Sign out from all the current sessions.

Usage

gem signout [options]

Common Options

Description

The signout command is used to sign out from all current sessions, allowing you to sign in using a different set of credentials.

gem sources

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

Usage

gem sources [options]

Options

Local/Remote Options

Common Options

Description

RubyGems fetches gems from the sources you have configured (stored in your ~/.gemrc).

The default source is https://rubygems.org, but you may have other sources configured. This guide will help you update your sources or configure yourself to use your own gem server.

Without any arguments the sources lists your currently configured sources:

$ gem sources
*** CURRENT SOURCES ***

https://rubygems.org

This may list multiple sources or non-rubygems sources. You probably configured them before or have an old ~/.gemrc. If you have sources you do not recognize you should remove them.

RubyGems has been configured to serve gems via the following URLs through its history:

Since all of these sources point to the same set of gems you only need one of them in your list. https://rubygems.org is recommended as it brings the protections of an SSL connection to gem downloads.

To add a source use the --add argument:

$ gem sources --add https://rubygems.org
https://rubygems.org added to sources

RubyGems will check to see if gems can be installed from the source given before it is added.

To remove a source use the --remove argument:

$ gem sources --remove https://rubygems.org/
https://rubygems.org/ removed from sources

gem specification

Display gem specification (in yaml)

Usage

gem specification [GEMFILE] [FIELD] [options]

Options

Deprecated Options

Local/Remote Options

Common Options

Arguments

Description

The specification command allows you to extract the specification from a gem for examination.

The specification can be output in YAML, ruby or Marshal formats.

Specific fields in the specification can be extracted in YAML format:

$ gem spec rake summary
--- Ruby based make-like utility.
#...

gem stale

List gems along with access times

Usage

gem stale [options]

Common Options

Description

The stale command lists the latest access time for all the files in your installed gems.

You can use this command to discover gems and gem versions you are no longer using.

gem uninstall

Uninstall gems from the local repository

Usage

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

Options

Common Options

Arguments

Description

The uninstall command removes a previously installed gem.

RubyGems will ask for confirmation if you are attempting to uninstall a gem that is a dependency of an existing gem. You can use the --ignore-dependencies option to skip this check.

gem unpack

Unpack an installed gem to the current directory

Usage

gem unpack GEMNAME [options]

Options

Install/Update Options

Common Options

Arguments

Description

The unpack command allows you to examine the contents of a gem or modify them to help diagnose a bug.

You can add the contents of the unpacked gem to the load path using the RUBYLIB environment variable or -I:

$ gem unpack my_gem
Unpacked gem: '.../my_gem-1.0'
[edit my_gem-1.0/lib/my_gem.rb]
$ ruby -Imy_gem-1.0/lib -S other_program

You can repackage an unpacked gem using the build command. See the build command help for an example.

gem update

Update installed gems to the latest version

Usage

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

Options

Deprecated Options

Install/Update Options

Local/Remote Options

Common Options

Arguments

Description

The update command will update your gems to the latest version.

The update command does not remove the previous version. Use the cleanup command to remove old versions.

gem which

Find the location of a library file you can require

Usage

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

Options

Common Options

Arguments

Description

The which command is like the shell which command and shows you where the file you wish to require lives.

You can use the which command to help determine why you are requiring a version you did not expect or to look at the content of a file you are requiring to see why it does not behave as you expect.

gem yank

Remove a pushed gem from the index

Usage

gem yank -v VERSION [-p PLATFORM] [--key KEY_NAME] [--host HOST] GEM [options]

Options

Common Options

Arguments

Description

The yank command permanently removes a gem you pushed to a server.

Once you have pushed a gem several downloads will happen automatically via the webhooks. If you accidentally pushed passwords or other sensitive data you will need to change them immediately and yank your gem.