In os/exec, when should you use cmd.StdoutPipe() instead of assigning a bytes.Buffer to cmd.Stdout?

## Two ways to get a child's output `os/exec` gives you two quite different mechanisms for capturing what a child process writes to standard output, and choosing between them is the first decision you make when you shell out from Go. **Shape one — give os/exec a writer.** ```go cmd := exec.Command("wc", "-l") var out bytes.Buffer cmd.Stdout = &out ``` `cmd.Stdout` is an `io.Writer`. What os/exec does with it depends on what you put there: - **`nil`** — the child's standard output is connected to the null device (`os.DevNull`). Output is discarded; it is not inherited from the parent. - **an `*os.File`** — that file's descriptor is handed straight to the child. No pipe is created, nothing is copied inside your process, and the child writes to the file or terminal itself. This is the cheapest form. - **any other writer** — os/exec creates an operating-system pipe, gives the write end to the child, and starts an internal goroutine that copies from the read end into your writer. `cmd.Wait` waits for the process *and* for that copying goroutine before it returns. That last point is the whole convenience: the draining happens whether or not you think about it, so the child can never block on a full pipe because of your code, and by the time `cmd.Wait` returns the writer holds everything. **Shape two — take the pipe yourself.** ```go stdout, err := cmd.StdoutPipe() ``` `cmd.StdoutPipe()` returns an `io.ReadCloser` — the parent's read end of a pipe whose write end goes to the child. Now you are the drainer, and you inherit three obligations: 1. **Read it to end of file before calling `cmd.Wait`.** `Wait` closes the pipes it created once the child exits, so a read that has not finished loses whatever was still in flight and then fails against a closed file. 2. **Keep reading while the child runs.** A pipe is a small fixed-size kernel buffer, not a queue that grows. If you stop reading, the child blocks on its next write. 3. **Drain every pipe you took, concurrently.** If you take both `cmd.StdoutPipe()` and `cmd.StderrPipe()` and read them one after the other, the unread one can fill and stall the child. You do not normally need to `Close` the reader: `Wait` closes it for you. ## How to choose Ask two questions about the child's output. **How much of it is there?** A `bytes.Buffer` grows without bound. Every byte the child prints is retained in your process's memory until `cmd.Wait` returns. For a command whose output you can bound — a version string, a few thousand lines of a report, a checksum — that is fine and simplest. For a child that streams a converted dataset, tails a log, or is not fully under your control, buffering it all is an out-of-memory incident waiting for a big input. **When do you need it?** A buffer is only useful *after* the command finishes. If you want to show progress, parse records as they appear, forward them to another sink, or stop early when you have seen enough, you need the pipe, because that is the only shape that lets you act on the first bytes while the child is still running. ```go stdout, _ := cmd.StdoutPipe() cmd.Start() sc := bufio.NewScanner(stdout) for sc.Scan() { fmt.Println(sc.Text()) } cmd.Wait() ``` ## A middle path The two shapes are not exclusive. `cmd.Stdout` accepts any writer, so you can pass something that is not a `bytes.Buffer`: an open file, a `bufio.Writer` around a network connection, an `io.MultiWriter`, or your own small writer that counts bytes and returns an error past a cap. You keep os/exec's automatic draining and still avoid unbounded memory. Likewise, if you have taken a pipe and simply want all of it, `io.ReadAll(stdout)` before `cmd.Wait` is correct — but at that point you have written by hand what setting `cmd.Stdout` would have done for you. ## The practical rule Default to assigning a writer, because it removes an entire class of ordering and draining bugs. Move to `cmd.StdoutPipe()` deliberately, when streaming or unbounded volume makes it necessary — and when you do, treat "read to end of file, then `cmd.Wait`" as a single indivisible sequence.