id       = "gem"
name     = "RubyGems"
homepage = "https://guides.rubygems.org/command-reference/"
description = "RubyGems is a package management framework for Ruby."
icon     = "theSVG:rubygems"
executables   = ["gem"]

[dotfiles]

# `gem help environment`: "Command line argument defaults and some RubyGems
# defaults can be set in a ~/.gemrc file for individual users and a gemrc in
# the SYSTEM CONFIGURATION DIRECTORY for all users." Only the per-user file is
# a dotfile. Windows writes the same file as %USERPROFILE%\.gemrc, which
# resolves to this very path.
paths = ["~/.gemrc"]

# `gem environment` on a stock install reports USER INSTALLATION DIRECTORY
# ~/.gem/ruby/<abi> and SPEC CACHE DIRECTORY ~/.gem/specs — installed gems and
# a downloaded index, not settings.
exclude = ["~/.gem/ruby/", "~/.gem/specs/"]

# rubygems lib/rubygems/config_file.rb, `credentials_path`: ~/.gem/credentials
# when that file exists, otherwise Gem.data_home + "/gem/credentials".
# lib/rubygems/defaults.rb defines `data_home` as
# `ENV["XDG_DATA_HOME"] || File.join(Gem.user_home, ".local", "share")` with no
# per-OS branch, so it is the XDG data home on macOS too and is written
# [xdgData]; [dataHome] would be ~/Library/Application Support, which RubyGems
# never writes. `gem environment credentials` prints whichever is in effect.
# Both hold nothing but RubyGems.org API keys, so both are whole-file secrets
# rather than files with a secret field in them.
secret = [
  "~/.gem/credentials",
  "[xdgData]/gem/credentials",
]

# Read once per `gem` invocation; no resident process holds it.
side_effect = false

# `gem help environment` documents `:gempath:` as "The paths in which to look
# for gems" — absolute paths into this machine's Ruby installations. The rest
# of the file (`:sources:`, `:verbose:`, `:update_sources:`, per-command
# argument defaults) is preference that should follow the user. The list mixes
# the user's own ~/.gem tree with whatever Ruby this machine has installed, so
# it cannot be handed to another machine — but it is worth having back when
# rebuilding this one: backup. `.gemrc` is YAML with Ruby symbol keys, and
# nothing in the name says so.
[[dotfiles.machine_lines]]
file   = "~/.gemrc"
format = "yaml"
match  = { key_path = [":gempath"] }
scope  = "backup"

[commands]
format = 1
label = "RubyGems"
description = "Install, update, remove and list Ruby gems."
quality = "ai-draft"
base = "fig:gem"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/gem.ts"
license = "MIT"

[[commands.subcommand]]
path = ["install"]
label = "Install gems"

[[commands.subcommand.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/gem.ts"
license = "MIT"

[[commands.subcommand.field]]
id = "gems"
label = "Gems"
type = "string"
position = 0
multiple = true
sources = ["fig"]

[[commands.subcommand.field]]
id = "platform"
label = "Platform"
type = "string"
option = ["--platform"]
sources = ["fig"]

[[commands.subcommand.task]]
id = "install"
label = "Install"
fields = ["gems", "platform"]
required = ["gems"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["gems", "platform"]

[[commands.subcommand]]
path = ["update"]
label = "Update gems"
description = "Name gems to update, or leave empty to update all."

[[commands.subcommand.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/gem.ts"
license = "MIT"

[[commands.subcommand.field]]
id = "gems"
label = "Gems"
type = "string"
position = 0
multiple = true
sources = ["fig"]

[[commands.subcommand.field]]
id = "system"
label = "Update RubyGems itself"
type = "boolean"
option = ["--system"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "prerelease"
label = "Allow prerelease"
type = "boolean"
option = ["--prerelease"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "conservative"
label = "Keep satisfied gems"
type = "boolean"
option = ["--conservative"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "user_install"
label = "Install in home directory"
type = "boolean"
option = ["--user-install"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "no_document"
label = "Skip documentation"
type = "boolean"
option = ["--no-document", "-N"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "explain"
label = "Only explain"
type = "boolean"
option = ["--explain"]
sources = ["fig"]

[[commands.subcommand.task]]
id = "update"
label = "Update gems"
fields = ["gems", "no_document"]
required = []

[[commands.subcommand.task]]
id = "preview"
label = "Preview updates"
set = { explain = [true] }
fields = ["gems", "explain"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["gems", "system"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["prerelease", "conservative", "user_install", "no_document", "explain"]

[[commands.subcommand]]
path = ["uninstall"]
label = "Uninstall gems"

[[commands.subcommand.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/gem.ts"
license = "MIT"

[[commands.subcommand.field]]
id = "gems"
label = "Gems"
type = "string"
position = 0
multiple = true
sources = ["fig"]

[[commands.subcommand.field]]
id = "version"
label = "Version"
type = "string"
option = ["--version", "-v"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "all"
label = "All matching versions"
type = "boolean"
option = ["--all", "-a"]
effect = "delete"
sources = ["fig"]

[[commands.subcommand.field]]
id = "executables"
label = "Remove executables without asking"
type = "boolean"
option = ["--executables", "-x"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "ignore_dependencies"
label = "Ignore dependencies"
type = "boolean"
option = ["--ignore-dependencies", "-I"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "force"
label = "Force"
type = "boolean"
option = ["--force"]
effect = "delete"
sources = ["fig"]

[[commands.subcommand.field]]
id = "user_install"
label = "Also from home directory"
type = "boolean"
option = ["--user-install"]
sources = ["fig"]

[[commands.subcommand.task]]
id = "uninstall"
label = "Uninstall"
fields = ["gems", "version"]
required = ["gems"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["gems", "version"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["all", "executables", "ignore_dependencies", "force", "user_install"]

[[commands.subcommand]]
path = ["list"]
label = "List gems"

[[commands.subcommand.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/gem.ts"
license = "MIT"

[[commands.subcommand.field]]
id = "regexp"
label = "Name pattern"
type = "string"
position = 0
sources = ["fig"]

[[commands.subcommand.field]]
id = "local"
label = "Local only"
type = "boolean"
option = ["--local", "-l"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "remote"
label = "Remote only"
type = "boolean"
option = ["--remote", "-r"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "all"
label = "All versions"
type = "boolean"
option = ["--all", "-a"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "exact"
label = "Exact name match"
type = "boolean"
option = ["--exact", "-e"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "details"
label = "Details"
type = "boolean"
option = ["--details", "-d"]
sources = ["fig"]

[[commands.subcommand.field]]
id = "prerelease"
label = "Include prerelease"
type = "boolean"
option = ["--prerelease"]
sources = ["fig"]

[[commands.subcommand.task]]
id = "list"
label = "List installed"
fields = ["regexp", "exact"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["regexp", "local", "remote", "all", "exact", "details", "prerelease"]