carapace-sh/carapace-bin / skills/ruby
ruby
VerifiedUse when working with Ruby — the dynamic, object-oriented language and its runtime (MRI/CRuby). Covers the object model, metaprogramming, core types, blocks/procs/lambdas, control flow and exceptions, I/O and encoding, the concurrency model (Threads, Fibers, Ractors, GVL), garbage collection and ObjectSpace, the RubyGems/Bundler package system, the interpreter CLI and tooling (irb, erb, rake, rdoc/ri), environment variables, and the standard library. Triggers on: "ruby", "Ruby", "MRI", "CRuby", "YARV", "Ripper", "object model", "method lookup", "eigenclass", "singleton class", "metaprogramming", "define_method", "method_missing", "class_eval", "instance_eval", "Refinements", "Binding", "Proc", "lambda", "block", "yield", "rescue", "ensure", "raise", "begin", "end", "Encoding", "String#encode", "Thread", "Fiber", "Ractor", "GVL", "GIL", "Mutex", "ObjectSpace", "GC", "WeakRef", "gem", "Gemfile", "Bundler", "gemspec", "bundle exec", "irb", "erb", "rake", "Rakefile", "rdoc", "ri", "RUBYOPT", "RUBYLIB", "GEM_HOME", "GEM_PATH", "BUNDLE_GEMFILE", "frozen string literal", "RUBY_VERSION", "RUBY_ENGINE".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.4 KB |
| references/blocks-procs-lambdas.md | markdown | 6.5 KB |
| references/cli.md | markdown | 8.4 KB |
| references/concurrency.md | markdown | 9.0 KB |
| references/control-flow.md | markdown | 7.2 KB |
| references/environment.md | markdown | 6.1 KB |
| references/gc-memory.md | markdown | 8.5 KB |
| references/gems-bundler.md | markdown | 9.4 KB |
| references/io-encoding.md | markdown | 7.5 KB |
| references/metaprogramming.md | markdown | 6.9 KB |
| references/object-model.md | markdown | 6.6 KB |
| references/stdlib.md | markdown | 8.5 KB |
| references/types.md | markdown | 7.8 KB |
references/environment.md
View on GitHub# Environment Variables
Environment variables that affect Ruby, RubyGems, and Bundler — interpreter behavior, load path, gem locations, and Bundler configuration.
> **Source of truth**: `ruby --help`, `gem env`, `bundle config`. For **CLI flags**, see [cli.md](cli.md). For **gem paths**, see [gems-bundler.md](gems-bundler.md).
## Ruby Interpreter
### RUBYOPT
Extra options appended to the command line for every `ruby` invocation:
```bash
export RUBYOPT="-w"
ruby script.rb # equivalent to: ruby -w script.rb
```
Common uses: `-w` (warnings), `-I/path` (load path), `-rfoo` (require).
### RUBYLIB
Prepends directories to `$LOAD_PATH`:
```bash
export RUBYLIB=/home/user/mylib
ruby -e 'puts $LOAD_PATH.first' # => /home/user/mylib
```
### RUBY_ENGINE, RUBY_VERSION, etc.
These are constants (not env vars), but commonly referenced:
| Constant | Value |
|----------|-------|
| `RUBY_VERSION` | e.g. `"3.2.0"` |
| `RUBY_ENGINE` | `"ruby"` (MRI), `"jruby"`, `"truffleruby"`, `"mruby"` |
| `RUBY_PLATFORM` | e.g. `"x86_64-linux"` |
| `RUBY_PATCHLEVEL` | patch level (e.g. `0`) |
| `RUBY_RELEASE_DATE` | release date string |
| `RUBY_DESCRIPTION` | full version string |
| `RUBY_REVISION` | git revision |
Check at runtime:
```ruby
if RUBY_ENGINE == "jruby"
# JRuby-specific code
end
```
### Encoding-Related
| Variable | Effect |
|----------|--------|
| `LANG` | Sets locale, affects `Encoding.default_external` |
| `LC_ALL` | Overrides `LANG` for all locale categories |
| `LC_CTYPE` | Locale for character encoding |
Ruby reads `LANG`/`LC_ALL`/`LC_CTYPE` to set `Encoding.default_external` at startup. Override with `-E` flag.
### RubyVM::FrozenStringLiteral
There's no env var for this — use the magic comment or `--enable-frozen-string-literal`:
```bash
ruby --enable-frozen-string-literal script.rb
ruby --disable-frozen-string-literal script.rb
```
## RubyGems
### GEM_HOME
Where gems are installed:
```bash
export GEM_HOME=/opt/gems
gem install foo # installs to /opt/gems/gems/foo-1.0/
```
### GEM_PATH
Where RubyGems looks for installed gems (colon-separated):
```bash
export GEM_PATH=/opt/gems:/home/user/.gem/ruby/3.2.0
```
Default: `GEM_HOME` plus the user's `.gem` directory.
### GEM_ROOT
The Ruby's built-in gem directory (read-only, comes with Ruby).
### GEM_RC
Path to `.gemrc` config file (default `~/.gemrc`):
```yaml
# ~/.gemrc
---
:sources:
- https://rubygems.org
:install: --user-install
gem: "--no-document"
```
### GEM_SPEC_CACHE
Cache directory for gemspec data (default: `GEM_HOME/specifications`).
### Common Gem Env Vars
| Variable | Effect |
|----------|--------|
| `GEM_HOME` | Install location |
| `GEM_PATH` | Search path |
| `GEM_SPEC_CACHE` | Spec cache dir |
| `GEM_RC` | Config file path |
| `RUBY_GEMSPEC` | (rarely used) |
Check with `gem env`:
```bash
$ gem env home
/usr/lib/ruby/gems/3.2.0
$ gem env path
/usr/lib/ruby/gems/3.2.0:/home/user/.gem/ruby/3.2.0
$ gem env gemdir
/usr/lib/ruby/gems/3.2.0
```
## Bundler
### BUNDLE_GEMFILE
Which Gemfile to use:
```bash
BUNDLE_GEMFILE=Gemfile.alt bundle exec rake
```
Default: `Gemfile` in the current directory (searched upward).
### BUNDLE_PATH
Where to install gems for `bundle install`:
```bash
bundle config set --local path 'vendor/bundle'
# or
export BUNDLE_PATH=vendor/bundle
bundle install
```
### BUNDLE_FROZEN
Equivalent to `--frozen` — prevents modifications to `Gemfile.lock`:
```bash
BUNDLE_FROZEN=true bundle install
```
### BUNDLE_WITHOUT
Skip groups:
```bash
BUNDLE_WITHOUT=test:development bundle install
```
### BUNDLE_BIN
Where binstubs are installed (default: `bin/`).
### BUNDLE_JOBS
Parallel jobs for installation:
```bash
BUNDLE_JOBS=4 bundle install
```
### BUNDLE_IGNORE_CONFIG
Ignore Bundler config files (only use env vars):
```bash
BUNDLE_IGNORE_CONFIG=true bundle install
```
### BUNDLE_CACHE_PATH
Where `bundle package` caches gems (default: `vendor/cache`).
### BUNDLER_VERSION
Force a specific Bundler version:
```bash
BUNDLER_VERSION=2.4.0 bundle _2.4.0_ install
```
The `bundle _<version>_` syntax also works (passed as arg).
### Bundler Config (Persistent)
Bundler reads config from:
1. Local: `.bundle/config` (per-project)
2. Env: `BUNDLE_*` variables
3. Global: `~/.bundle/config`
```bash
bundle config set --global path vendor/bundle # global
bundle config set --local path vendor/bundle # per-project
bundle config # show all
bundle config path # show one
bundle config unset path # remove
```
## Load Path and $LOAD_PATH
`$LOAD_PATH` (alias `$:`) is an array of directories Ruby searches when you `require`:
```ruby
$LOAD_PATH
# => ["/usr/lib/ruby/gems/3.2.0/gems/foo-1.0/lib",
# "/usr/lib/ruby/3.2.0",
# "/usr/lib/ruby/3.2.0/x86_64-linux",
# ...]
```
Modify at runtime:
```ruby
$LOAD_PATH.unshift("/my/lib")
require "my_file" # looks in /my/lib first
```
`-I` flag and `RUBYLIB` env var prepend to `$LOAD_PATH`.
## ARGV and ENV
```ruby
ARGV # command-line args (Array)
ENV # environment (Hash-like, read-only)
ENV["PATH"]
ENV.fetch("HOME", "/tmp")
ENV.to_h # full hash
```
`ENV` is a pseudo-Hash. Keys and values are Strings. Modifying `ENV` with `ENV[key] = val` calls the OS `setenv`.
## Edge Cases and Known Issues
- **`RUBYOPT` is parsed early** — errors in options will prevent Ruby from starting
- **`GEM_HOME` must exist** — RubyGems may create it, but missing parent dirs can cause errors
- **`BUNDLE_FROZEN` + `Gemfile.lock` out of date** — fails immediately; run `bundle install` without `BUNDLE_FROZEN` to update the lockfile
- **`ENV` is process-wide** — modifying it affects all threads and child processes
- **`LANG=C` sets ASCII encoding** — use `LANG=C.UTF-8` or `LANG=en_US.UTF-8` for UTF-8 default
- **`GEM_PATH` order matters** — earlier paths shadow later; useful for overriding a system gem with a local one
- **Bundler env vars override config files** — `BUNDLE_PATH=foo` takes precedence over `.bundle/config`
## Related
- [cli.md](cli.md) — `ruby` flags, `-I`, `-E`
- [gems-bundler.md](gems-bundler.md) — `gem env`, `bundle config`
- [io-encoding.md](io-encoding.md) — `Encoding.default_external` and locale
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |