gem looks for a configuration file .gemrc in your home directory, although you can specify another file on the command-line if you wish (with the —config-file modifier). Only one configuration file will be processed: the rightmost one on the command-line, or the default $HOME/.gemrc, or none at all.

There are three things you can specify in the configuration file:

• command-line arguments to be used every time gem runs
• command-line options for ’’RDoc’’ (used when generating docuemntation)
• GEMPATH settings

The config file itself is in ’’‘YAML’’’ format. Here is an example:

  gem:  --local --gen-rdoc --run-tests
  rdoc: --inline-source --line-numbers
  gempath:
    - /usr/local/rubygems
    - /home/gavin/.rubygems

The effects of such a config file would be:

• gem only runs ’’local’’ operations (unless you specify -remote or -both on the command-line)
• gem generates RDocs and runs unit tests every time it installs something (good idea!)
• when it generates RDocs, the given arguments will be used
• /usr/local/rubygems and /home/gavin/rubygems will be used as your $GEM_PATH setting

gem

The gem configuration item specifies the command-line options you wish to include every time you run gem.

The effect of including options here is the same as including them at the start of the command-line. That means they may be overridden by later options.

For example, you you have a poor internet connection, then you probably don’t want gem to go to the internet all the time by default. Thus, you should include

gem: --local

in your configuration file. However, when you ’’do’’ want to remotely install something, you can run

gem install something --remote

to override the value in the config file.

Other good uses for this config item are:

• —gen-rdoc to generate documentation on every install
• —run-tests to run unit tests on every install
• —install-stub to install a library stub on every install
• —http-proxy, or some variant, if you have certain proxy requirements

rdoc

The rdoc configuration item specifies the command-line options you would like to pass to rdoc when it is generating documentation for an installed gem.

The purpose of this is so that you can tailor the output that RDoc generates. See rdoc—help for a full list, but here are some things you might want to use:

• —all to include all methods, not just public ones
• —charset to specify the HTML charset to use
• —diagram, if you can get that to work (requires graphviz)
• —line-numbers, if you want source code to have line numbers
• —inline-source, if you want methods to have their source code displayed
• —template to specify the template to be used (e.g. “kilmer”)
• —style to specify your own stylesheet URL

gemhome

gemhome is the location of the gem repository where your gems will be installed.

This value will override the GEM_HOME environment variable. Both may be overridden by the —install-dir command line options.

If not specified, then the first repository in the gem path will be used (see gempath below).

gempath

gempath is an array of directories where you have gems installed. The first entry will be used as the default gem installation directory (unless an explicit gemhome config setting or GEM_HOME environment setting is found.

This value will override the value of the environment variable GEM_PATH.

This is useful if you have gems installed in several places.

The default value for this is the system wide gem repository in the ruby installation directory.

Here is a simple example. We always specify the -gem-rdoc option to generate the documentation when we install a package. The locally specified -line-numbers and —template html will override the options specified in the gem file.

  gem: --gen-rdoc
  rdoc: --line-numbers --template html

This user isn’t able to install gems into the standard system location, so they provide a local gem repository. We make sure that the system wide gem repository is still in the path so that gems installed there can be found.

  gemhome: /home/a_user/.gems
  gempath:
    - /usr/local/lib/ruby/gems/1.8