Metadata-Version: 2.3
Name: pixi-diff-to-markdown
Version: 0.2.1
Summary: Tool for converting `pixi update` diffs to markdown
Project-URL: repository, https://github.com/pavelzw/pixi-diff-to-markdown
Author-email: Pavel Zwerschke <pavelzw@gmail.com>
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: more-itertools<11,>=10.3.0
Requires-Dist: ordered-enum<0.1,>=0.0.8
Requires-Dist: py-rattler<0.6,>=0.5.0
Requires-Dist: pydantic-settings<3,>=2.2.1
Requires-Dist: pydantic<3,>=2.7.1
Requires-Dist: typer<0.13,>=0.12.3
Description-Content-Type: text/markdown

# 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.

```bash
pixi update --json | pixi-diff-to-markdown > diff.md
```

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`.

```bash
# 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`.

```toml
# defaults
[tool.pixi-diff-to-markdown]
merge-dependencies = "no" # or "yes" 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`.

```bash
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](./tests/resources/diff-example/merge-no_hide-False_change-type-True_explicit-False_package-type-False.md)).
- `yes`: Merge all dependencies into one table and deduplicate them ([example](./tests/resources/diff-polarify/merge-yes_hide-False_change-type-True_explicit-False_package-type-False.md)).
- `split-explicit`: Merge all dependencies into one table and deduplicate them but split the table into one `explicit` and one `implicit` table ([example](./tests/resources/diff-polarify/merge-split-explicit_hide-False_change-type-True_explicit-False_package-type-False.md)).

The default is `no` when there are less than three environments / platforms and `yes` when there are three or more environments / platforms.

### `hide`

Whether to hide the tables in a collapsible object ([example 1 true](./tests/resources/diff-example/merge-no_hide-True_change-type-True_explicit-False_package-type-False.md), [example 2 true](./tests/resources/diff-example/merge-split-explicit_hide-True_change-type-True_explicit-False_package-type-False.md), [example false](./tests/resources/diff-example/merge-no_hide-False_change-type-True_explicit-False_package-type-False.md))

### `change-type-column`

Whether to enable the `Change` column in the output ([example true](./tests/resources/diff-example/merge-yes_hide-False_change-type-True_explicit-False_package-type-False.md), [example false](./tests/resources/diff-example/merge-yes_hide-False_change-type-False_explicit-False_package-type-False.md)).

### `explicit-column`

Whether to enable the `Explicit` column in the output ([example true](./tests/resources/diff-example/merge-yes_hide-False_change-type-True_explicit-True_package-type-False.md), [example false](./tests/resources/diff-example/merge-yes_hide-False_change-type-True_explicit-False_package-type-False.md)).
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](./tests/resources/diff-example/merge-yes_hide-False_change-type-True_explicit-False_package-type-True.md), [example false](./tests/resources/diff-example/merge-yes_hide-False_change-type-True_explicit-False_package-type-False.md)).
This column will show whether the dependency is a `conda` or `pypi` package.
