Skip to content
atif-1402Public

About

Make messy Linux command output readable. Formats git, systemctl, journalctl, ps, ip, ss, lsof and more. Single Go binary, stdlib only.

Topics

Resources

Contributing

Stars

14 stars

Watchers

0 watching

Forks

Repository files navigation

parse

Single Go binary · Standard library only · Linux only

release Go 1.21+ MIT license Linux only standard library only

Install · Usage · Supported tools · Diffs · Docker · Bugs · Contributing · Releases

parse demo

Status: v0.2.7. Feedback and bug reports welcome. See reporting bugs.

parse git diff -w          # old | new, side by side
parse ip addr              # one tidy group per interface
parse journalctl -n 50     # dimmed prefix, colored severities
parse ss                   # the Process column gets its own column
parse docker system df -v  # sizes normalized, cache collapsed to one line
parse curl -I https://example.com  # status colored, header keys cyan

The one rule

Format output that is hard to read. Leave output that already reads well exactly as the tool printed it. Machine-readable formats and anything interactive are never touched, so your scripts keep working.

  • Exit codes are the tool's own.
  • stderr stays on stderr, never mixed into formatted text.
  • If parse isn't sure what it is looking at, it passes your bytes through unchanged.

Install

Install the latest Release of parse for AUR

yay -S parse

or (Requires Go. see go.mod for the minimum version).

go install github.com/atif-1402/parse@latest

Or build from source:

git clone https://github.com/atif-1402/parse
cd parse
make build       # creates ./parse
make install

Usage

Two ways, same result.

Run the tool through parse:

parse git status
parse git log -n 10
parse systemctl --user status
parse ps aux --sort=-%mem
parse du -sh ~/src
parse lsof -i

Pipe into parse:

git status | parse
ip addr | parse
ps aux | parse

parse <tool> ... accepts every normal argument for that tool. Any tool parse doesn't support is refused with one line (parse: ls is not supported yet). Piping is the other way round: unknown text comes out byte for byte, so ls | parse and df -h | parse are always safe.

Run parse -l to see every supported command and what it changes, or parse -h for full usage.

Supported tools

Tool What parse does
git status, log, diff, show, branch, blame, grep, stash, remote, shortlog, reflog, and more
systemctl status, list-units, list-unit-files, is-active, is-failed
journalctl timestamp/host/unit dimmed, severities colored
ps aux and friends: busy values tinted, long COMMAND dimmed
find -ls turned into named columns
du sizes always carry a unit, large entries tinted
findmnt mount tree dimmed, filling filesystems tinted
mount rows lined up as a table: filesystem types colored, options quietened, a read-only mount marked
gcc diagnostics grouped by file, count summary up front, severity colored, source line + caret shown
clang diagnostics grouped by file, count summary up front, severity colored, source line + caret shown
free bare numbers get a unit, a filling machine is tinted
lsof socket state colored, heading bolded
ip addr / link collapsed per interface, route colored
ss colliding headers split, process name in its own column
lsblk device tree dimmed, wrapped mountpoints indented
kubectl experimental, see below
docker ps: names bold, STATE colored by state with exit codes and uptime; inspect: semantic sections (state, network, ports, env with secrets masked — --show-secrets reveals real values); network inspect: name/driver/scope/subnet header, attached containers as a NAME/IPv4/MAC table sorted by name, empty networks get one dim line; system df: size-ordered summary (build cache included; -v pipe sums marked ~, direct mode re-runs plain df for exact totals), tables sorted by size then state then name, sizes normalized, unused/dangling tagged, -v containers reduced to NAME/STATE/SIZE with empty ones on one dim line, -v build cache collapsed to one line (--all shows the rows)
curl -I/-i: status line colored by code (2xx green, 3xx yellow, 4xx/5xx red), header keys cyan, body untouched; -v: verbose noise dimmed, failures red, response status still colored, { … bytes data] markers dimmed; a bare curl: (n) failure painted red; the progress meter is dropped from piped output

Everything else a tool can do runs unchanged. Mutating commands (systemctl start, git commit, kubectl apply, ...) are never altered.

Side-by-side diffs

A unified diff makes you read it twice: once to match each - with its +, once to understand the result. parse git diff -w puts the old version on the left and the new one on the right, with line numbers on both sides:

app.py  +3 -2
@@ -1,5 +1,6 @@
2 def process(data):                    │ 2 def process(data, opts):
3     result = compute(data)            │ 3     result = compute(data, opts)
                                        │ 4     logger.info(result)
3     return result                     │ 4     return result
4                                       │ 5
5 def other():                          │ 6 def other():
  • Opt-in, because it lays out to your terminal width. Under about 27 columns it falls back to one column.
  • Long lines are cut with …, not wrapped. Double-width (CJK) characters are counted correctly.

What parse never touches

Machine formats are passed through byte for byte:

Format Why
git diff --numstat, --name-only, --name-status, --raw, --shortstat, --stat scripts read these
git diff --word-diff not a normal patch layout
findmnt -r -P -y -J raw, pairs, shell, JSON
journalctl -o json, -o export, -o cat machine formats
lsof -F, lsof -t script input
lsblk --output script input
free -h already readable (tint only), unit-pinned forms pass through
docker --format templates and JSON scripts read these; network inspect JSON also falls back to raw when a render would say less than docker
curl bodies, JSON, -w write-outs data a script reads; only -I/-i headers, -v streams and curl: (n) failures are formatted
anything with -f / --follow / --watch never ends, handed straight to the terminal

