From 629bad4abae141cb72a138cde9c98ad74181fbd0 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 11 Apr 2022 05:49:59 +0800
Subject: [PATCH] Update PTY.spawn's document

Passing the optional env hash to PTY.spawn has been supported for years, but it's never documented.
More info: https://bugs.ruby-lang.org/issues/12312
---
 ext/pty/pty.c | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/ext/pty/pty.c b/ext/pty/pty.c
index cb663ab2de..c85f1dcae3 100644
--- a/ext/pty/pty.c
+++ b/ext/pty/pty.c
@@ -539,10 +539,10 @@ pty_detach_process(VALUE v)
 
 /*
  * call-seq:
- *   PTY.spawn(command_line)  { |r, w, pid| ... }
- *   PTY.spawn(command_line)  => [r, w, pid]
- *   PTY.spawn(command, arguments, ...)  { |r, w, pid| ... }
- *   PTY.spawn(command, arguments, ...)  => [r, w, pid]
+ *   PTY.spawn([env,] command_line)  { |r, w, pid| ... }
+ *   PTY.spawn([env,] command_line)  => [r, w, pid]
+ *   PTY.spawn([env,] command, arguments, ...)  { |r, w, pid| ... }
+ *   PTY.spawn([env,] command, arguments, ...)  => [r, w, pid]
  *
  * Spawns the specified command on a newly allocated pty. You can also use the
  * alias ::getpty.
@@ -550,6 +550,13 @@ pty_detach_process(VALUE v)
  * The command's controlling tty is set to the slave device of the pty
  * and its standard input/output/error is redirected to the slave device.
  *
+ * +env+ is an optional hash that provides additional environment variables to the spawned pty.
+ *
+ *   # sets FOO to "bar"
+ *   PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") { |r,w,pid| p r.read } #=> "bar\r\n"
+ *   # unsets FOO
+ *   PTY.spawn({"FOO"=>nil}, "printenv", "FOO") { |r,w,pid| p r.read } #=> ""
+ *
  * +command+ and +command_line+ are the full commands to run, given a String.
  * Any additional +arguments+ will be passed to the command.
  *