Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Regenerate command reference from RubyGems 2.0.2

  • Loading branch information...
commit 57fc526de2b6b66a5888f5516d5328b38e8e9b83 1 parent 87a10e6
@ffmike ffmike authored
Showing with 171 additions and 46 deletions.
  1. +171 −46 command-reference.md
View
217 command-reference.md
@@ -2,11 +2,13 @@
layout: default
title: Command Reference
previous: /patterns
-next: /rubygems-org-api
+next: /specification-reference
---
What each `gem` command does, and how to use it.
+This reference was automatically generated from RubyGems version 2.0.2.
+
* [gem build](#gem_build)
* [gem cert](#gem_cert)
* [gem check](#gem_check)
@@ -20,6 +22,7 @@ What each `gem` command does, and how to use it.
* [gem install](#gem_install)
* [gem list](#gem_list)
* [gem lock](#gem_lock)
+* [gem mirror](#gem_mirror)
* [gem outdated](#gem_outdated)
* [gem owner](#gem_owner)
* [gem pristine](#gem_pristine)
@@ -35,6 +38,7 @@ What each `gem` command does, and how to use it.
* [gem unpack](#gem_unpack)
* [gem update](#gem_update)
* [gem which](#gem_which)
+* [gem yank](#gem_yank)
@@ -47,6 +51,10 @@ Build a gem from a gemspec
gem build GEMSPEC_FILE [options]
+### Options:
+
+* -​-force - skip validation of the spec
+
### Common Options:
* -h, -​-help - Get help on this command
@@ -79,12 +87,12 @@ Manage RubyGems certificates and signing settings
### 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.
+* -l, -​-list \[FILTER\] - List trusted certificates where the subject contains FILTER
+* -r, -​-remove FILTER - Remove trusted certificates where the subject contains FILTER
+* -b, -​-build EMAIL_ADDR - Build private key and self-signed certificate for EMAIL_ADDR
+* -C, -​-certificate CERT - Signing certificate for -​-sign
+* -K, -​-private-key KEY - Key for -​-sign or -​-build
+* -s, -​-sign CERT - Signs CERT with the key from -K and the certificate from -C
### Common Options:
@@ -99,20 +107,59 @@ Manage RubyGems certificates and signing settings
+### Description
+
+The cert command manages signing keys and certificates for creating signed
+gems. Your signing certificate and private key are typically stored in
+~/.gem/gem-public_cert.pem and ~/.gem/gem-private_key.pem respectively.
+
+To build a certificate for signing gems:
+
+ gem cert --build you@example
+
+If you already have an RSA key, or are creating a new certificate for an
+existing key:
+
+ gem cert --build you@example --private-key /path/to/key.pem
+
+If you wish to trust a certificate you can add it to the trust list with:
+
+ gem cert --add /path/to/cert.pem
+
+You can list trusted certificates with:
+
+ gem cert --list
+
+or:
+
+ gem cert --list cert_subject_substring
+
+If you wish to remove a previously trusted certificate:
+
+ gem cert --remove cert_subject_substring
+
+To sign another gem author's certificate:
+
+ gem cert --sign /path/to/other_cert.pem
+
+For further reading on signing gems see `ri Gem::Security`.
+
## gem check
-Check installed gems
+Check a gem repository for added or missing files
### Usage
- gem check [options]
+ gem check [OPTIONS] [GEMNAME ...] [options]
### Options:
-* -​-verify FILE - Verify gem file against its internal checksum
-* -a, -​-alien - Report 'unmanaged' or rogue files in the gem repository
+* -a, -​-\[no-\]alien - Report "unmanaged" or rogue files in the gem repository
+* -​-\[no-\]doctor - Clean up uninstalled gems and broken specifications
+* -​-\[no-\]dry-run - Do not remove files, only report what would be removed
+* -​-\[no-\]gems - Check installed gems for problems
* -v, -​-version VERSION - Specify version of gem to check
### Common Options:
@@ -126,6 +173,12 @@ Check installed gems
+### Arguments
+
+
+* *GEMNAME* - name of gem to check
+
+
@@ -165,6 +218,9 @@ Clean up old versions of installed gems in the local repository
The cleanup command removes old gems from GEM_HOME. If an older version is
installed elsewhere in GEM_PATH the cleanup command won't touch it.
+
+Older gems that are required to satisify the dependencies of gems
+are not removed.
## gem contents
@@ -294,33 +350,38 @@ Display information about the RubyGems environment
The RubyGems environment can be controlled through command line arguments,
gemrc files, environment variables and built-in defaults.
-Command line argument defaults and some RubyGems defaults can be set in
-~/.gemrc file for individual users and a /etc/gemrc for all users. A gemrc
-is a YAML file with the following YAML keys:
+Command line argument defaults and some RubyGems defaults can be set in a
+~/.gemrc file for individual users and a /etc/gemrc for all users. These
+files are YAML files with the following YAML keys:
:sources: A YAML array of remote gem repositories to install gems from
- :verbose: Verbosity of the gem command. false, true, and :really are the
+ :verbose: Verbosity of the gem command. false, true, and :really are the
levels
:update_sources: Enable/disable automatic updating of repository metadata
:backtrace: Print backtrace when RubyGems encounters an error
:gempath: The paths in which to look for gems
- gem_command: A string containing arguments for the specified gem command
+ :disable_default_gem_server: Force specification of gem server host on push
+ <gem_command>: A string containing arguments for the specified gem command
Example:
:verbose: false
install: --no-wrappers
update: --no-wrappers
+ :disable_default_gem_server: true
RubyGems' default local repository can be overridden with the GEM_PATH and
-GEM_HOME environment variables. GEM_HOME sets the default repository to
-install into. GEM_PATH allows multiple local repositories to be searched for
+GEM_HOME environment variables. GEM_HOME sets the default repository to
+install into. GEM_PATH allows multiple local repositories to be searched for
gems.
If you are behind a proxy server, RubyGems uses the HTTP_PROXY,
HTTP_PROXY_USER and HTTP_PROXY_PASS environment variables to discover the
proxy server.
+If you would like to push gems to a private gem server the RUBYGEMS_HOST
+environment variable can be set to the URI for that server.
+
If you are packaging RubyGems all of RubyGems' defaults are in
lib/rubygems/defaults.rb. You may override these in
lib/rubygems/defaults/operating_system.rb
@@ -346,6 +407,7 @@ Download a gem and place it in the current directory
* -B, -&#8203;-bulk-threshold COUNT - Threshold for switching to bulk synchronization (default 1000)
* -p, -&#8203;-\[no-\]http-proxy \[URL\] - Use HTTP proxy for remote operations
* -&#8203;-source URL - Add URL as a remote source for gems
+* -&#8203;-clear-sources - Clear the gem sources
### Common Options:
@@ -379,16 +441,9 @@ Generates the index files for a gem server directory
### Options:
* -d, -&#8203;-directory=DIRNAME - repository base dir containing gems subdir
-* -&#8203;-\[no-\]legacy - Generate Marshal.4.8
-* -&#8203;-\[no-\]modern - Generate indexes for RubyGems newer than 1.2.0
+* -&#8203;-\[no-\]modern - Generate indexes for RubyGems (always true)
* -&#8203;-update - Update modern indexes with gems added since the last update
-### RSS Options:
-
-* -&#8203;-rss-gems-host=GEM_HOST - Host name where gems are served from, used for GUID and enclosure values
-* -&#8203;-rss-host=HOST - Host name for more gems information, used for RSS feed link
-* -&#8203;-rss-title=TITLE - Set title for RSS feed
-
### Common Options:
* -h, -&#8203;-help - Get help on this command
@@ -422,16 +477,9 @@ When done, it will generate a set of files like this:
prerelease_specs.<version>.gz # prerelease specs index
quick/Marshal.<version>/<gemname>.gemspec.rz # Marshal quick index file
- # these files support legacy RubyGems
- Marshal.<version>
- Marshal.<version>.Z # Marshal full index
-
-The .Z and .rz extension files are compressed with the inflate algorithm.
+The .rz extension files are compressed with the inflate algorithm.
The Marshal version number comes from ruby's Marshal::MAJOR_VERSION and
Marshal::MINOR_VERSION constants. It is used to ensure compatibility.
-
-If --rss-host and --rss-gem-host are given an RSS feed will be generated at
-index.rss containing gems released in the last two days.
## gem help
@@ -482,24 +530,28 @@ Install a gem into the local repository
### Deprecated Options:
+* -&#8203;-\[no-\]rdoc - Generate RDoc for installed gems Use -&#8203;-document instead
+* -&#8203;-\[no-\]ri - Generate ri data for installed gems. Use -&#8203;-document instead
* -u, -&#8203;-\[no-\]update-sources - Update local source cache
### Install/Update Options:
* -i, -&#8203;-install-dir DIR - Gem repository directory to get installed gems
* -n, -&#8203;-bindir DIR - Directory where binary files are located
-* -d, -&#8203;-\[no-\]rdoc - Generate RDoc documentation for the gem on install
-* -&#8203;-\[no-\]ri - Generate RI documentation for the gem on install
+* -&#8203;-\[no-\]document \[TYPES\] - Generate documentation for installed gems List the documentation types you wish to generate. For example: rdoc,ri
+* -N, -&#8203;-no-document - Disable documentation generation
* -E, -&#8203;-\[no-\]env-shebang - Rewrite the shebang line on installed scripts to use /usr/bin/env
* -f, -&#8203;-\[no-\]force - Force gem to install, bypassing dependency checks
* -w, -&#8203;-\[no-\]wrappers - Use bin wrappers for executables Not available on dosish platforms
* -P, -&#8203;-trust-policy POLICY - Specify gem trust policy
* -&#8203;-ignore-dependencies - Do not install any required dependent gems
-* -y, -&#8203;-include-dependencies - Unconditionally install the required dependent gems
* -&#8203;-\[no-\]format-executable - Make installed executable names match ruby. If ruby is ruby18, foo_exec will be foo_exec18
* -&#8203;-\[no-\]user-install - Install in user's home directory instead of GEM_HOME.
-* -&#8203;-development - Install any additional development dependencies
+* -&#8203;-development - Install additional development dependencies
+* -&#8203;-development-all - Install development dependencies for all gems (including dev deps themselves)
* -&#8203;-conservative - Don't attempt to upgrade gems already meeting version requirement
+* -&#8203;-minimal-deps - Don't upgrade any dependencies that already meet version requirements
+* -g, -&#8203;-file FILE - Read from a gem dependencies API file and install the listed gems
### Local/Remote Options:
@@ -593,6 +645,7 @@ Display gems whose name starts with STRING
### Options:
* -i, -&#8203;-\[no-\]installed - Check for installed gem
+* -I - Equivalent to -&#8203;-no-installed
* -v, -&#8203;-version VERSION - Specify version of gem to list for use with -&#8203;-installed
* -d, -&#8203;-\[no-\]details - Display detailed information of gem(s)
* -&#8203;-\[no-\]versions - Display only gem names
@@ -676,7 +729,7 @@ generated.
Example:
- gemlock rails-1.0.0 > lockdown.rb
+ gem lock rails-1.0.0 > lockdown.rb
will produce in lockdown.rb:
@@ -698,6 +751,29 @@ Rake-0.7.0.1 is the most recent version installed that satisfies that, so we
lock it down to the exact version.
+## gem mirror
+
+Mirror all gem files (requires rubygems-mirror)
+
+### Usage
+
+ gem mirror [options]
+
+
+### Common Options:
+
+* -h, -&#8203;-help - Get help on this command
+* -V, -&#8203;-\[no-\]verbose - Set the verbose level of output
+* -q, -&#8203;-quiet - Silence commands
+* -&#8203;-config-file FILE - Use this config file instead of default
+* -&#8203;-backtrace - Show stack backtrace on errors
+* -&#8203;-debug - Turn on Ruby debugging
+
+
+
+
+
+
## gem outdated
Display all gems that need updates
@@ -745,7 +821,7 @@ Manage gem owners on RubyGems.org.
### Usage
- gem owner [options]
+ gem owner GEM [options]
### Options:
@@ -795,6 +871,7 @@ Restores installed gems to pristine condition from files located in the gem cach
* -&#8203;-all - Restore all installed gems to pristine condition
* -&#8203;-\[no-\]extensions - Restore gems with extensions
+* -&#8203;-only-executables - Only restore executables
* -v, -&#8203;-version VERSION - Specify version of gem to restore to pristine condition
### Common Options:
@@ -886,6 +963,7 @@ Query gem information in local or remote repositories
### Options:
* -i, -&#8203;-\[no-\]installed - Check for installed gem
+* -I - Equivalent to -&#8203;-no-installed
* -v, -&#8203;-version VERSION - Specify version of gem to query for use with -&#8203;-installed
* -n, -&#8203;-name-matches REGEXP - Name of gem(s) to query on matches the provided REGEXP
* -d, -&#8203;-\[no-\]details - Display detailed information of gem(s)
@@ -975,6 +1053,7 @@ Display all gems whose name contains STRING
### Options:
* -i, -&#8203;-\[no-\]installed - Check for installed gem
+* -I - Equivalent to -&#8203;-no-installed
* -v, -&#8203;-version VERSION - Specify version of gem to search for use with -&#8203;-installed
* -d, -&#8203;-\[no-\]details - Display detailed information of gem(s)
* -&#8203;-\[no-\]versions - Display only gem names
@@ -1009,7 +1088,7 @@ Display all gems whose name contains STRING
### Arguments
-* *STRING* - fragment of gem name to search for
+* *STRING* - start of gem name to look for
@@ -1111,6 +1190,7 @@ Display gem specification (in yaml)
* -v, -&#8203;-version VERSION - Specify version of gem to examine
* -&#8203;-platform PLATFORM - Specify the platform of gem to specification
+* -&#8203;-\[no-\]prerelease - Allow prerelease versions of a gem
* -&#8203;-all - Output specifications for all versions of the gem
* -&#8203;-ruby - Output ruby format
* -&#8203;-yaml - Output RUBY format
@@ -1187,11 +1267,13 @@ Uninstall gems from the local repository
* -a, -&#8203;-\[no-\]all - Uninstall all matching versions
* -I, -&#8203;-\[no-\]ignore-dependencies - Ignore dependency requirements while uninstalling
+* -D, -&#8203;-\[no-\]-check-development - Check development dependencies while uninstalling (default: false)
* -x, -&#8203;-\[no-\]executables - Uninstall applicable executables without confirmation
* -i, -&#8203;-install-dir DIR - Directory to uninstall gem from
* -n, -&#8203;-bindir DIR - Directory to remove binaries from
* -&#8203;-\[no-\]user-install - Uninstall from user's home directory in addition to GEM_HOME.
* -&#8203;-\[no-\]format-executable - Assume executable names match Ruby's prefix and suffix.
+* -&#8203;-\[no-\]force - Uninstall all versions of the named gems ignoring dependencies
* -v, -&#8203;-version VERSION - Specify version of gem to uninstall
* -&#8203;-platform PLATFORM - Specify the platform of gem to uninstall
@@ -1252,7 +1334,7 @@ Unpack an installed gem to the current directory
## gem update
-Update the named gems (or all installed gems) in the local repository
+Update installed gems to the latest version
### Usage
@@ -1267,24 +1349,27 @@ Update the named gems (or all installed gems) in the local repository
### Deprecated Options:
+* -&#8203;-\[no-\]rdoc - Generate RDoc for installed gems Use -&#8203;-document instead
+* -&#8203;-\[no-\]ri - Generate ri data for installed gems. Use -&#8203;-document instead
* -u, -&#8203;-\[no-\]update-sources - Update local source cache
### Install/Update Options:
* -i, -&#8203;-install-dir DIR - Gem repository directory to get installed gems
* -n, -&#8203;-bindir DIR - Directory where binary files are located
-* -d, -&#8203;-\[no-\]rdoc - Generate RDoc documentation for the gem on install
-* -&#8203;-\[no-\]ri - Generate RI documentation for the gem on install
+* -&#8203;-\[no-\]document \[TYPES\] - Generate documentation for installed gems List the documentation types you wish to generate. For example: rdoc,ri
+* -N, -&#8203;-no-document - Disable documentation generation
* -E, -&#8203;-\[no-\]env-shebang - Rewrite the shebang line on installed scripts to use /usr/bin/env
* -f, -&#8203;-\[no-\]force - Force gem to install, bypassing dependency checks
* -w, -&#8203;-\[no-\]wrappers - Use bin wrappers for executables Not available on dosish platforms
* -P, -&#8203;-trust-policy POLICY - Specify gem trust policy
* -&#8203;-ignore-dependencies - Do not install any required dependent gems
-* -y, -&#8203;-include-dependencies - Unconditionally install the required dependent gems
* -&#8203;-\[no-\]format-executable - Make installed executable names match ruby. If ruby is ruby18, foo_exec will be foo_exec18
* -&#8203;-\[no-\]user-install - Install in user's home directory instead of GEM_HOME.
-* -&#8203;-development - Install any additional development dependencies
+* -&#8203;-development - Install additional development dependencies
+* -&#8203;-development-all - Install development dependencies for all gems (including dev deps themselves)
* -&#8203;-conservative - Don't attempt to upgrade gems already meeting version requirement
+* -&#8203;-minimal-deps - Don't upgrade any dependencies that already meet version requirements
### Local/Remote Options:
@@ -1350,3 +1435,43 @@ Find the location of a library file you can require
+## gem yank
+
+Remove a specific gem version release from RubyGems.org
+
+### Usage
+
+ gem yank GEM -v VERSION [-p PLATFORM] [--undo] [--key KEY_NAME] [options]
+
+
+### Options:
+
+* -v, -&#8203;-version VERSION - Specify version of gem to remove
+* -&#8203;-platform PLATFORM - Specify the platform of gem to remove
+* - -&#8203;-undo
+* -k, -&#8203;-key KEY_NAME - Use API key from your gem credentials file
+
+### Common Options:
+
+* -h, -&#8203;-help - Get help on this command
+* -V, -&#8203;-\[no-\]verbose - Set the verbose level of output
+* -q, -&#8203;-quiet - Silence commands
+* -&#8203;-config-file FILE - Use this config file instead of default
+* -&#8203;-backtrace - Show stack backtrace on errors
+* -&#8203;-debug - Turn on Ruby debugging
+
+
+
+### Arguments
+
+
+* *GEM* - name of gem
+
+
+
+
+### Description
+
+Remove a specific gem version release from RubyGems.org
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.