doc: update readme

README.md

@@ -36,8 +36,8 @@ I don't know if anybody can make use of this, but here you go.
 ### What is the scope?
 
 I don't know yet.
-Maybe I will add more features, and copy more of the original brew CLI.
-But most importantly, it should be simple and dependency free.
+Maybe I will add more features, or copy more of the original brew CLI.
+But most importantly, this script should be simple and dependency free.
 
 brew.py focuses on:
 - downloading pre-built binaries (bottles) from Brew.sh or GitHub registry
@@ -47,14 +47,14 @@ brew.py focuses on:
 What brew.py does **NOT** do:
 - build from source code
 - search or browse packages (use Brew.sh for that)
-- formula analysis & dependency checks (use Brew.sh to check if a package is suitable for your machine)
-- cask management (beyond mere download)
+- install from formula (only homebrew-core)
+- cask management
 
 
 ## Usage
 
 ```
-usage: brew.py [-h] [-q] [--version] command ...
+usage: brew.py [-h] [-v] [-q] [--version] command ...
 
 A lightweight replacement for Homebrew
 
@@ -62,8 +62,14 @@ positional arguments:
   command
     info                List versions, dependencies, platforms, etc.
     home (homepage)     Open a project's homepage in a browser.
-    fetch               Download bottle (binary tar) for package.
+    fetch (download, bottle)
+                        Download bottle (binary tar) for package.
     list (ls)           List installed packages.
+    outdated (old)      Show packages with an updated version available.
+    upgrade (update, up)
+                        Upgrade outdated packages. Will delete old versions,
+                        unless package is pinned. Pinned packages are skipped
+                        by default but can be upgraded if provided
     deps                Show dependencies for package.
     uses                Show dependents of package (reverse dependencies).
     leaves              List installed packages that are not dependencies of
@@ -71,21 +77,80 @@ positional arguments:
     missing             Check the given packages for missing dependencies. If
                         no packages are provided, check all kegs. Will exit
                         with a non-zero status if any are found to be missing.
-    install             Install a package with all dependencies.
+    install (add)       Install package(s) with all dependencies.
     uninstall (remove, rm)
                         Remove / uninstall a package.
     link (ln)           Link a specific package version (activate).
     unlink              Remove symlinks for package to (temporarily) disable
                         it.
     switch              Change package version.
-    cleanup             Remove old versions of installed packages. If
+    toggle              Link/unlink all binaries of a single package. Can be
+                        used to switch between versioned packages
+                        (automatically disables other versions, e.g. node <=>
+                        node@22).
+    pin                 Prevent specified packages from being upgraded.
+    unpin               Allow specified packages to be upgraded.
+    cleanup (clean)     Remove old versions of installed packages. If
                         arguments are specified, only do this for the given
-                        packages. Removes all downloads more than 21 days old.
-                        This can be adjusted with
-                        $BREW_PY_CLEANUP_MAX_AGE_DAYS.
+                        packages. Removes all downloads older than 21 days
+                        (see config.ini).
 
 optional arguments:
   -h, --help            show this help message and exit
-  -q, --quiet           reduce verbosity (-q or -qq)
+  -v, --verbose         increase verbosity
+  -q, --quiet           reduce verbosity (-q up to -qqq)
   --version             show program's version number and exit
 ```
+
+
+#### Show dependencies
+
+output of `brew.py deps node --tree`
+
+```
+node
+├─╴brotli
+├─╴c-ares
+├─╴icu4c@77
+├─╴libnghttp2
+├─╴libnghttp3
+├─╴libuv
+├─╴simdjson
+├─╴libngtcp2
+│  └─╴openssl@3
+│     └─╴ca-certificates
+├─╴openssl@3
+│  └─╴ca-certificates
+├─╴sqlite
+│  └─╴readline
+├─╴uvwasi
+│  └─╴libuv
+└─╴zstd
+   ├─╴lz4
+   └─╴xz
+```
+
+
+... or inverse dependencies `brew.py uses ca-certificates --tree`
+
+```
+ca-certificates
+└─╴openssl@3
+   ├─╴node
+   └─╴libngtcp2
+      └─╴node
+```
+
+
+optionally as dot graph `brew.py uses ca-certificates --dot`
+
+```dot
+digraph G {
+{rank=same; "ca-certificates" [shape=box, style=dashed];}
+"openssl@3" -> "ca-certificates";
+"node" -> "libngtcp2";
+"libngtcp2" -> "openssl@3";
+"node" -> "openssl@3";
+}
+```
+![dot-graph of uses ca-certificates](doc/dot-graph.png)