Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,14 @@ sudo chmod +x /usr/local/bin/brewshelf
**3. Run**

```bash
brewshelf
brewshelf # what you installed
brewshelf --all # plus everything installed as a dependency
```

By default brewshelf shows only what you installed yourself: formulas installed as a dependency
of another formula (codecs, libraries, …) are hidden and counted at the bottom. On a typical
machine that turns a 160-line list into the ~35 packages you actually chose.

## Requirements

- macOS (tested on macOS Sequoia)
Expand All @@ -73,7 +78,7 @@ brewshelf
| System Libraries | Dim | Low-level dependencies |
| GUI Applications | Green | Homebrew casks |

Unknown packages (not in the built-in catalog) appear under **Other / Dependencies**.
Packages without a category appear under **Other**.

## Descriptions

Expand Down
86 changes: 65 additions & 21 deletions brewshelf.sh
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,18 @@ BLUE=$'\e[34m'
RED=$'\e[31m'
WHITE=$'\e[37m'

# Category of each known formula. Descriptions come from Homebrew itself (load_descriptions).
# Category of each known formula. Descriptions come from Homebrew itself (load_metadata).
typeset -gA PKG_CAT
typeset -gA FORMULA_DESC CASK_DESC
# Formulas installed only as a dependency of another formula (value: 1)
typeset -gA FORMULA_IS_DEP

# Reads the descriptions of all installed packages from `brew info --json=v2 --installed`
# and prints them as "formula|cask <TAB> name <TAB> description" lines.
# Field separator for json_to_rows: ASCII "unit separator". Unlike a tab it is not
# whitespace for `read`, so an empty description does not shift the following fields.
SEP=$'\x1f'

