'\" t

.\"RubyGems is copyrighted free software by Chad Fowler, Rich Kilmer, Jim Weirich and others.

.\"

.\" CDDL HEADER START

.\"

.\" The contents of this file are subject to the terms of the

.\" Common Development and Distribution License (the "License").

.\" You may not use this file except in compliance with the License.

.\"

.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

.\" or http://www.opensolaris.org/os/licensing.

.\" See the License for the specific language governing permissions

.\" and limitations under the License.

.\"

.\" When distributing Covered Code, include this CDDL HEADER in each

.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.

.\" If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying

.\" information: Portions Copyright [yyyy] [name of copyright owner]

.\"

.\" CDDL HEADER END

.\"

.\"

.\" gem.1

.\"

.SH NAME

gem  \-\-  Command-line interface to RubyGems

.SH SYNOPSIS

.B gem

.RB \-h | \-\-help

.PP

.B gem

.RB \-v | \-\-version

.PP

.B gem 

.I command 

[ arguments\.\.\. ]

[ options\.\.\. ]

.SH DESCRIPTION

A gem is a packaged Ruby application or library, while RubyGems is the premier ruby packaging system which is used to manage gems.

Gems are managed on your computer using the 

.I gem 

command. You can install, remove, and query gem packages using the 

.I gem 

command.

.SH FEATURES

* Easy Installation and removal of RubyGems packages and their dependencies

* Management and control of local packages

* Package dependency management

* Query, search and list local and remote packages

* Multiple version support for installed packages

* Web-based interface to view the documentation for your installed gems

* Easy to use interface for building gem packages

* Simple server for distributing your own gem packages

.SH OPTIONS

.TP

\fB\-h | \-\-help\fP

Get the basic help message for 

.I gem 

command.

.TP

\fB\-v | \-\-version\fP

Get the version of 

.I gem

command.

.TP

.I command

.sp

.ne 2

.mk

\fBbuild\fP

.in +16n

.rt

Build a gem from a gemspec

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBcert\fP

.in +16n

.rt

Manage RubyGems certificates and signing settings

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBcheck\fP

.in +16n

.rt

Check a gem repository for added or missing files

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBcleanup\fP

.in +16n

.rt

Clean up old versions of installed gems

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBcontents\fP

.in +16n

.rt

Display the contents of the installed gems

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBdependency\fP

.in +16n

.rt

Show the dependencies of an installed gem

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBenvironment\fP

.in +16n

.rt

Display information about the RubyGems environment

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBfetch\fP

.in +16n

.rt

Download a gem and place it in the current directory

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBgenerate_index\fP

.in +16n

.rt

Generates the index files for a gem server directory

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBhelp\fP

.in +16n

.rt

Provide help on the 'gem' command

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBinstall\fP

.in +16n

.rt

Install a gem into the local repository

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBlist\fP

.in +16n

.rt

Display local gems whose name starts with STRING

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBlock\fP

.in +16n

.rt

Generate a lockdown list of gems

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBmirror\fP

.in +16n

.rt

Mirror all gem files (requires rubygems-mirror)

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBoutdated\fP

.in +16n

.rt

Display all gems that need updates

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBowner\fP

.in +16n

.rt

Manage gem owners of a gem on the push server

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBpristine\fP

.in +16n

.rt

Restores installed gems to pristine condition from files located in the gem cache

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBpush\fP

.in +16n

.rt

Push a gem up to the gem server

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBquery\fP

.in +16n

.rt

Query gem information in local or remote repositories

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBrdoc\fP

.in +16n

.rt

Generates RDoc for pre-installed gems

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBsearch\fP

.in +16n

.rt

Display remote gems whose name contains STRING

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBserver\fP

.in +16n

.rt

Documentation and gem repository HTTP server

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBsources\fP

.in +16n

.rt

Manage the sources and cache file RubyGems will search for gems

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBspecification\fP

.in +16n

.rt

Display gem specification (in yaml)

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBstale\fP

.in +16n

.rt

List gems along with access times

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBuninstall\fP

.in +16n

.rt

Uninstall gems from the local repository

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBunpack\fP

.in +16n

.rt

Unpack an installed gem to the current directory

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBupdate\fP

.in +16n

.rt

Update installed gems to the latest version

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fBwhich\fP

.in +16n

.rt

Find the location of a library file you can require

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

\fByank\fP

.in +16n

.rt

Remove a pushed gem from the index

.sp

.sp 1

.in -16n

.sp

.ne 2

.mk

For more detailed help on a particular command with its arguments and options,

use 'gem help

.I command

\'.

For example:

        # gem help install

Commands may be abbreviated, so long as they are unambiguous.

e.g. 'gem i thor' is short for 'gem install thor'.

.SH ENVIRONMENT

.TP

.B GEM_HOME

Directory containing the master gem repository.

.TP

.B 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 ':' 

.TP

.B http_proxy / HTTP_PROXY

URL of the HTTP protocol proxy to be used to get out of the firewall. The lower case version will be used first.

.TP

Name of the make program that should be used to build extensions.

.TP

.B HOME

Home directory of the user (see below).

.SH EXAMPLES

.PP

\fBExample 1: Install 'thor', either from local directory or remote server

.PP

.nf

	# gem install thor

.fi

.PP

\fBExample 2: Install 'thor', only from remote server

.PP

.nf

	# gem install thor --remote

.fi

.PP

.PP

.nf

.fi

.PP

\fBExample 4: Install 'thor', but only version 0.18.1, even if dependencies are not met, and into a specific directory

.PP

.nf

	# gem install thor --version 0.18.1 --force --install-dir $HOME/.gem/ruby/RUBY_LIB_VER

.fi

.PP

.PP

.nf

.fi

.PP

\fBExample 6: List local and remote gems whose name contains 'log'

.PP

.nf

	# gem search log --both

.fi

.PP

\fBExample 7:  List only remote gems whose name contains 'log'

.PP

.nf

	# gem search log --remote

.fi

.PP

\fBExample 8: Uninstall 'thor'

.PP

.nf

	#  gem uninstall thor

.fi

.PP

\fBExample 9:  See information about RubyGems

.PP

.nf

	# gem environment

.TE

.sp

.SH SEE ALSO

\fBruby\fR(1)

.sp

.SH FILES

The following files specify the installation  locations  for Ruby: 

.PP

.TP

/usr/ruby/RUBY_VER/lib/ruby/gems/RUBY_LIB_VER

Default installation location for Ruby gems

.PP

.TP

~/.gem/ruby/RUBY_LIB_VER

Per user location to install gems. This is automatically added to GEM_PATH.

.PP

.TP

/usr/ruby/RUBY_VER/lib/ruby/vendor_ruby/gems/RUBY_LIB_VER

Location of gems installed by Solaris packages.

.PP

.TP

~/.gem/ruby/RUBY_LIB_VER/bin

Per user location for gem executables.

.PP

.TP

/usr/ruby/RUBY_VER/bin 

Contains the Rubygems program with all other Ruby related programs.  These programs are linked from /usr/bin.

Also contains executables for any installed gems that supply them (i.e.: thor, rails, etc).

.PP

.PP

.SH NOTES

Detailed documentation for RubyGems is available at http://guides.rubygems.org/