From 426e03c75e964f48f06e6914309101590d94b8eb Mon Sep 17 00:00:00 2001
From: tamnd <1218621+tamnd@users.noreply.github.com>
Date: Sat, 25 Jul 2026 22:20:19 +0700
Subject: [PATCH] docs: say which formats --fields actually narrows

It said every format. It narrows the column formats and leaves json,
jsonl, and raw carrying the whole record, so the page now says that and
shows the jq one-liner for the other half.
---
 docs/content/reference/output.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/content/reference/output.md b/docs/content/reference/output.md
index b6f4ed0..81e8a33 100644
--- a/docs/content/reference/output.md
+++ b/docs/content/reference/output.md
@@ -72,7 +72,15 @@ A non-empty `extra` is a bug report: it means the site added something and this
 github tags golang/go --fields name,sha
 ```
 
-`--fields` works on every format, and it can call back a field the table hides, since a hidden field keeps its name.
+`--fields` works on the column formats: `table`, `csv`, `tsv`, `markdown`, and `list`.
+It can call back a field the table hides, since a hidden field keeps its name.
+
+It does not touch `json`, `jsonl`, or `raw`, which always carry the whole record.
+Narrow those with `jq`:
+
+```bash
+github tags golang/go -n 3 | jq '{name, sha}'
+```
 
 `--no-header` drops the header row from `table`, `csv`, and `tsv`, which is what a downstream tool usually wants.