Known limit: two formats that print identical bytes can't be told apart. git status --porcelain is byte-identical to git status -s, so both get formatted.

Paging

On a terminal, long output goes through a pager (less -R -F -X by default). Output that fits on one screen is printed straight through.

parse will not page when:

  • stdout is not a terminal (parse journalctl > log.txt just writes the file)
  • the command is interactive (git add -p, git commit without -m)
  • the command never ends (journalctl -f, kubectl logs -f)
  • TERM is dumb or unset
  • no pager is installed

Change the pager with PARSE_PAGER or PAGER. Turn it off with --no-pager:

PARSE_PAGER=most parse journalctl -n 200
parse --no-pager journalctl -n 200

Color

--color=auto|always|never works on either side of the subcommand. auto (default) colors only on a terminal and respects NO_COLOR.

parse --color=always git log | less
git status | parse --color=never

If parse has a formatter for a command, it replaces the tool's own color with its palette. If it doesn't, text passes through untouched, color included, so grep --color=always ... | parse keeps its highlight.

In the middle of a pipeline (cmd | parse | other), parse's stdout is not a terminal, so auto leaves color off and the bytes pass through unchanged — the next command gets clean input. Force color when the reader handles ANSI:

docker inspect demo-web | parse --color=always | less -R

Piped input is auto-detected

When text arrives on stdin, parse works out which tool produced it from its header or shape. This is deliberately strict: a false positive would rewrite another tool's output, so anything unrecognized is passed through unchanged. If you'd rather be explicit, use parse <tool> ... instead of piping.

Details worth knowing

  • git log gets --decorate=short added unless you set a decoration mode, because git hides branch/tag markers when output isn't a terminal. Use --no-decorate or --pretty/--format to keep git's own behavior.
  • -w before a tool name is parse's side-by-side flag. After the tool name it belongs to the tool (git log -w still means "ignore whitespace").
  • English output only. In another locale, headers won't match and output passes through unchanged.

kubectl (experimental)

Works as a command and as a pipe, but has never been run against a live cluster. It was written from the Kubernetes docs and tested against hand-written fixtures. When unsure, it passes your bytes through untouched, so the worst case is plain kubectl output.

Formatted: get tables (aligned, STATUS / READY / RESTARTS tinted) and describe. Passed through: -o json|yaml|name|jsonpath|custom-columns, --template, --no-headers, -w, kubectl get all, and every other verb.

If you run a cluster and it formats something wrongly, please open an issue.

docker

docker demo

Works as a command and as a pipe. Six subcommands are formatted, each against live Docker output on this machine:

  • ps — names bold, STATE colored by state with exit codes and uptime, busy ports tinted.
  • inspect — semantic sections: state, network, ports, env with secrets masked (--show-secrets reveals real values). Networks get a name/driver/scope/subnet header, attached containers as a NAME / IPv4 / MAC table sorted by name, and no containers attached when empty. Ids, endpoint ids and unset flags are hidden.
  • image inspect — tags and short id, size/created/os-arch, layers, entrypoint/cmd, user (root dimmed), ports, workdir and healthcheck; env is reduced to what the user's own image baked in, with base-image defaults hidden. Secrets baked into an image are masked, and --show-secrets reveals them. Mixed arrays decide per object, and an unknown object is printed raw.
  • volume inspect — bold name header with driver and scope, then mountpoint, created, and labels / options rows as sorted key=value pairs — empty maps never print. Mixed arrays decide per object, and an unknown object is printed raw.
  • info — one-screen summary: version/context/host header, containers, storage, cgroup, runtime, system, logging and plugin versions, with non-default flags (swarm, insecure registries, rootless/userns, live restore, debug, experimental) shown only when set. Warnings are kept verbatim, and the last line says how much was left out: N more fields hidden, run docker info for everything.
  • system df — size-ordered summary with build cache included; sizes normalized to four significant digits; unused images and dangling layers tagged; -v containers reduced to NAME/STATE/SIZE with the empty ones on one dim line broken down by state; -v build cache collapsed to one line (--all shows the rows). Piped -v sums are marked ~; running the command directly (parse docker system df -v) re-runs plain df for exact totals.

Everything else passes through byte for byte: --format templates, JSON, and any other verb. When a formatter would print less than docker itself — a network JSON that yields fewer than two lines, say — parse falls back to the raw output instead.

Project layout

main.go            CLI entry, stdin reading, dispatch
colors.go          ANSI color helpers
pager.go           pager policy and launching
cmd/               one package per tool, plus the Pipe dispatcher
internal/tool/     shared plumbing: hooks, capture, exit codes
test/              end-to-end tests

Each tool lives in its own folder under cmd/. Each has an internal test beside its source for unexported helpers, and test/ covers the exported entry points end to end.

Reporting bugs

Please include:

  1. The exact command you ran (or the command you piped from)
  2. The raw output of the tool without parse
  3. What parse printed instead
  4. Distro and tool version (ip -V, systemctl --version, ps --version, ...)

Real-world output from different distros is the most useful thing you can send.

License

MIT

Contributing

Want to add a tool or fix one? See CONTRIBUTING.md for the ground rules, how to add a tool under cmd/, and what make check expects before a pull request.

About

Make messy Linux command output readable. Formats git, systemctl, journalctl, ps, ip, ss, lsof and more. Single Go binary, stdlib only.

Topics

Resources

Contributing

Stars

14 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Contributors

Languages