From c4c588038c699c6697044f37447ba4a5837f2761 Mon Sep 17 00:00:00 2001 From: "Christoph J. Scherr" Date: Wed, 21 Feb 2024 16:26:57 +0100 Subject: [PATCH] readme --- README.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 947e0a1..6bf6108 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,39 @@ # seep -print stdin to terminal, then pipe into next process +Print `stdin` to terminal, then pipe into next process. + +`seep` (short for see pipe and also to describe leaks in real pipes) has the +purpose of letting you peek at what you're piping. + +## Usage + +On Unix like systems, you can pass the output (`stdout`) of one process to the +other as input, like this: `echo "foo" | hexdump`. In some cases, the output of +the first command might contain information that a user might want to look at. + +When the second process does not show the information it received, the user +cannot *see* the information produced by the first program. This is where `seep` +comes useful: + +To look at the output of process one, we pipe it to `seep` and then pipe the +output of `seep` to process two. `seep` will show us what information it +receives and pass it over to process two: + +```bash +ls | seep | grep src +``` +(list files and dirs, show all with `seep`, show only containing "src") + +## Similarity to `tee` + +The command `tee` is part of the coreutils and available on almost any Unix like +system. It can be used to achieve similar things as `seep`, for example: + +```bash +ls | tee $TTY | grep src +``` +(list files and dirs, show all with `tee`, show only containing "src") + +`tee` and `seep` do not have the same features. Currently, `seep` cannot output +to files specified with cli arguments, and `seep`'s focus lies on presenting +information to the user.