Metadata-Version: 2.4
Name: macports-viz
Version: 0.1.0
Summary: See why MacPorts ports are installed, where outdated ones come from, and what you can clean up
Keywords: macports,dependencies,graph,macos,package-manager
Author: Maciek Szczesniak
Author-email: Maciek Szczesniak <maciek@id43.net>
License-Expression: MIT
License-File: LICENSE
License-File: src/portviz/static/vendor/LICENSE-cytoscape-dagre.txt
License-File: src/portviz/static/vendor/LICENSE-cytoscape.txt
License-File: src/portviz/static/vendor/LICENSE-dagre.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# macports-viz

See why MacPorts ports are installed, where your outdated ones come from, and what
you can clean up. Installs a `portviz` command.

portviz reads the MacPorts registry (`/opt/local/var/macports/registry/registry.db`)
directly, read-only and without locks, and combines it with `port outdated`.
Descriptions, homepages, Portfile paths and build dependencies come from the local
PortIndex that `port selfupdate` keeps current.
No dependencies beyond the Python standard library; the UI's JS libraries are vendored.

## Run

```sh
uvx macports-viz                 # open the interactive graph in your browser
uvx macports-viz outdated        # or any other command below
uv tool install macports-viz     # or install it as a `portviz` command
```

Needs macOS with MacPorts and Python 3.11+ (uv fetches one if needed).

From a checkout: `uv run portviz`, or `uv tool install --editable .`.

## Commands

| Command | What it shows |
| --- | --- |
| `portviz` / `portviz serve` | Web UI: outdated / requested / unneeded lists, dependency graph, details |
| `portviz outdated` | Outdated ports, grouped by whether something you requested needs them, and which requested ports pull in the most |
| `portviz why PORT` | Tree of dependents from PORT up to the ports you requested |
| `portviz unneeded` | Ports nothing you requested depends on, with an uninstall command |
| `portviz cleanup [-v]` | Disk used by inactive versions, leftover build dirs, distfiles and logs, with commands to clean each (also the Cleanup button in the UI) |

Global options: `--prefix` (default `/opt/local`), `--no-outdated` (skip `port outdated`).
`serve` takes `--port` (default 8017) and `--no-browser`.

## License

MIT. The bundled web UI includes [Cytoscape.js](https://js.cytoscape.org/),
[dagre](https://github.com/dagrejs/dagre) and
[cytoscape-dagre](https://github.com/cytoscape/cytoscape.js-dagre), all MIT; their
licenses ship in `portviz/static/vendor/`.

## Terms

- **requested**: ports you installed explicitly (`port echo requested`).
- **not needed**: not reachable from any requested port. These are usually leftover
  build dependencies (the registry only records library and runtime dependencies), so you
  can often uninstall them instead of upgrading. Keep one with `sudo port setrequested NAME`.
- **used to build**: installed ports whose current Portfile lists this one as a
  fetch/extract/build dependency. Only relevant when those are built from source.
- **frees N**: ports only this requested port needs, which uninstalling it
  (`sudo port uninstall --follow-dependencies NAME`) would also remove.
