This chapter gives examples of the most common user opertions performed with the gem command. See the gem Command Reference manual for details about particular gem commands.

Versioning is a pretty basic concept in RubyGems. You might want to glance at the Specifying Versions chapter for a better understanding of how versions work with RubyGems.

When you run

gem query --remote        # shortcut: gem q -R

you see will a detailed list of all the gems on the remote server.

Sample output (heavily abbreviated):

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

BlueCloth (0.0.4, 0.0.3, 0.0.2)
    BlueCloth is a Ruby implementation of Markdown, a
    text-to-HTML conversion tool for web writers.
    Markdown allows you to write using an easy-to-read,
    easy-to-write plain text format, then convert it to
    structurally valid XHTML (or HTML).

captcha (0.1.2)
    Ruby/CAPTCHA is an implementation of the 'Completely
    Automated Public Turing Test to Tell Computers
    and Humans Apart'.

cardinal (0.0.4)
    Ruby to Parrot compiler.

cgikit (1.1.0)
    CGIKit is a componented-oriented web application
    framework like Apple Computers WebObjects.  This
    framework services Model-View-Controller architecture
    programming by components based on a HTML file, a
    definition file and a Ruby source.

progressbar (0.0.3)
    Ruby/ProgressBar is a text progress bar library for
    Ruby.  It can indicate progress with percentage, a
    progress bar, and estimated remaining time.

rake (0.4.0, 0.3.2)
    Ruby based make-like utility.

The progressbar gem is a nice and simple utility that we will use to demonstrate further features.

When you run

  gem query --remote --name-matches doom
  # shortcut: gem q -R -n doom

you will see a detailed list of matching gems on the remote server.

Sample output:

*** REMOTE GEMS ***

ruby-doom (0.8, 0.0.7)
    Ruby-DOOM provides a scripting API for creating DOOM
    maps. It also provides higher-level APIs to make map
    creation easier.

When you run

  gem query --remote --name-matches doom
  # shortcut: gem q -R -n doom

you will see a detailed list of matching gems on the remote server.

Sample output:

*** REMOTE GEMS ***

ruby-doom (0.8, 0.0.7)
    Ruby-DOOM provides a scripting API for creating DOOM
    maps. It also provides higher-level APIs to make map
    creation easier.

When you run (as root, if appropriate and necessary)

gem install --remote progressbar
# shortcut: gem i -r progressbar

the progressbar gem will be installed on your computer. Notice that you don’t need to specify the version, but you can if you want to. It will default to the last version available.

gem ins -r progressbar-0.0.3

or

gem ins -r progressbar --version '> 0.0.1'

In both cases, the output is simply:

Attempting remote installation of 'progressbar'
Successfully installed progressbar, version 0.0.3

RubyGems allows you to have multiple versions of a library installed and choose in your code which version you wish to use.

Useful extra options for installation are -gen-rdoc for generating the gem’s RDoc API documentation, and -run-tests to run the gem’s unit tests, if any.

Note too that when you remotely install a gem, it will download and install any specified dependencies. Try installing copland and see that it prompts you to accept log4r as well (if it’s not already installed).

When you run

gem specification  progressbar
# shortcut: gem spec progressbar

you will see all the details of the ’’progressbar’’ gem.

Sample output:

  --- !ruby/object:Gem::Specification
  rubygems_version:"1.0\" 
  name: progressbar
  version: !ruby/object:Gem::Version
    version: 0.0.3
  date: 2004-03-20 20:03:00.679937 +11:00
  platform:
  summary: "Ruby/ProgressBar is a text progress bar library for Ruby.  It can
            indicate progress with percentage, a progress bar, and estimated
            remaining time." 
  require_paths:
    - lib
  files:
    - sample/test.rb
    - lib/progressbar.rb
    - docs/progressbar.en.rd
    - docs/progressbar.ja.rd
    - ChangeLog
  autorequire: progressbar
  author: Satoru Takabayashi
  email: satoru@namazu.org
  homepage: http://namazu.org/~satoru/ruby-progressbar/

Some interesting information includes the author’s details, the version and description of the gem.

There is also important technical information for RubyGems to use this gem properly. This includes the list of files included, where to include files from, and what to require by default (more on this later).

If we’ve finished with progressbar, we can uninstall it.

gem uninstall progressbar

Sample output:

Successfully uninstalled progressbar version 0.0.3

If there are more than one version of a gem installed, the gem command will ask you which version to delete.

If there are other gems that depend upon the gem being uninstalled, and if there is no other way to satisfy that dependency, then the user will be will be given a warning and allowed to cancel the uninstall.

It’s easy:

gem query --local
# shortcut: 'gem q -L'

You’ve no doubt noticed the -local and -remote options on most of the command lines shown so far. If you don’t specify either of these, then gem will (usually) try ’’both’’ a local and remote operation. For example:

gem ins rake   # Attempt local installation; go remote if necessary
gem list -b ^C # List all local AND remote gems beginning with "C"

You can run your own gem server. This means other people can (potentially) install gems ’’from your computer’’. And as a side-effect of that, you can view your installed gems through your web browser. Just run

gem_server

and point your browser to http://localhost:8808.

You’ll be able to view the documentation for each gem, as long as you asked for it to be generated when you installed it.

If you want to always generate RDoc documentation and run unit tests for each gem you install, then you can specify these command-line options in a config file (.gemrc in your home directory).

gem: --gen-rdoc --run-tests

There are other things you can achieve with a config file (RDoc parameters, GEMPATH settings). See GemReference for the details.

gem check—alien will report on any rogue (unmanaged) files in the RubyGems repository area.

gem check—verify progressbar will check that the installed ’’progressbar’’ gem is valid against its own checksum.