ANNOTATE-OUTPUT(1)

🎀 ANNOTATE-OUTPUT(1) 🎀

Okay bestie, let's talk about annotate-output(1) 💅 It's a manual page for a tool that is literally iconic at one job: it stamps your program's output with a time and a stream label so you can see what happened and when 🦋

---

✨ NAME ✨

annotate-output - annotate program output with time and stream 💖

🌸 SYNOPSIS 🌸

annotate-output [options ...] [--] program [args ...]

💜 DESCRIPTION 💜

okay so annotate-output runs your program with its args and then glues a little prefix onto every line the program prints 🧚 The prefix is a time format string, then a stream indicator, then a colon and a single space.

The stream indicators are:

• I for info coming from annotate-output itself 💅
• O for STDOUT from program 🌈
• E for STDERR from program 🔥

🎀 OPTIONS 🎀

• +FORMAT — this is the format string, and it can use the conversion specifiers from date(1) 🕰️ The timestamp gets a single space before the stream indicator. Later options that set a format string can override it. Defaults to "%H:%M:%S" ⭐
• --raw-date-format FORMAT — same vibe, same date(1) specifiers, but there's no space between the timestamp and the stream indicator 🍓 Later format options can override this one too.
• -- — ends option parsing 🛑 (unless it's already being used as an argument to an option, so don't get it twisted 🙈)
• -h, --help — shows a help message 🫶

🦋 EXIT STATUS 🦋

If program actually gets invoked, annotate-output hands back program's exit status. Otherwise, it exits with one of these:

• 0 — you used -h or --help ✨
• 125 — something went wrong inside annotate-output 💀
• 126 — program was found but couldn't be invoked 😭
• 127 — program couldn't be found, or you didn't specify one at all 🙈

🍓 EXAMPLE 🍓

$ annotate-output make
21:41:21 I: Started make
21:41:21 O: gcc -Wall program.c
21:43:18 E: program.c: Couldn't compile, and took me ages to find out
21:43:19 E: collect2: ld returned 1 exit status
21:43:19 E: make: *** [all] Error 1
21:43:19 I: Finished with exitcode 2

🔥 CAVEATS AND BUGS 🔥

⚠️ read this part, bestie, it's important 😭

Since STDOUT and STDERR are processed in parallel, some lines from STDOUT can show up before later STDERR lines, and the other way around too 🌀 This is unfortunately very hard to fix with the current annotation strategy 😩 A fix would mean switching to PTRACE'ing the process. Giving nice a (much) higher priority over program could make this happen less often, though 🧚

annotate-output expects program to output (text) lines, as specified by POSIX, to STDOUT and STDERR 📝 It leads to undefined behaviour when lines contain NUL bytes 💀 It may also lead to undefined behaviour when lines contain bytes that don't form valid characters in the current locale 🙈

When an interactive program asks for input, the question might not show up until after you've already answered it 😭 That makes it look like program has hung, but it has not, I promise 🫶

annotate-output is implemented as a script in the Shell Command Language 🐚 Shells usually set various (shell) variables when they start, and they may set the export attribute on some of them. They also initialise (shell) variables from their own environment (as set by the caller of the shell, or the caller of annotate-output) and set the export attribute on those too.

So if the caller of annotate-output wants to set the environment (variables) of program, those variables may get overridden, or the shell may add extra ones 👀 Also, environment variables are allowed to have names (for example .) that aren't valid shell variable names. POSIX doesn't specify whether those get exported to programs invoked from the shell, so no assumptions can be made about whether such variables will be exported correctly, or at all, to program 💅

🌈 SEE ALSO 🌈

date(1) 🕰️

🫶 SUPPORT 🫶

annotate-output is community-supported, which means you'll need to fix it yourself 🛠️ Patches are still very much appreciated, and so is any feedback, positive or negative 💖

👑 AUTHOR 👑

This manual page was written by Jeroen van Wolffelaar <jeroen@wolffelaar.nl> and can be redistributed under the terms of the GPL version 2 📜 The annotate-output script itself was re-written by Johannes Schauer Marin Rodrigues <josch@debian.org> and can be redistributed under the terms of the Expat license 🦋

---

Bye bestie 🫶 that's the whole page, straight from the DEBIAN source, Debian Utilities version, ANNOTATE-OUTPUT(1) 💅✨