Searching for Gems

You can add and install Ruby Gems by searching the Ruby Gems repository. Simply run the gem search command. By default, Ruby Gems only searches your local repository--the gems you already have installed. While this can be a useful way to search the gems you already have, it's not what is generally intended when the search command is run. To search the remote repositories, add the --remote or -r switch.

The basic form of a Ruby Gems search is a single search term with no arguments other than --remote. The search term will be matched against all of the Gems in the repository and results will include partial matches. For example, searching for cloth will match both the RedCloth and BlueCloth gems.

Below is an example search for cloth. A number of gems are printed, as well as their current version. What, exactly, the output is can be changed by the switches outlined below.

$ gem search --remote cloth

*** REMOTE GEMS ***

BlueCloth (1.0.0)
ClothRed (0.4.1)
mediacloth (0.0.3)
RedCloth (3.0.4)

A number of arguments can be supplied to define how the results should be printed to the terminal. The full list of these arguments can be accessed by running the command gem help search. Other help topics can be viewed by running the gem help command.

• -d, --details - Displays the RubyGem descriptions as well as their gem names and versions. This particularly useful when you're looking for gems related to a given topic. For example, when searching for gems to work with PDF files, if you don't have a specific gem in mind, searching for gems with pdf in the name and reading the descriptions can give you an idea of what's available.

• --local, --remote, --both - Defines where RubyGems should search for gems.
• -a, --all - Displays all versions of the gem in the repository. When a developer upgrades a gem version, the old gem is not deleted, since it may be necessary (at times) to install a previous version of a gem. By using this switch, RubyGems will display all versions of the gem it has in its repository.

Installing Gems

To install gems, you must have write access to the gem repository. On Linux or OS X, this means either getting a root terminal or using the sudo command to run RubyGems as root. The examples below will show how to do it with sudo, you'll need to refer to your operating system's documentation for instructions on how to run things as root. On Windows, you will not need to run the gem command as an Administrator user if, on the hard drive, you have write access to the gem directory.

Install gems with the gem install command. As with the search command, adding the --remote switch is necessary. You must also supply the full name, not just a search term as you did with the search command. Keep in mind that the names are also case sensitive: redcloth is not the same as RedCloth.

$ sudo gem install RedCloth
[sudo] password for username:
Updating metadata for 52 gems from http://gems.rubyforge.org/
....................................................
complete
Successfully installed RedCloth-3.0.4
1 gem installed

You can also install a specific version of a gem. For instance, it may be that you want to install an earlier version of RedCloth because a newer version has a bug or breaks a feature you need to use. In that care, you can use the --version switch, first runing a search command with the --all switch to see which versions are available.

$ gem search --remote --all redcloth

*** REMOTE GEMS ***

Bulk updating Gem source index for: http://gems.rubyforge.org/
Bulk updating Gem source index for: http://gems.rubyforge.org/
RedCloth (3.0.4, 3.0.3, 3.0.2, 3.0.1, 3.0.0, 2.0.11, 2.0.10,
  2.0.9, 2.0.8, 2.0.7, 2.0.6, 2.0.5, 2.0.4, 2.0.3, 2.0.2)

In this example, the version installed the latest in the 2.x series, 2.0.11. The --version switch takes a "version string" as an argument. A version string has an operator followed by a version number. The operator can be just = (the equals sign) meaning you want to install that exact gem version, but it can also be something like >= (greater than or equal to) to signify you want to install that version or any newer version.

$ sudo gem install --version '= 2.0.11' RedCloth
Bulk updating Gem source index for: http://gems.rubyforge.org/
Successfully installed RedCloth-2.0.11
1 gem installed