# Reads all installed packages from `brew info --json=v2 --installed` and prints one row
# per package: kind, name, description, installed on request (1/0), separated by $SEP.
# Uses jq when available (bundled with macOS 15+), otherwise JavaScript via osascript,
# which every macOS has. BREWSHELF_JSON_PARSER=jq|osascript forces one (used by the tests).
json_to_rows() {
Expand All @@ -40,32 +46,38 @@ json_to_rows() {

if [[ "$parser" == jq ]]; then
jq -r '
def clean: (. // "") | gsub("[\t\n\r]+"; " ");
(.formulae[]? | ["formula", .name, (.desc | clean)]),
(.casks[]? | ["cask", .token, (.desc | clean)])
| join("\t")'
def clean: (. // "") | gsub("[\t\n\r\u001f]+"; " ");
(.formulae[]? | ["formula", .name, (.desc | clean),
(if any(.installed[]?; .installed_on_request) then "1" else "0" end)]),
(.casks[]? | ["cask", .token, (.desc | clean), "1"])
| join("\u001f")'
else
osascript -l JavaScript -e '
ObjC.import("Foundation");
const data = $.NSFileHandle.fileHandleWithStandardInput.readDataToEndOfFile;
const info = JSON.parse($.NSString.alloc.initWithDataEncoding(data, $.NSUTF8StringEncoding).js);
const clean = (s) => (s || "").replace(/[\t\n\r]+/g, " ");
const clean = (s) => (s || "").replace(/[\t\n\r\x1f]+/g, " ");
const onRequest = (f) => ((f.installed || []).some((i) => i.installed_on_request) ? "1" : "0");
[
...(info.formulae || []).map((f) => ["formula", f.name, clean(f.desc)].join("\t")),
...(info.casks || []).map((c) => ["cask", c.token, clean(c.desc)].join("\t")),
...(info.formulae || []).map((f) => ["formula", f.name, clean(f.desc), onRequest(f)].join("\x1f")),
...(info.casks || []).map((c) => ["cask", c.token, clean(c.desc), "1"].join("\x1f")),
].join("\n");'
fi
}

# Packages from untrusted taps or removed from Homebrew are missing from the JSON;
# they are still listed (from `brew list`), just without a description.
load_descriptions() {
local row kind name desc
# they are still listed (from `brew list`), without a description and treated as
# installed on request — better to show a dependency than to hide something you installed.
load_metadata() {
local row kind name desc on_request
for row in ${(f)"$(brew info --json=v2 --installed 2>/dev/null | json_to_rows 2>/dev/null)"}; do
IFS=$'\t' read -r kind name desc <<< "$row"
IFS=$SEP read -r kind name desc on_request <<< "$row"
case "$kind" in
formula) FORMULA_DESC[$name]=$desc ;;
cask) CASK_DESC[$name]=$desc ;;
formula)
FORMULA_DESC[$name]=$desc
[[ "$on_request" == 0 ]] && FORMULA_IS_DEP[$name]=1
;;
cask) CASK_DESC[$name]=$desc ;;
esac
done
}
Expand Down Expand Up @@ -274,8 +286,14 @@ print_shelf() {

typeset -A cat_items
local -a unknown
local -i hidden=0

for pkg in "${formulas[@]}"; do
# Dependencies are hidden unless --all: they are what makes `brew list` unreadable
if [[ -n "${FORMULA_IS_DEP[$pkg]:-}" && "$SHOW_ALL" != 1 ]]; then
(( hidden++ ))
continue
fi
local cat="${PKG_CAT[$pkg]:-}"
if [[ -n "$cat" ]]; then
cat_items[$cat]+="$pkg "
Expand All @@ -300,16 +318,16 @@ print_shelf() {
print "${BOLD}${color}▶ ${cat}${RESET}"
print "${color}$(printf '─%.0s' {1..50})${RESET}"
for pkg in ${=cat_items[$cat]}; do
printf " ${BOLD}%-30s${RESET} ${DIM}%s${RESET}\n" "$pkg" "${FORMULA_DESC[$pkg]:-}"
print_formula "$pkg"
done
echo ""
done

if [[ ${#unknown[@]} -gt 0 ]]; then
print "${BOLD}${DIM}▶ Other / Dependencies${RESET}"
print "${DIM}$(printf '─%.0s' {1..50})${RESET}"
print "${BOLD}${WHITE}▶ Other${RESET}"
print "${WHITE}$(printf '─%.0s' {1..50})${RESET}"
for pkg in "${unknown[@]}"; do
printf " ${DIM}%-30s %s${RESET}\n" "$pkg" "${FORMULA_DESC[$pkg]:-}"
print_formula "$pkg"
done
echo ""
fi
Expand All @@ -327,9 +345,35 @@ print_shelf() {
local noun="packages"
(( total == 1 )) && noun="package"
print "${DIM} Total: ${total} ${noun} installed${RESET}"
if (( hidden > 0 )); then
print "${DIM} ${hidden} dependencies hidden — run 'brewshelf --all' to show them${RESET}"
elif [[ "$SHOW_ALL" == 1 && ${#FORMULA_IS_DEP[@]} -gt 0 ]]; then
print "${DIM} Dimmed names were installed as dependencies${RESET}"
fi
echo ""
}

# Requested formulas in bold, dependencies (only shown with --all) dimmed
print_formula() {
local desc="${FORMULA_DESC[$1]:-}"
if [[ -n "${FORMULA_IS_DEP[$1]:-}" ]]; then
printf " ${DIM}%-30s %s${RESET}\n" "$1" "$desc"
else
printf " ${BOLD}%-30s${RESET} ${DIM}%s${RESET}\n" "$1" "$desc"
fi
}

SHOW_ALL=0
for arg in "$@"; do
case "$arg" in
-a|--all) SHOW_ALL=1 ;;
*)
print -u2 "brewshelf: unknown option '$arg' (available: --all)"
exit 2
;;
esac
done

init_data
load_descriptions
load_metadata
print_shelf
52 changes: 44 additions & 8 deletions tests/run.zsh
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,20 @@ OUT="" STATUS=0
cat > "$WORK/info.json" <<'JSON'
{
"formulae": [
{ "name": "node", "desc": "Open-source, cross-platform JavaScript runtime environment" },
{ "name": "ffmpeg", "desc": "Play, record, convert, and stream audio and video" },
{ "name": "sqlite", "desc": "Command-line interface for SQLite" },
{ "name": "some-unknown-formula", "desc": "Formula without a category" },
{ "name": "multiline", "desc": "First line\tand a tab\nsecond line" }
{ "name": "node", "desc": "Open-source, cross-platform JavaScript runtime environment",
"installed": [{ "installed_on_request": true }] },
{ "name": "ffmpeg", "desc": "Play, record, convert, and stream audio and video",
"installed": [{ "installed_on_request": true }] },
{ "name": "sqlite", "desc": "Command-line interface for SQLite",
"installed": [{ "installed_on_request": true }] },
{ "name": "some-unknown-formula", "desc": "Formula without a category",
"installed": [{ "installed_on_request": true }] },
{ "name": "multiline", "desc": "First line\tand a tab\nsecond line",
"installed": [{ "installed_on_request": true }] },
{ "name": "libvpx", "desc": "VP8/VP9 video codec",
"installed": [{ "installed_on_request": false }] },
{ "name": "no-desc-dep", "desc": null,
"installed": [{ "installed_on_request": false }] }
],
"casks": [
{ "token": "ngrok", "desc": "Reverse proxy, secure introspectable tunnels to localhost" }
Expand All @@ -33,15 +42,16 @@ JSON
# Extra environment for the next run_brewshelf call, e.g. (BREWSHELF_JSON_PARSER=osascript)
typeset -a EXTRA_ENV=()

# run_brewshelf <formulas> <casks> [shell] — lists are newline-separated names
# run_brewshelf <formulas> <casks> [shell [args...]] — lists are newline-separated names
run_brewshelf() {
print -rn -- "$1" > "$WORK/formulas"
print -rn -- "$2" > "$WORK/casks"
local shell=${3:-zsh}
local -a args=("${@:4}")
OUT=$(env -i HOME="$HOME" PATH="$TEST_PATH" \
FAKE_BREW_FORMULAS="$WORK/formulas" FAKE_BREW_CASKS="$WORK/casks" \
FAKE_BREW_JSON="$WORK/info.json" "${EXTRA_ENV[@]}" \
"$shell" "$SCRIPT" 2>&1)
"$shell" "$SCRIPT" "${args[@]}" 2>&1)
STATUS=$?
# Strip ANSI colors so assertions match plain text
OUT=$(print -r -- "$OUT" | sed $'s/\e\\[[0-9;]*m//g')
Expand Down Expand Up @@ -77,7 +87,7 @@ check "counts formulas + casks" contains "Total: 4 packages installed"

print "unknown packages"
run_brewshelf $'node\nsome-unknown-formula' ''
check "puts unknown formulas under Other" contains "▶ Other / Dependencies"
check "puts unknown formulas under Other" contains "▶ Other"
check "lists the unknown formula" contains "some-unknown-formula"
check "describes the unknown formula too" contains "Formula without a category"

Expand All @@ -93,6 +103,30 @@ check "brew info failing: exits 0" status_is 0
check "brew info failing: still lists packages" contains "node"
EXTRA_ENV=()

print "dependencies"
run_brewshelf $'node\nlibvpx\nno-desc-dep' ''
check "hides dependencies by default" not_contains "libvpx"
check "hides a dependency without description" not_contains "no-desc-dep"
check "still counts them" contains "Total: 3 packages installed"
check "says how many are hidden" contains "2 dependencies hidden — run 'brewshelf --all'"
check "keeps requested formulas" contains "node"
run_brewshelf $'node\nuntrusted-formula' ''
check "shows formulas missing from brew info (cannot tell)" contains "untrusted-formula"
check "no hidden note when nothing is hidden" not_contains "hidden"
run_brewshelf $'node\nlibvpx\nno-desc-dep' '' zsh --all
check "--all: shows dependencies" contains "libvpx"
check "--all: with their description" contains "VP8/VP9 video codec"
check "--all: shows a dependency without description" contains "no-desc-dep"
check "--all: explains dimmed names" contains "Dimmed names were installed as dependencies"
check "--all: no hidden note" not_contains "hidden"

print "options"
run_brewshelf $'node' '' zsh --bogus
check "unknown option: exits 2" status_is 2
check "unknown option: names it" contains "unknown option '--bogus'"
run_brewshelf $'node\nlibvpx' '' zsh -a
check "-a works like --all" contains "libvpx"

print "JSON parsers"
for parser in jq osascript; do
if [[ $parser == jq ]] && ! PATH=$TEST_PATH command -v jq >/dev/null; then
Expand All @@ -103,6 +137,8 @@ for parser in jq osascript; do
run_brewshelf $'node\nsome-unknown-formula' $'ngrok'
check "$parser: formula description" contains "Open-source, cross-platform JavaScript runtime environment"
check "$parser: cask description" contains "Reverse proxy, secure introspectable tunnels to localhost"
run_brewshelf $'node\nlibvpx\nno-desc-dep' ''
check "$parser: hides dependencies" contains "2 dependencies hidden"
done
EXTRA_ENV=()

Expand Down
Loading