Metadata-Version: 2.4
Name: composefmt
Version: 0.3.1
Summary: A Python tool for formatting Docker Compose YAML files
Author-email: Sebastian Mark <smark+pypi@posteo.net>
License-Expression: CC-BY-SA-4.0
Project-URL: Homepage, https://git.smsvc.net/docker/composefmt
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: ruamel-yaml>=0.19.1

# composefmt

A Python tool for formatting Docker Compose YAML files.
It reorders top-level and service-level keys in a consistent,
predefined order while preserving comments, quotes, and structure.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Features](#features)
- [Requirements](#requirements)
- [Setup](#setup)
  - [Installation (Optional)](#installation-optional)
  - [Configuration (Optional)](#configuration-optional)
- [Usage (multiple ways)](#usage-multiple-ways)
- [Testing](#testing)
- [Exit Codes](#exit-codes)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Features

- Reorders top-level and service-level keys in Docker Compose files
- Configure key orders and YAML indentation via a TOML config file
- Preserves comments, quotes, and YAML structure
- Supports files (glob patterns) and stdin piping
- Outputs formatted content to stdout or overwrites files in-place
- Check-mode for verify formatting without modifying files

## Requirements

- Python 3.13+
- uv (for dependency management and installation)

For a full list of Python dependencies, see `uv tree` or check `pyproject.toml`.

## Setup

```bash
git clone <repository-url>
cd composefmt
uv sync
```

### Installation (Optional)

Install `composefmt` as a global tool:

```bash
uv tool install .
# or
uv tool install git+https://git.smsvc.net/docker/composefmt.git
```

### Configuration (Optional)

Create a config file at `$XDG_CONFIG_HOME/composefmt.toml` to customize key
orders and YAML indentation.  
This is optional: If no configuration file exists or config options are
omitted, the builtin defaults will be used (see `src/composefmt/lib/defaults.py`).  
YAML keys that are not defined in the configuration will be appended in existing order.  

```toml
# Custom top-level order
top_level_order = [
    "name",
    "services",
    "networks",
    "volumes",
]

# Custom service-level order
service_order = [
    "image",
    "build",
    "ports",
    "volumes",
    "environment",
]

# Custom YAML indentation
yaml_indent = 4
```

## Usage (multiple ways)

```bash
# Format files and overwrite in-place
./src/composefmt/cli.py docker-compose.yml

# Format files and output to stdout
uv run composefmt docker-compose.yml --stdout

# Check if files are formatted (without modifying them)
composefmt docker-compose.yml --check

# Read from stdin (e.g., for piping)
cat docker-compose.yml | composefmt
```

see `--help` for further details

## Testing

All tests are defined in `./tests/` and can be run via `pytest`.

## Exit Codes

Exit codes are only relevant in check mode (`--check`).  
In all other modes, the script exits with `0`.

| Code | Meaning                           |
| :-:  | :-------------------------------- |
| 0    | No files would be changed         |
| 1    | One or more files need formatting |
