diff --git a/README.md b/README.md index 947e0a1..33ccbfd 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,56 @@ # 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 +Cargo.lock +Cargo.toml +LICENSE +README.md +scripts +src +target + +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 +Cargo.lock +Cargo.toml +LICENSE +README.md +scripts +src +target +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.