Zsh: stdout and stderr both to console AND log

To redirect both standard output and standard error to the console and a log file in Zsh, use the tee command with process substitution. The pattern command 2>&1 | tee -a logfile captures all output streams, displays them on the terminal, and appends them to the specified file. This approach ensures that debugging information is visible in real-time while preserving a persistent record for later analysis without requiring complex background job management or environment variable hacks.

Understanding File Descriptors

Before implementing redirection, it is essential to understand how shells handle data streams. Every running process in Unix-like systems has three default file descriptors: standard input (fd 0), standard output (fd 1), and standard error (fd 2). By default, both fd 1 and fd 2 point to your terminal emulator. When you run a script, any text printed to stdout appears on the screen, and errors printed to stderr also appear on the screen. To capture these into a file while keeping them visible, you must merge these streams before passing them to a utility like tee. The shell uses specific syntax to manipulate these descriptors. The number 1 represents stdout, and 2 represents stderr. The symbol & allows you to refer to another file descriptor by number rather than a filename. For example, 2>&1 means "redirect file descriptor 2 to wherever file descriptor 1 is currently pointing." This merging step is critical because tee only sees one stream of data; if you do not merge stderr into stdout first, the error messages will bypass tee and go directly to the terminal, leaving the log file incomplete.

The Standard Tee Pattern

The most robust and widely used method for simultaneous logging and console display involves piping the merged output to tee. In Zsh, this is achieved using the pipe operator |. The general structure is:

your_command 2>&1 | tee -a /path/to/logfile.log

Let us break down this command. First, 2>&1 redirects standard error to standard output. At this point, both streams are combined into a single stream flowing through the pipe. Next, tee reads from the pipe. The -a flag tells tee to append to the file rather than overwriting it. If you omit -a, each new execution of the command will erase the previous log contents. Without -a, tee creates a new file or truncates an existing one every time the script runs, which is rarely desired for continuous logging. This pattern works identically in Bash and Zsh. If you are coming from a different shell, note that the order of redirection matters. You must merge stderr to stdout (2>&1) *before* piping to tee. Writing | tee logfile 2>&1 is incorrect because the pipe redirects stdout, but stderr remains separate and goes to the terminal, failing to log errors.

Zsh-Specific Considerations

While the tee pattern is universal, Zsh offers some additional features that can refine this process. One common issue users encounter is interleaved output. If multiple processes write to stdout and stderr simultaneously, their lines may mix up in the terminal. Using stdbuf can help force line buffering, ensuring that tee receives complete lines rather than partial chunks, which makes the log file more readable. However, stdbuf is not always available on all systems, so relying on the core shell redirection is safer for portability. Another consideration is how Zsh handles globbing and aliases. If your command involves complex arguments, ensure that quotes are preserved when passing through the pipe. Generally, simple commands work seamlessly. For more complex scenarios involving functions, you might need to wrap the logic in a function to handle exit codes properly. The exit code of a pipeline is determined by the last command, which is tee. If tee succeeds, the pipeline returns success even if the original command failed. To preserve the original exit status, you can use the PIPESTATUS array in Zsh.

your_command 2>&1 | tee -a logfile.log
exit_code=${PIPESTATUS[0]}

This snippet captures the exit status of your_command before tee completes. This is crucial for scripts that need to react to failures. If you ignore this, your script might continue executing despite the primary command failing, leading to cascading errors.

Handling Background Processes

If you need to run a command in the background while logging its output, the syntax changes slightly. You cannot simply append & at the end of the pipeline, as it would detach tee from the foreground job control. Instead, redirect the entire pipeline to a background job:

(your_command 2>&1 | tee -a logfile.log) &

Wrapping the pipeline in parentheses creates a subshell. The ampersand at the end backgrounds this subshell. This ensures that tee continues to run and write to the file even after the parent shell returns control to the user. Note that the terminal output will still appear, but it may be mixed with subsequent prompts. For production scripts, consider using nohup or proper daemonization tools instead of simple backgrounding to avoid orphaned processes.

Alternative Approaches

Some users prefer using Zsh's built-in print or echo capabilities for custom logging functions. While possible, this adds complexity and overhead compared to the external tee utility. Another alternative is using the exec builtin to permanently redirect file descriptors for the duration of a script.

exec 1>>logfile.log 2>&1

This command redirects stdout to the file and stderr to stdout (which is now the file). Consequently, *all* subsequent output in the script goes to the file, and nothing appears on the console. This is useful for silent installation scripts but fails the requirement of displaying output to the console. Combining exec with tee is possible but often leads to confusing code structures. Stick to the pipe method for clarity and maintainability. For those interested in similar redirection techniques in other contexts, see Redirecting stdout and stderr in Bash: Handling apt-get error output. Additionally, understanding how to handle binary or structured output can be beneficial, as discussed in Redirect ffmpeg showinfo to Pipe with Stderr.

Frequently Asked Questions

Why does my log file miss error messages?

You likely forgot to redirect stderr to stdout before piping to tee. If you write command | tee logfile, only stdout is captured. You must use command 2>&1 | tee logfile to ensure both streams enter the pipe.

How do I prevent tee from overwriting my log file?

Always include the -a (append) flag with tee. Without it, tee treats the file as a new output destination and truncates it upon opening. Use tee -a to add new entries to the end of the existing file.

Can I log to multiple files simultaneously?

Yes, you can chain tee commands. For example, command 2>&1 | tee file1.log | tee file2.log will copy the output to both files. The second tee receives the same stream from the first tee and writes it to the second file while passing it along.

Does this method work in Bash?

Yes, the syntax command 2>&1 | tee -a logfile is POSIX-compliant and works identically in Bash, Zsh, and most other POSIX shells. It is the standard portable solution for dual output.

What happens to the exit code of the command?

The exit code of the pipeline is the exit code of the last command, which is tee. If tee succeeds, the pipeline returns 0, hiding the failure of the original command. Use ${PIPESTATUS[0]} in Zsh or $? immediately after checking the pipeline in Bash to retrieve the original command's exit status.