The gem command is one of the most used Ruby-related commands, but most users don't take the time to learn anything past gem install and gem search. Learning the gem command well is an essential Ruby skill.
The gem command-line utility is split into a number of commands. Among these are the familiar install and search, but other useful commands exist such as spec and sources. However, you should start with the help command.
The gem command has integrated help. By running the command gem help, you can get a basic help screen. To get a list of commands available, run the gem help commands command. To get further help about a specific command, here, for example, the purge command, run the gem help purge command. Another useful help screen is the examples screen, accessible by the gem help examples command.
Most commands work on a gem repository, either local (the gems you have installed), or remote. Though, by default, it's the local repository. To specify the repository you intend , add either --remote or --local to the end of the command. For example, to search the remote repository for gems with the word "twitter" in them, you would run gem search twitter --remote. Specify both remote and local repositories by using the --both switch.
When running any gem command, the name can be shortened as long as it doesn't become ambiguous. To run a gem dependency command, you can simply run a gem dep command.
Below is a list of the commands and an explanation of their function.
build - Given the source code for a gem and a .gemspec file, this will build a .gem file suitable for uploading to a gem repository or installing on another computer with the gem command. A .gemspec file holds information about a gem including name, author, version and dependencies.
cert - Manages certificates for cryptographically signed gems. If you're worried that a malicious user is going to compromise the gems you install, you can cryptographically sign them to prevent this. Keys may be added or deleted from your list of acceptable keys, as well as a few other crypto key related functions.
check - Performs a number of actions, including running any unit tests, checking the checksum of installed gems and looking for unmanaged files in the gem repository. The type of check you wish to run must be added to the end of the gem command.
cleanup - Removes old versions of installed gems from your local repository. If you frequently upgrade gems, you can have old versions hanging around that you don't need anymore.
contents - Shows the contents of an installed gem. This is a list of files the gem installed and where they are on the filesystem.
dependency - Shows all the gems the listed gem depends upon, as well as the versions of the gem it depends upon. For example, running gem dep twitter tells me the twitter gem relies on hpricot, activesupport, httparty and echoe. This is useful when packaging your applications for deployment.
environment - Displays various information about the RubyGems environment, including the version installed, where it's installed, where the gem repository is, etc.
fetch - Fetches a gem and saves the .gem file in the current directory. This is useful for transferring gems to be deployed on other servers, without them needing to download the gem themselves.
generate_index - Generates an index for a gem server. This is only useful if you're running a gem repository.
install - Downloads a gem from the specified repository (--local or --remote) and install it. Also, downloads any dependencies and installs them as well. To install a specific version of a gem, use the --version switch.
list - Displays a list of gems in the repository. Note that doing this with --remote will generate quite a large list. Save this list to a file for fast searching.
lock - Generates a Ruby script that requires the exact version of all dependencies of a certain gem. This ensures that the gem versions tested during development will be installed, not future or past versions which may have bugs the developers cannot account for.
mirror - Mirrors an entire gem repository. Note that trying to mirror the RubyGems repository is a huge task. Do not do so unless you need to run a local mirror for other clients.
outdated - Displays a list of installed gems that have newer versions on the remote repository.
pristine - Returns gems to their original state. This means unpacking all gems from the local cache, overwriting any changes made to the gems in the local gem repository. This can be used to repair a broken gem.
rdoc - Generates rdoc documentation for an installed gem. This rdoc documentation can then be viewed with a web browser.
search - Searches the names of all gems and returns a list of gems whose name contains a string. For example, to search for all gems containing the word twitter in the name, run gem search twitter.
server - Starts a web server that will act as a gem repository and serves RDoc documentation for all installed gems. This is most useful for the documentation feature.
sources - Manages the list of sources for remote repositories. By default, only http://gems.rubyforge.org is in the list, but more can be added or removed.
specification - Displays the gemspec of a gem. This will tell you all the information about a gem, including author, dependencies, etc.
stale - Displays a list of installed gems, as well as the access times (the last time the gem was included). This can help you weed out gems you no longer user to uninstall them.
uninstall - Uninstalles a gem. If there are any installed gems that depend on this gem, you will be prompted whether you want to uninstall this gem. If you do, any gems that depended on this gem will be broken until it is reinstalled.
unpack - Unpacks an install gem into the current directory. This can be used to "freeze" gems to your project directory.
update - Checks if there are new versions of the specified gem in the remote repository. If there are, download and install the newest version.
which - Finds the exact location of the .rb file to include. This can be useful for getting a path for requiring a gem without requiring the rubygems library.