---
book:
- chapter:
- title: Overview
page:
- body: "gem is the command-line interface to RubyGems. With it, you can install gems locally or remotely, see what you have installed, search for gems, and more.\r\n\
\r\n\
It works on the following basis: you specify an operation and optionally some modifiers. Finally, you can have a configuration file to specify commonly-used command-line arguments and other settings.\r\n\
\r\n\
See the QuickIntroduction for a task-driven hands-on overview of gem's main features.\r\n\
\r\n\
This reference covers 'gem' version 0.8.7. "
title: Introduction
- body: |
gem is based on ''commands'', like build, install, and search. See the Table of Contents for a full list.
Each command takes ''arguments'' and/or ''options''. For example, if you run
gem install rake --remote
then install is the command, rake is the argument, and --remote is an option. (By the way, this command installs rake
remotely.)
gem provides most of the help you need inline.
* To see a list of commands, run gem help commands.
* To get help on the install command, run gem help install.
* To see some examples of common usage, run gem help examples.
* For a reminder of all this, just run gem help.
The help on each command is also included in this document.
title: Getting Help
- title: Command Reference
page:
- body: |+
The build command is used by developers to package their Ruby software
into a single gem file that can be distributed. The build command
requires a gemspec file to describe the metadata in the packge. You
can see a good example of using build in CreateAGemInTenMinutes.
A yaml file containing the Gem::Specification object built by a
gemspec (instead of a gemspec file) may also be also be used with the
build command.
h3. Usage
Usage: gem build GEMSPEC_FILE [options]
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMSPEC_FILE name of gemspec file used to build the gem
Summary:
Build a gem from a gemspec
h3. Examples
This example builds a the rake package from a gemspec file.
$ gem build rake.gemspec
Attempting to build gem spec 'rake.gemspec'
Successfully built RubyGem
Name: rake
Version: 0.4.0
File: rake-0.4.0.gem
Of course, rake isn't normally built from a gemspec. It uses a
special gem building task to build the gem directly from the rakefile.
See CreateAGemUsingRake for more details.
$ rake gem
(in /home/jim/working/rubyforge/rake)
Successfully built RubyGem
Name: rake
Version: 0.4.0
File: rake-0.4.0.gem
title: gem build -- Build a gem file from a specification
- body: |+
The cert command manages the certificates needed to sign gems.
h3. Usage
Usage: gem cert [options]
Options:
-a, --add CERT Add a trusted certificate.
-l, --list List trusted certificates.
-r, --remove STRING Remove trusted certificates containing STRING.
-b, --build EMAIL_ADDR Build private key and self-signed certificate for EMAIL_ADDR.
-C, --certificate CERT Certificate for --sign command.
-K, --private-key KEY Private key for --sign command.
-s, --sign NEWCERT Sign a certificate with my key and certificate.
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Summary:
Adjust RubyGems certificate settings.
See the "chapter on signing
gems":http://docs.rubygems.org/read/chapter/21 in the :Ruby Users
Guide":http://docs.rubygems.org/read/book/1 for details.
h3. Examples
Build a private key and certificate for gemmaster@example.com.
Substitute your own email address for your own certificates.
$ gem cert --build gemmaster@example.com
Add a certificate to the list of trusted certificates. The trusted
certificate list will be consulted when installing signed gems.
$ gem cert --add gem-public_cert.pem
Sign a certificate with the specified key and certificate (note that
this modifies client_cert.pem!)
$ gem cert \
-K /mnt/floppy/issuer-priv_key.pem \
-C issuer-pub_cert.pem \
--sign client_cert.pem
title: gem cert -- Support signing and managing signed gems
- body: |+
The check command is used to verify that a gem in is good working order.
h3. Usage
Usage: gem check [options]
Options:
-v, --verify FILE Verify gem file against its internal checksum
-a, --alien Report 'unmanaged' or rogue files in the gem repository
-t, --test Run unit tests for gem
-V, --version Specify version for which to run unit tests
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Summary:
Check installed gems
The verify option checks a gem file for corruption. If the file is
not exactly like it was built, verify will complain. (Note: This is a
simple integrity check. It is not checking for PGP like signatures).
The alien option checks an installed gem to see if any of the files
have been tampered with.
h3. Examples
The following check is run against a valid rake gem file.
$ gem check -v pkg/rake-0.4.0.gem
Verifying gem: 'pkg/rake-0.4.0.gem'
The following check shows that the rake gem file is invalid.
$ gem check -v pkg/rake-0.4.0.gem
Verifying gem: 'pkg/rake-0.4.0.gem'
ERROR: pkg/rake-0.4.0.gem is invalid.
In this installation of ActiveRecord, the postgreSQL driver
has been locally patched after the gem was installed. This is how the alien
option reports it.
$ gem check --alien
Performing the 'alien' operation
madeleine-0.6 is error-free
madeleine-0.6.1 is error-free
rake-0.4.0 is error-free
rake-0.3.2 is error-free
copland-0.3.0 is error-free
sources-0.0.1 has 2 problems
iterator-0.5 is error-free
activerecord-0.8.1 has 2 problems
lib/active_record/connection_adapters/postgresql_adapter.rb:
installed file doesn't match original from gem
/usr/local/lib/ruby/gems/1.8/cache/activerecord-0.8.1.gem:
Unmanaged files in gem: ["lib/active_record/connection_adapters/postgresql_adapter.rb~"]
[... remaining output elided ...]
title: gem check -- Check installed gems for problems
- body: |+
(new in version 0.8.7)
This command will remove (uninstall) all the versions of a gem, except
for the latest one. If no gemname is given in the command line, cleanup will be run agains all installed gems.
h3. Usage
Usage: gem cleanup [options]
Options:
-d, --dryrun
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME(s) name of gem(s) to cleanup
Summary:
Cleanup old versions of installed gems in the local repository
Defaults:
--no-dryrun
h3. Examples
$ gem cleanup
Rubygems Environment:
- VERSION: 0.6 (0.6.1)
- INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/1.8
- GEM PATH:
- /usr/local/lib/ruby/gems/1.8
- REMOTE SOURCES:
- http://gems.rubyforge.org
title: gem cleanup -- Cleanup old versions in the repository
- body: |+
(new in version 0.8.11)
The @contents@ command will list the full path names of all the files
contained in the gem.
h3. Usage
Usage: gem contents [options]
Options:
-l, --list List the files inside a Gem
-V, --version Specify version for gem to view
-s, --spec-dir a,b,c Search for gems under specific paths
-v, --verbose Be verbose when showing status
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Summary:
Disply the contents of the installed gems
h3. Examples
The following command displays the files included in the Rake gem.
$ gem contents rake
traken$ gem inspect rake
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/install.rb
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/CHANGES
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/Rakefile
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/README
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/TODO
[... truncated ...]
h3. Limitations
Currently there is no way to specify the version of the gem you wish
to view.
title: gem contents -- Display the files contained in an installed gem
- body: |+
The @dependency@ command displays the declared dependencies of any install gem package.
h3. Usage
Usage: gem dependency GEMNAME [options]
Options:
-v, --version VERSION Specify version of gem to uninstall
-r, --[no-]reverse-dependencies Include reverse dependencies in the output
-p, --pipe Pipe Format (name --version ver)
Common Options:
--source URL Use URL as the remote source for gems
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME name of gems to show
Summary:
Show the dependencies of an installed gem
Defaults:
--version '> 0' --no-reverse
h3. Examples
Here is the dependencies of the Rails gem.
$ gem dependency rails -v 0.10.1
Gem rails-0.10.1
Requires
rake (>= 0.4.15)
activesupport (= 1.0.1)
activerecord (= 1.8.0)
actionpack (= 1.5.1)
actionmailer (= 0.7.1)
actionwebservice (= 0.6.0)
Adding a @--reverse-dependencies@ option adds the following bit of information:
$ gem dependency rails -v 0.10.1 --reverse-dependencies
Gem rails-0.10.1
Requires
rake (>= 0.4.15)
activesupport (= 1.0.1)
activerecord (= 1.8.0)
actionpack (= 1.5.1)
actionmailer (= 0.7.1)
actionwebservice (= 0.6.0)
Used by
storycards-0.0.2 (rails (>= 0.7.0))
Finally, the @--pipe@ option for the dependency command puts out the dependencies in a format that could be piped to another command.
$ gem dependency rails -v 0.10.1 --pipe
rake --version '>= 0.4.15'
activesupport --version '= 1.0.1'
activerecord --version '= 1.8.0'
actionpack --version '= 1.5.1'
actionmailer --version '= 0.7.1'
actionwebservice --version '= 0.6.0'
title: gem dependency -- List the dependencies of a gem
- body: |+
Gems uses several paths and directories to perform its work. This
command will display the information the gem command has found.
h3. Usage
Usage: gem environment [args] [options]
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
packageversion display the package version
gemdir display the path where gems are installed
gempath display path used to search for gems
version display the gem format version
remotesources display the remote gem servers
display everything
Summary:
Display RubyGems environmental information
h3. Examples
$ gem environment
Rubygems Environment:
- VERSION: 0.6 (0.6.1)
- INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/1.8
- GEM PATH:
- /usr/local/lib/ruby/gems/1.8
- REMOTE SOURCES:
- http://gems.rubyforge.org
title: gem environment -- Display information about the gem environment
- body: |+
gem help provides information about the syntax and options
available on the gem command.
h3. Usage
Usage: gem help ARGUMENT [options]
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
commands List all 'gem' commands
examples Show examples of 'gem' usage
Show specific help for
Summary:
Provide help on the 'gem' command
title: gem help -- Provide help about gem commands
- body: |+
gem install will install the named gem. It will
attempt a local installation (i.e. a .gem file in the current
directory), and if that fails, it will attempt to download and install
the most recent version of the gem you want.
If a gem is being installed remotely, and it depends on other gems
that are not installed, then gem will download and install those,
after you have confirmed the operation.
h3. Usage
Usage: gem install GEMNAME [options]
Options:
-v, --version VERSION Specify version of gem to install
-l, --local Restrict operations to the LOCAL domain (default)
-r, --remote Restrict operations to the REMOTE domain
-b, --both Allow LOCAL and REMOTE operations
-i, --install-dir DIR
-d, --[no-]rdoc Generate RDoc documentation for the gem on install
-f, --[no-]force Force gem to install, bypassing dependency checks
-t, --[no-]test Run unit tests prior to installation
-w, --[no-]wrappers Use bin wrappers for executables
Not available on dosish platforms
-P, --trust-policy POLICY Specify gem trust policy.
--ignore-dependencies Do not install any required dependent gems
-y, --include-dependencies Unconditionally install the required dependent gems
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME name of gem to install
Summary:
Install a gem into the local repository
Defaults:
--both --version '> 0' --rdoc --no-force --no-test
--install-dir /usr/local/lib/ruby/gems/1.8
h3. Examples
These examples show how GEMNAME can be specified:
This will install local 'copland.gem' or remote 'copland-0.3.0' (for
instance), but not a local file 'copland-0.3.0' gem.
gem install copland
This will install local 'copland-0.2.0' or remote 'copland-0.2.0'.
gem install copland-0.2.0
This will only succeed if the local file exists. This will not resolve to a remote gem.
gem install copland-0.2.0.gem
gem install --remote copland # shortcut: gem ins -R copland
gem install copland --version '> 0.2'
gem install copland --gen-rdoc --run-tests
gem install copland --install-stub
Here is an example session where a dependency is automatically
downloaded and resolved.
$ gem install copland
Attempting local installation of ''
Local gem file not found: copland.gem
Attempting remote installation of 'copland'
Install required dependency log4r? [Yn] y
Successfully installed copland, version 0.3.0
title: gem install -- Installing a gem
- body: |+
gem list will list all gems whose name starts with the given
string. If no string is provided, all gems are listed.
h3. Usage
Usage: gem list [STRING] [options]
Options:
-d, --[no-]details Display detailed information of gem(s)
-l, --local Restrict operations to the LOCAL domain (default)
-r, --remote Restrict operations to the REMOTE domain
-b, --both Allow LOCAL and REMOTE operations
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
STRING start of gem name to look for
Summary:
Display all gems whose name starts with STRING
Defaults:
--local --no-details
h3. Examples
List all remote gems starting with "a".
$ gem list -r a
*** 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.
arrayfields (3.3.0)
Allow keyword access to arrays
List all gems, local and remote.
$ gem list --both
*** LOCAL GEMS ***
...
*** REMOTE GEMS ***
...
title: gem list -- List gems starting with a string
- body: |+
gem query will list all gems matching a particular criteria.
The domain may be local, remote or both.
h3. Usage
Usage: gem query [options]
Options:
-n, --name-matches REGEXP Name of gem(s) to query on maches the provided REGEXP
-d, --[no-]details Display detailed information of gem(s)
-l, --local Restrict operations to the LOCAL domain (default)
-r, --remote Restrict operations to the REMOTE domain
-b, --both Allow LOCAL and REMOTE operations
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Summary:
Query gem information in local or remote repositories
Defaults:
--local --name-matches '.*' --no-details
h3. Examples
To list all local gems with a digit in the gem name:
$ gem query -n '[0-9]' --local
*** LOCAL GEMS ***
jabber4r (0.7.0)
Jabber4r is a pure-Ruby Jabber client library
log4r (1.0.5)
Log4r is a comprehensive and flexible logging library for Ruby.
To list all remote gems that begin with the letter 'm':
$ gem query -R -n ^m
*** REMOTE GEMS ***
madeleine (0.6.1, 0.6)
Madeleine is a Ruby implementation of Object Prevalence
midilib (0.8.0)
MIDI file and event manipulation library
title: gem query -- Query for a list of gems
- body: |+
gem rdoc will generate the RDoc files for an installed gem.
The files are put in the standard gem RDoc location so that
@gem_server@ can find them.
h3. Usage
Usage: gem rdoc [args] [options]
Options:
--all Generate RDoc documentation for all installed gems
-v, --version VERSION Specify version of gem to rdoc
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME The gem to generate RDoc for (unless --all)
Summary:
Generates RDoc for pre-installed gems
Defaults:
--version '> 0.0.0'
h3. Examples
The following command generates the RDoc files for the rake-0.5.4 gem.
traken$ sudo gem rdoc rake --version 0.5.4
Installing RDoc documentation for rake-0.5.4...
title: gem rdoc -- Generate the RDoc files for an installed gem
- body: |+
gem search will list all gems whose name contains the given
(case-insensitive) string. If no string is provided, all gems will be listed.
h3. Usage
Usage: gem search [STRING] [options]
Options:
-d, --[no-]details Display detailed information of gem(s)
-l, --local Restrict operations to the LOCAL domain (default)
-r, --remote Restrict operations to the REMOTE domain
-b, --both Allow LOCAL and REMOTE operations
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
STRING fragment of gem name to look for
Summary:
Display all gems whose name contains STRING
Defaults:
--local --no-details
h3. Examples
List all remote gems containing "log" in their name.
$ gem search -r log
*** REMOTE GEMS ***
log4r (1.0.5)
Log4r is a comprehensive and flexible logging library for Ruby.
rublog (0.8.0)
RubLog is a simple web log, based around the idea of displaying a
set of regular files in a log-format.
title: gem search -- List gems containing a string
- body: |+
The specification command will extract the Gem::Specification from a
gem file and write to standard output in YAML format.
h3. Usage
Usage: gem specification GEMFILE [options]
Options:
-v, --version VERSION Specify version of gem to examine
-l, --local Restrict operations to the LOCAL domain (default)
-r, --remote Restrict operations to the REMOTE domain
-b, --both Allow LOCAL and REMOTE operations
--all Output specifications for all versions of the gem
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMFILE Name of a .gem file to examine
Summary:
Display gem specification (in yaml)
Defaults:
--local --version '(latest)'
h3. Examples
Here is the specification from rake 0.4.1.
$ gem spec rake -v 0.4.1
--- !ruby/object:Gem::Specification
rubygems_version: "0.6"
name: rake
version: !ruby/object:Gem::Version
version: 0.4.1
date: 2004-07-02 01:08:54.678603 -04:00
platform:
summary: Ruby based make-like utility.
require_paths:
- lib
files:
- install.rb
- CHANGES
- Rakefile
- README
- TODO
- MIT-LICENSE
- bin/rake
- lib/rake.rb
- lib/rake/clean.rb
......
title: gem specification -- Extract the Gem::Specification from a gem file
- body: |+
The uninstall will uninstall the named gem. If multiple versions of a
gem are installed, you will be prompted to select a single one, or all
of them.
h3. Usage
Usage: gem uninstall GEMNAME [options]
Options:
-a, --[no-]all Uninstall all matching versions
-i, --[no-]ignore-dependencies Ignore dependency requirements while uninstalling
-x, --[no-]executables Uninstall applicable executables without confirmation
-v, --version VERSION Specify version of gem to uninstall
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME name of gem to uninstall
Summary:
Uninstall a gem from the local repository
Defaults:
--version '> 0' --no-force
h3. Examples
The following uninstalls the only copy of copland.
$ gem uninstall copland
Attempting to uninstall gem 'copland'
Successfully uninstalled copland version 0.3.0
The following uninstalls all the installed versions of the rake gem.
Since rake is an application, it has a ApplicationStub installed. The
uninstall removes the stub as well.
$ sudo gem uninstall rake
Attempting to uninstall gem 'rake'
Select RubyGem to uninstall:
1. rake-0.3.2
2. rake-0.4.0
3. All versions
> 3
Successfully uninstalled rake version 0.3.2
Successfully uninstalled rake version 0.4.0
WARNING: About to remove executables and scripts for: rake
Proceed? [Y/n] y
Removing rake
title: gem uninstall -- Uninstalling a gem
- body: |+
(Not in version 0.7.)
The unpack command creates a private copy of the named gem's contents into a
new directory. This enables you to examine the contents without interfering
with the gem repository.
You can only unpack gems that you have installed, and you must specify the gem
name exactly.
h3. Usage
Usage: gem unpack GEMNAME [options]
Options:
-v, --version VERSION Specify version of gem to unpack
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME Name of the gem to unpack
Summary:
Unpack an installed gem to the current directory
Defaults:
--version '> 0'
h3. Examples
$ gem unpack rake
Unpacked gem: 'rake-0.4.3'
$ ls rake-0.4.3/
CHANGES MIT-LICENSE README Rakefile TODO bin doc install.rb lib test
$ gem unpack wazoo
ERROR: Gem 'wazoo' not installed.
title: gem unpack -- Unpack an installed gem to the current directory
- body: |+
The update command will check the named gem (or all of your installed
gems if no name is given) and update each one to a newer version if
one is available.
h3. Usage
Usage: gem update [options]
Options:
-i, --install-dir DIR
-d, --[no-]rdoc Generate RDoc documentation for the gem on install
-f, --[no-]force Force gem to install, bypassing dependency checks
-t, --[no-]test Run unit tests prior to installation
-w, --[no-]wrappers Use bin wrappers for executables
Not available on dosish platforms
-P, --trust-policy POLICY Specify gem trust policy.
--ignore-dependencies Do not install any required dependent gems
-y, --include-dependencies Unconditionally install the required dependent gems
--system Update the RubyGems system software
Common Options:
--source URL Use URL as the remote source for gems
-p, --[no-]http-proxy [URL] Use HTTP proxy for remote operations
-h, --help Get help on this command
--config-file FILE Use this config file instead of default
--backtrace Show stack backtrace on errors
--debug Turn on Ruby debugging
Arguments:
GEMNAME(s) name of gem(s) to update
Summary:
Upgrade the named gem (or all installed gems) in the local repository
Defaults:
--rdoc --no-force --no-test
--install-dir /usr/local/lib/ruby/gems/1.8
h3. Examples
$ gem update
Upgrading installed gems...
Attempting remote upgrade of activerecord
Attempting remote installation of 'activerecord'
Successfully installed activerecord, version 0.8.4
Attempting remote upgrade of csbattery
Attempting remote installation of 'csbattery'
Successfully installed csbattery, version 0.2.2
All gems up to date
title: gem update -- Update your installed gems
- title: Configuration File
page:
- body: |
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
title: Overview
- body: |-
h3. 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
h3. 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
h3. 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).
h3. 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.
title: Configuration Options
- body: |-
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
title: Examples
- title: Environment Variables
page:
- body: |
You can control the behavior of RubyGems through the following environment variables.
GEMCACHE
* Name of user defined cache file to use when the site wide cache file is unwritable. (NOTE: we will probably rename this to GEM_CACHE in the next revision to be consistent with the other environment variables).
GEM_HOME
* Directory containing the master gem repository.
GEM_PATH
* Path list of directories containing gem repositories to be searched in addition to the GEM_HOME directory. The list should be delimited by the appropriate path separator (e.g. ':' on Unix and ';' on Windows)
GEM_SKIP
* List of gems should should not be loaded (normally used for development). The list should be delimited by the appropriate path separator (e.g. ':' on Unix and ';' on Windows)
HOME
* Home directory of the user (see below).
HOMEDRIVE
* Drive containing the users home directory.
HOMEPATH
* Path to the user's home directory.
http_proxy or HTTP_PROXY
* URL of the HTTP protocol proxy to be used to get out of the firewall. The lower case verion will be used first.
make
* Name of the make program that should be used to build extensions.
USERPROFILE
* Home directory of the user (used if HOME is not defined).
title: GEM Environment Variables
- body: |
Finding the user's home directory can be tricky across different systems. Gems tries the following in order until it finds one that works:
# Use HOME if it is defined.
# Use USERPROFILE if it is defined.
# Use HOMEDRIVE and HOMEPATH together if they are defined.
# Use the path you get by having Ruby expand "~".
# Use "C:/" if you are on a Windows machine.
title: Finding a Home Directory
- title: Common Command Options
page:
- body: |
The ''Operations'' section listed the modifiers that are relevant to each operation. In this section the modifiers are discussed in more detail where needed. Most of them apply only to installation of gems.
title: Additional Details on some Gem Command Options
- body: |
Specifies a configuration file to use. The default is .gemrc in your HOME directory. Only one configuration file will be read. See ConfigurationFile for more details.
title: --config-file FILE
- body: |
Installation will take place in the given directory. For instance, if DIR is /usr/share/rubygems, then your gem will be installed into /usr/share/rubygems/gem/gem-name.
Normally, installation takes place in the ''first'' directory specified in your gem path, which is set by the environment variable GEM_PATH or in the configuration file. If you don't specify a ''gem path'' (and most people shouldn't need to), then the base RubyGems installation directory is /usr/local/lib/ruby/gems/1.8/.
This modifier applies to installation of gems only.
title: --install-dir DIR
- body: |
Forces the installation of a gem even if the dependencies are not met.
This modifier applies to installation of gems only.
title: --force
- body: |
RDoc API documentation will be generated after a gem is installed. If the gem does not specify that it contains RDoc comments, RDoc will be run anyway.
This modifier applies to installation of gems only.
title: --[no-]rdoc
- body: |
Unit tests will be run after a gem is installed. If the gem does not contain any unit tests, then a message will be printed to that effect.
This modifier applies to installation of gems only.
title: --run-tests
- body: |
The operation will limit itself, if appropriate, to gems matching the given version requirement string. Examples for VERSION are:
* 1.0.5
* > 1.0.5
* <= 1.0.5
title: --version VERSION
- body: |
The operation will be restricted to the ''remote'' domain. Fo r example, an --install operation will go directly to the remote servers.
title: " --remote, -R"
- body: |
The operation may be performed in the local ''and'' remote domains. This is the default behaviour.
title: --both, -B
- body: |-
Command-line applications typically set an environment variable to specify an HTTP proxy through which to access the Internet. gem respects the following variables:
* http_proxy
* HTTP_PROXY
* NO_PROXY
A proxy specification must be a full HTTP URL,
e.g. http://www-cache:8000. A NO_PROXY setting lists the domains (comma-separated) for which no proxy should be used.
If you specify:
* nothing or --http-proxy, then the environment will be respected;
* --http-proxy URL, then URL will be used, regardless of the environment.
* --no-http-proxy, then _no_ proxy will be used, regardless of the environment;
-P is a shortcut for --http-proxy. There is no shortcut for --no-http-proxy.
Between the environment and the command-line, there are many options available for specifying your proxy if you are behind one. Annoyingly, I am behind a proxy half the time, and my solution is to:
* set HTTP_PROXY to my proxy URL
* in my .gemrc config file (see below), specify --no-http-proxy
* when I am behind a proxy, give -P on the command line to override the above option
That solution is the least amount of typing, until I think of a way to conditionally set HTTP_PROXY in a smart way.
title: --[no-]http-proxy [URL], -p
body: The gem command is the main user interface to the RubyGems packaging system. This document provides a reference to the gem command and its options.
title: gem Command Reference