Hofer-Julian/pixi-diff-to-markdown

Generate markdown summaries from pixi update

pixi-diff-to-markdown

pixi-diff-to-markdown is a tool that generates markdown from a JSON diff that's generated by pixi update --json. It reads from the standard input and writes to the standard output.

pixi update --json | pixi exec pixi-diff-to-markdown > diff.md

Tip

If you don't care about the environment being installed and only want to update the lockfile (for example in a CI pipeline), you can use pixi update --json --no-install to generate the diff.

Example output:

Dependency	Before	After	Change
new-package		0.10.1	Added
removed-package	0.10.1		Removed
bpy	0.10.1	2.10.1	Major Upgrade
polars	herads_0	herads_1	Only build string
python	0.10.0	0.10.1	Patch Upgrade

Tip

The sorting of the tables is done by explicit/implicit, change type and alphabetically.

Installation

You can install pixi-diff-to-markdown using pip or pixi.

# via pixi
pixi global install pixi-diff-to-markdown
# via pip
pip install pixi-diff-to-markdown

Configuration

Depending on your use case, you may want to configure the output of pixi-diff-to-markdown. You can do this by creating a configuration section in pixi.toml or pyproject.toml.

# defaults
[tool.pixi-diff-to-markdown]
merge-dependencies = "no" # or "split-explicit" when there are three or more environments / platforms
hide = false
change-type-column = true
explicit-column = false
package-type-column = false

You can also override the configuration options by passing them as arguments to pixi-diff-to-markdown.

pixi update --json | pixi-diff-to-markdown --merge-dependencies=yes --explicit-column

merge-dependencies

Depending on the amount of environments and platforms you have in your pixi.toml, it might make sense to either merge all dependencies into one table, split them by explicit and implicit dependencies or split them by environment and platform. For a large amount of environments and platforms, it is recommended to merge the dependencies into one table for deduplication. merge-dependencies can be set to one of the following values:

• no: Don't merge the dependencies, each environment will be displayed in their own table. Only recommended for a small amount of environments / platforms (example).
• yes: Merge all dependencies into one table and deduplicate them (example).
• split-explicit: Merge all dependencies into one table and deduplicate them but split the table into one explicit and one implicit table (example).

The default is no when there are less than three environments / platforms and split-explicit when there are three or more environments / platforms.

hide

Whether to hide the tables in a collapsible object (example 1 true, example 2 true, example false)

change-type-column

Whether to enable the Change column in the output (example true, example false).

explicit-column

Whether to enable the Explicit column in the output (example true, example false). If a dependency is explicitly defined in pixi.toml, it will be marked as Explicit. Otherwise, it will be marked as Implicit.

If this is set to false, the Explicit column will be omitted and the explicitly defined dependencies will be marked as cursive.

package-type-column

Whether to enable the Package Type column in the output (example true, example false). This column will show whether the dependency is a conda or pypi package.