Merge pull request #99 from go-cmd/dn/v1.4.2

Prepare v1.4.2: update docs, go.mod, some code comments

Author: daniel-nichter

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## v1.4
 
+### v1.4.2 (2023-07-08)
+
+* Added `Options.CombinedOutput` based on PR #76 by @jwomackgsa (issue #70)
+
 ### v1.4.1 (2022-03-27)
 
 * Added `Options.LineBufferSize` based on PR #85 by @Crevil (issue #66)

cmd.go

@@ -147,16 +147,17 @@ type Options struct {
 // See Cmd.Status for more info.
 Buffered bool
 
-// If CombinedOutput is true, STDOUT and STDERR are written to Status.Stdout ONLY similar to 2>&1.
-// If CombinedOutput is used at the same time as Buffered, CombinedOutput will take preference.
-// Status.StdErr will be empty. The caller can call Cmd.Status to read output at intervals.
-// See Cmd.Status for more info.
+// If CombinedOutput is true, STDOUT and STDERR are written only to Status.Stdout
+// (similar to 2>&1 on Linux), and Status.StdErr will be empty. If CombinedOutput
+// is used Buffered, CombinedOutput takes preference. CombinedOutput does not work
+// with Streaming.
 CombinedOutput bool
 
 // If Streaming is true, Cmd.Stdout and Cmd.Stderr channels are created and
 // STDOUT and STDERR output lines are written them in real time. This is
 // faster and more efficient than polling Cmd.Status. The caller must read both
-// streaming channels, else lines are dropped silently.
+// streaming channels, else lines are dropped silently. Streaming does not work
+// with CombinedOutput.
 Streaming bool
 
 // BeforeExec is a list of functions called immediately before starting
@@ -166,8 +167,7 @@ type Options struct {
 
 // LineBufferSize sets the size of the OutputStream line buffer. The default
 // value DEFAULT_LINE_BUFFER_SIZE is usually sufficient, but if
-// ErrLineBufferOverflow errors occur, try increasing the size with this
-// field.
+// ErrLineBufferOverflow errors occur, try increasing the size with this field.
 LineBufferSize uint
 }
 
@@ -227,10 +227,9 @@ func NewCmdOptions(options Options, name string, args ...string) *Cmd {
 return c
 }
 
-// Clone clones a Cmd. All the options are transferred,
-// but the internal state of the original object is lost.
-// Cmd is one-use only, so if you need to re-start a Cmd,
-// you need to Clone it.
+// Clone clones a Cmd. All the options are transferred, but the internal state
+// of the original object is lost. Cmd is one-use only, so if you need to restart
+// a Cmd, you need to Clone it.
 func (c *Cmd) Clone() *Cmd {
 clone := NewCmdOptions(
 Options{
@@ -340,8 +339,7 @@ func (c *Cmd) Stop() error {
 // consider using streaming output. When the command finishes, buffered output
 // is complete and final.
 //
-// Status.Runtime is updated while the command is running and final when it
-// finishes.
+// Status.Runtime is updated while the command runs and is final when it finishes.
 func (c *Cmd) Status() Status {
 c.Lock()
 defer c.Unlock()

go.mod

@@ -1,5 +1,5 @@
 module github.com/go-cmd/cmd
 
-go 1.17
+go 1.20
 
-require github.com/go-test/deep v1.0.7
+require github.com/go-test/deep v1.1.0

go.sum

@@ -1,2 +1,2 @@
-github.com/go-test/deep v1.0.7 h1:/VSMRlnY/JSyqxQUzQLKVMAskpY/NZKFA5j2P+0pP2M=
-github.com/go-test/deep v1.0.7/go.mod h1:QV8Hv/iy04NyLBxAdO9njL0iVPN1S4d/A3NVv1V36o8=
+github.com/go-test/deep v1.1.0 h1:WOcxcdHcvdgThNXjw0t76K42FXTU7HpNQWHpA2HHNlg=
+github.com/go-test/deep v1.1.0/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=