From a87ff5ff95aa144a751f19a30cb343dca7dddd87 Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Sat, 7 Feb 2026 17:16:32 +0900
Subject: [DOC] The order of command line options

---
 doc/language/options.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/language/options.md b/doc/language/options.md
index a1f29bfd03..228a56e87b 100644
--- a/doc/language/options.md
+++ b/doc/language/options.md
@@ -129,6 +129,24 @@ $ basename `pwd`
 ruby
 ```
 
+This option is accumulative; relative paths are solved from the
+previous working directory.
+
+```console
+$ ruby -C / -C usr -e 'puts Dir.pwd'
+/usr
+```
+
+If the argument is not an existing directory, a fatal error will
+occur:
+
+```console
+$ ruby -C /nonexistent
+ruby: Can't chdir to /nonexistent (fatal)
+$ ruby -C /dev/null
+ruby: Can't chdir to /dev/null (fatal)
+```
+
 Whitespace between the option and its argument may be omitted.
 
 ### `-d`: Set `$DEBUG` to `true`
@@ -273,6 +291,16 @@ $ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)'
 $ popd
 ```
 
+This option and {option `-C`}[rdoc-ref:@-C+Set+Working+Directory] will
+be applied in the order in the command line; expansion of `-I` options
+are affected by preceeding `-C` options.
+
+```console
+$ ruby -C / -Ilib -C usr -Ilib -e 'puts $:[0, 2]'
+/lib
+/usr/lib
+```
+
 Whitespace between the option and its argument may be omitted.
 
 ### `-l`: Set Output Record Separator; Chop Lines
@@ -396,6 +424,11 @@ $ ruby -r csv -r json -e 'p defined?(JSON); p defined?(CSV)'
 "constant"
 ```
 
+The library is loaded with the `Kernel#require` method, after the
+other options such as {`-C`}[rdoc-ref:@-C+Set+Working+Directory],
+{`-I`}[rdoc-ref:@-I+Add+to+LOADPATH], and "custom options" by
+{`-s`}[rdoc-ref:@-s+Define+Global+Variable], are applied:
+
 Whitespace between the option and its argument may be omitted.
 
 ### `-s`: Define Global Variable
-- 
cgit v1.2.3