uv-upsync 2.3.1__tar.gz → 2.4.0__tar.gz

uv_upsync-2.4.0/.github/workflows/ci.yaml

@@ -0,0 +1,45 @@
+# Requires GitHub secrets
+# - CODECOV_TOKEN
+
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups --all-extras
+
+      - name: Run linters
+        run: just lint
+
+      - name: Run tests
+        run: just test
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Run audit
+        run: uv audit

uv_upsync-2.4.0/.github/workflows/demo.yaml

@@ -0,0 +1,38 @@
+name: Demo
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - assets/demo.tape
+      - assets/demo/**
+      - src/**
+
+permissions:
+  contents: write
+
+jobs:
+  vhs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install uv-upsync
+        run: |
+          uv tool install --from . uv-upsync
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Render demo
+        uses: charmbracelet/vhs-action@v2
+        with:
+          path: assets/demo.tape
+
+      - name: Commit demo
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs: regenerate demo gif"
+          file_pattern: assets/demo.gif

uv_upsync-2.4.0/.github/workflows/release.yaml

@@ -0,0 +1,55 @@
+# Requires GitHub secrets
+# - GH_TOKEN
+# - PYPI_TOKEN
+
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version override (leave empty to auto-detect from commits)"
+        required: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --group ci
+
+      - name: Semantic release (auto)
+        if: ${{ !inputs.version }}
+        uses: python-semantic-release/python-semantic-release@v10.5.3
+        with:
+          github_token: ${{ secrets.GH_TOKEN }}
+
+      - name: Semantic release (version override)
+        if: ${{ inputs.version }}
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: uv run semantic-release version --define "version=${{ inputs.version }}"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

uv_upsync-2.3.1/.github/workflows/labels.yaml → uv_upsync-2.4.0/.github/workflows/update-labels.yaml

@@ -1,17 +1,19 @@
 # Requires GitHub secrets
 # - GH_TOKEN
 
-name: Update GitHub Labels
+name: Update Labels
 
 on:
   push:
     branches: ["main"]
     paths:
       - ".github/labels.yaml"
-      - ".github/workflows/labels.yaml"
+      - ".github/workflows/update-labels.yaml"
+  workflow_dispatch:
 
 jobs:
-  labels:
+  update-labels:
+    name: Update Labels
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository

uv_upsync-2.4.0/.pre-commit-hooks.yaml

@@ -0,0 +1,17 @@
+- id: uv-upsync
+  name: uv-upsync
+  description: Upgrade dependency lower bounds in pyproject.toml to the latest versions
+  entry: uv-upsync
+  language: python
+  files: ^pyproject\.toml$
+  pass_filenames: false
+  require_serial: true
+
+- id: uv-upsync-check
+  name: uv-upsync (check)
+  description: Fail if any dependency in pyproject.toml can be upgraded
+  entry: uv-upsync --check
+  language: python
+  files: ^pyproject\.toml$
+  pass_filenames: false
+  require_serial: true

{uv_upsync-2.3.1 → uv_upsync-2.4.0}/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 <!-- version list -->
 
+## v2.4.0 (2026-05-30)
+
+### Bug Fixes
+
+- Replace singleton metaclass with __new__-based singleton
+  ([`53b7737`](https://github.com/pivoshenko/uv-upsync/commit/53b77372e484a3695f5bbac0cb4abfaf58821a39))
+
+- **ci**: Configure ty python-version to match ruff target
+  ([`1cc34f1`](https://github.com/pivoshenko/uv-upsync/commit/1cc34f10645df6885c484aeb844d9cf25defdace))
+
+### Build System
+
+- Bump pytest to 9.0.3 to fix GHSA-6w46-j5rx-g56g
+  ([`4479cf6`](https://github.com/pivoshenko/uv-upsync/commit/4479cf679006e7fd3224221441dc70eb29e41865))
+
+- Drop unused pytest-lazy-fixture (incompatible with pytest 9)
+  ([`fe3176a`](https://github.com/pivoshenko/uv-upsync/commit/fe3176a69c5d86f67324fadd60500e6249dcc3b1))
+
+- Update dev dependencies
+  ([`b0813fa`](https://github.com/pivoshenko/uv-upsync/commit/b0813fa8191f364761833cb5f83c22fad71af146))
+
+- Update dev dependencies
+  ([`5ef0fe5`](https://github.com/pivoshenko/uv-upsync/commit/5ef0fe5b9eb2f7c77a5218c4a979667e7f9a5021))
+
+- Update dev dependencies
+  ([`dd39a19`](https://github.com/pivoshenko/uv-upsync/commit/dd39a191d129b9a712bb674b1b73a5630c997fc7))
+
+- Update dev dependencies
+  ([`dcd9ed7`](https://github.com/pivoshenko/uv-upsync/commit/dcd9ed7c4d66e55b714b00835030d81d9f8554b5))
+
+- Update dev dependencies
+  ([`2b8bb0b`](https://github.com/pivoshenko/uv-upsync/commit/2b8bb0bb732d7d8dd1b478e0db01a6e5055f94bf))
+
+### Chores
+
+- Align pyproject keywords with github repository topics
+  ([`2f420db`](https://github.com/pivoshenko/uv-upsync/commit/2f420db49e3c0c4f4c4c3e8604eef2088026885f))
+
+- Keep dependencies-upgrade and packaging-upgrade keywords
+  ([`9140317`](https://github.com/pivoshenko/uv-upsync/commit/9140317c0bdcf042620338153547d925547d14ac))
+
+### Documentation
+
+- Clearer tagline
+  ([`d445a73`](https://github.com/pivoshenko/uv-upsync/commit/d445a73bf570082606f3ba43100d1ddae170d775))
+
+- Drop manual table of contents in favor of github's built-in
+  ([`aa5c0a6`](https://github.com/pivoshenko/uv-upsync/commit/aa5c0a60fb2c7d27db40de3238a79a5cc452826e))
+
+- Note that examples can be run with uvx without installing
+  ([`a6c20a8`](https://github.com/pivoshenko/uv-upsync/commit/a6c20a8a7ec33e1872c5d4e801953a5a868bc4a7))
+
+- Reorder badges, add table of contents, simplify overview
+  ([`88b5592`](https://github.com/pivoshenko/uv-upsync/commit/88b55923883e530d11827e32243598bc8a85c100))
+
+### Features
+
+- Add --format json/markdown output and expose it from the action
+  ([`618bb44`](https://github.com/pivoshenko/uv-upsync/commit/618bb44faf66554c4dce817f284ba096caf2a7d8))
+
+- Add [tool.uv-upsync] config, pre-commit hook, and GitHub Action
+  ([`9d718a9`](https://github.com/pivoshenko/uv-upsync/commit/9d718a9573cec997bb5826e2ea4c9c4cd747b075))
+
+- Align uv-upsync with the uv ecosystem
+  ([`3557c71`](https://github.com/pivoshenko/uv-upsync/commit/3557c71a9163f35abb57f25d7897ced593bdc888))
+
+- Best-effort resolution that isolates un-lockable upgrades
+  ([`2e5bfc8`](https://github.com/pivoshenko/uv-upsync/commit/2e5bfc8a68b1708c1339dfb08f88ead5f0fada72))
+
+- Render failures as uv-style errors instead of tracebacks
+  ([`7ad19d6`](https://github.com/pivoshenko/uv-upsync/commit/7ad19d6f07762385b5b8f834cd1e7623eb0e42fa))
+
+- Resolver-aware --resolve, conflict naming, and a VHS demo
+  ([`07ad6fd`](https://github.com/pivoshenko/uv-upsync/commit/07ad6fd3600d3836a4b484e7422de221eb2a9d31))
+
+- Support compound ranges, --max-bump, and --prerelease
+  ([`973e8fa`](https://github.com/pivoshenko/uv-upsync/commit/973e8fa351d743a7dd9c1d577fdd5dc835789445))
+
+
+## v2.3.2 (2026-03-29)
+
+### Chores
+
+- Remove deprecated GitHub workflows and files
+  ([`9f2f579`](https://github.com/pivoshenko/uv-upsync/commit/9f2f5795469ac2535bdaf12c938950588184a174))
+
+### Documentation
+
+- Remove TOC
+  ([`91548dc`](https://github.com/pivoshenko/uv-upsync/commit/91548dc7d012087d2640ea6f7c6f68fcc294a160))
+
+
 ## v2.3.1 (2026-03-29)
 
 ### Build System

uv_upsync-2.4.0/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+uv-upsync is a CLI tool for automated dependency updates and version bumping in `pyproject.toml` files. Think of it as `uv lock --upgrade` for the human-authored version specifiers: it raises the lower bounds in `pyproject.toml` to the latest published versions, then re-locks with `uv`. It is designed to feel native to the uv ecosystem — uv-style flags, output, and a `uv lock` round-trip with rollback on failure. Built with Click, httpx, tomlkit, and packaging.
+
+## Commands
+
+All commands use `uv run` (no virtual env activation needed). Task runner: `just`.
+
+```bash
+just format          # pyupgrade + ruff format
+just lint            # ty check + ruff check
+just test            # pytest with coverage
+just update          # uv lock --upgrade + uv-upsync
+
+uv run pytest tests/test_parsers.py              # single test file
+uv run pytest tests/test_parsers.py::test_name   # single test
+uv run ruff check --no-fix .                     # lint without auto-fix
+uv run ty check .                                # type check
+```
+
+## Architecture
+
+Entry point: `uv_upsync.__main__:main` (Click CLI).
+
+Source in `src/uv_upsync/` with clear separation:
+
+- **`__main__.py`** — uv-style Click CLI and orchestration. Resolves the target pyproject, collects upgradable package names across the selected groups, fetches latest versions concurrently, plans updates, then locks. Default is **best-effort**: try the full set, and on a lock failure keep the maximal subset that resolves (greedy), naming the conflicting peer (via `find_conflicts`) for held-back packages. `--resolve` bisects a held-back dependency's versions for the latest that locks; `--strict` rolls back everything and exits 2; `--no-lock` writes without locking. Supports `--check` (CI gate) and `--dry-run`
+- **`parsers.py`** — TOML iteration and version-bumping logic. Parses specifiers with `packaging` (`Requirement`/`Specifier`), not regex. `upgradable_specifier` returns the single raisable lower-bound clause plus a residual `SpecifierSet` (caps/exclusions), so compound ranges like `>=1.2,<2.0` are supported. `select_new_version` picks the highest version that beats the floor, satisfies the residual, and respects `--prerelease`/`--max-bump`. `plan_updates` computes a list of `Update`s (group label, index, new text) without mutating; `apply_updates` returns a deep-copied document with a chosen subset applied. Handles `project.dependencies`, `project.optional-dependencies`, `dependency-groups` (PEP 735). Only raises lower bounds (`>=`, `>`, `~=`); pinned (`==`) requirements are never touched. `_replace_version` rewrites only the version token, preserving formatting, extras and markers. Inline tables (e.g. `include-group`) are ignored
+- **`pypi.py`** — `PyPIClient` querying the PEP 691 simple JSON API (`Accept: application/vnd.pypi.simple.v1+json`). Index-aware: `index_url_from_pyproject` reads `[[tool.uv.index]]` / `tool.uv.index-url`. Fetches concurrently (thread pool), caches in memory, supports `--offline`/`--no-cache`. Picks the highest stable version via `packaging.version`
+- **`report.py`** — Renders the applied/held-back updates as JSON or Markdown for `--format` (text output is handled by the logger). The GitHub Action exposes the Markdown as a `summary` output for PR bodies
+- **`uv.py`** — Subprocess wrapper for `uv lock` (accepts `cwd` and `--offline`)
+- **`config.py`** — Reads `[tool.uv-upsync]` from pyproject (`exclude`, `group`, `upgrade-package`, `all-groups`, `index-url`) with validation. CLI args take precedence over config, which takes precedence over defaults
+- **`commands.py`** — Custom Click command/formatter classes; help mirrors uv's clap layout (bold headers, cyan flags)
+- **`logging.py`** — Singleton logger with uv-style output: `status` (green verb), `update` (`Updated <name> v<old> -> v<new>`), `warning:`/`error:` prefixes to stderr (with dimmed `Caused by:` chains), verbose-only `skip`. Honors `--quiet`/`--verbose`/`--color`
+- **`exceptions.py`** — `BaseError` and `UVCommandError`
+
+The entry point (`main`) wraps the Click command so failures render as `error:` lines (never tracebacks). Repo root also ships `.pre-commit-hooks.yaml` and a composite `action.yml`.
+
+## Code Conventions
+
+- `from __future__ import annotations` required in every file (enforced by ruff isort)
+- Python 3.13 target for ruff; requires-python >= 3.10
+- All ruff lint rules enabled (`select = ["ALL"]`), specific ignores in pyproject.toml
+- Line length: 100
+- Double quotes, single-line imports, imports sorted by length
+- Type annotations throughout; type checker is `ty` (not mypy)
+- Coverage target: 95% (`__main__.py` and `__init__.py` are omitted from coverage)
+- Run the test suite with all dependency groups installed (e.g. `uv run --all-groups pytest`) so `pytest-cov` is available
+
+## Commit Convention
+
+Conventional Commits: `type(scope): description`
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`, `style`, `revert`. Semantic-release uses these for automatic versioning (`feat` = major, `fix`/`perf`/`refactor` = minor, `docs`/`style` = patch).

uv_upsync-2.4.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: uv-upsync
+Version: 2.4.0
+Summary: uv-upsync - is a tool for automated dependency updates and version bumping in pyproject.toml.
+Project-URL: Homepage, https://github.com/pivoshenko/uv-upsync
+Project-URL: Repository, https://github.com/pivoshenko/uv-upsync
+Author-email: Volodymyr Pivoshenko <contact@pivoshenko.dev>
+Maintainer-email: Volodymyr Pivoshenko <contact@pivoshenko.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependencies,dependencies-management,dependencies-update,dependencies-upgrade,hacktoberfest,packaging,packaging-management,packaging-update,packaging-upgrade,pypi,python,uv,uv-plugin,uv-plugins,uv-tool
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Other Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: click~=8.1.8
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: packaging~=26.2
+Requires-Dist: tomlkit~=0.13.3
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img alt="logo" src="https://github.com/pivoshenko/uv-upsync/blob/main/assets/logo.svg?raw=True" height=200>
+</div>
+
+<br>
+
+<p align="center">
+  <a href="https://pypi.org/project/uv-upsync">
+    <img alt="PyPI" src="https://img.shields.io/pypi/v/uv-upsync?style=flat-square&logo=pypi&logoColor=white&color=4856CD&label=PyPI">
+  </a>
+  <a href="https://pypi.org/project/uv-upsync">
+    <img alt="Python" src="https://img.shields.io/pypi/pyversions/uv-upsync?style=flat-square&logo=python&logoColor=white&color=4856CD&label=Python">
+  </a>
+  <a href="https://github.com/astral-sh/uv">
+    <img alt="uv" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=flat-square&label=uv">
+  </a>
+  <a href="https://docs.astral.sh/ruff">
+    <img alt="Ruff" src="https://img.shields.io/badge/Style-ruff-black.svg?style=flat-square&logo=ruff&logoColor=white&color=D7FF64">
+  </a>
+  <a href="https://github.com/pivoshenko/uv-upsync/actions/workflows/ci.yaml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/pivoshenko/uv-upsync/ci.yaml?label=CI&style=flat-square&logo=githubactions&logoColor=white&color=0A6847">
+  </a>
+  <a href="https://codecov.io/gh/pivoshenko/uv-upsync">
+    <img alt="Coverage" src="https://img.shields.io/codecov/c/gh/pivoshenko/uv-upsync?token=cqRQxVnDR6&style=flat-square&logo=codecov&logoColor=white&color=0A6847&label=Coverage">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img alt="License" src="https://img.shields.io/pypi/l/uv-upsync?style=flat-square&logo=opensourceinitiative&logoColor=white&color=0A6847&label=License">
+  </a>
+  <a href="https://stand-with-ukraine.pp.ua">
+    <img alt="StandWithUkraine" src="https://img.shields.io/badge/Support-Ukraine-FFC93C?style=flat-square&labelColor=07689F">
+  </a>
+</p>
+
+<p align="center">
+  <em>Automated dependency upgrades for <code>pyproject.toml</code>, native to uv.</em>
+</p>
+
+<div align="center">
+  <img alt="demo" src="https://github.com/pivoshenko/uv-upsync/blob/main/assets/demo.gif?raw=true">
+</div>
+
+## Overview
+
+`uv-upsync` is a [uv]-native tool for automated dependency updates and version
+bumping in `pyproject.toml`.
+
+`uv lock --upgrade` refreshes your **lockfile** but leaves the lower bounds in
+`pyproject.toml` untouched, so `httpx>=0.24.0` stays `>=0.24.0` forever.
+`uv-upsync` raises those human-authored bounds to the latest published version,
+re-locks with `uv`, and rolls back if the resolution fails — all while
+preserving your formatting, comments, operators, extras and environment markers.
+
+[uv]: https://github.com/astral-sh/uv
+
+### Features
+
+- **Built for the uv ecosystem** — familiar flags (`--project`, `--upgrade-package`,
+  `--all-groups`, `--offline`, `--no-cache`, `--color`), uv-style output and a
+  `uv lock` round-trip with automatic rollback on failure
+- **Index-aware** — resolves versions from the [PEP 691] index configured for
+  your project via `[[tool.uv.index]]`, so private indexes work out of the box
+- **Correct by construction** — specifiers are parsed with [`packaging`], the
+  canonical PEP 440/508 implementation, not regular expressions
+- **Conservative** — only raises lower bounds (`>=`, `>`, `~=`); pinned (`==`)
+  requirements are never touched
+- **Range-aware** — compound specifiers like `>=1.2,<2.0` have their floor raised
+  to the latest version that still satisfies the cap (`<2.0`) and any exclusions (`!=`)
+- **Controlled** — `--max-bump patch|minor|major` holds back larger jumps (auto-apply
+  minors, review majors), and `--prerelease` opts into pre-release versions
+- **Format-preserving** — only the version token is rewritten; everything else,
+  including comments and markers, is kept verbatim
+- **Fast** — version lookups are fetched concurrently and cached
+- **Selective** — target specific groups or packages, or exclude packages
+- **Configurable** — persist defaults in a `[tool.uv-upsync]` table, overridable per run
+- **Resilient** — by default an upgrade that does not resolve is held back individually instead of failing the whole run (`--strict` to opt out)
+- **Safe** — `--dry-run` to preview and `--check` for CI
+- **Scriptable** — `--format json` for tooling and `--format markdown` for pull request bodies
+- **Integrated** — ships a [pre-commit] hook and a GitHub Action
+
+## Installation
+
+Run it without installing:
+
+```shell
+uvx uv-upsync
+```
+
+Or add it to your development dependencies:
+
+```shell
+uv add --dev uv-upsync
+```
+
+## Usage
+
+> The examples below assume `uv-upsync` is installed. If it isn't, prefix any
+> command with `uvx` to run it without installing (e.g. `uvx uv-upsync --dry-run`).
+
+By default, `uv-upsync` upgrades every dependency in the `pyproject.toml` found
+in the current directory:
+
+```shell
+$ uv-upsync
+Updated click v8.1.8 -> v8.2.1
+Updated httpx v0.27.0 -> v0.28.1
+Resolved 12 packages in 184ms
+Updated 2 dependencies in pyproject.toml
+Locked dependencies
+```
+
+Nothing to do is reported the way uv reports it:
+
+```shell
+$ uv-upsync
+Resolved 12 packages in 121ms
+Audited 12 dependencies, all up to date
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--project <DIR>` | Path to the project directory containing the `pyproject.toml` |
+| `--directory <DIR>` | Change to `DIR` before running |
+| `-P`, `--upgrade-package <PKG>` | Allow upgrades for only the given package(s) |
+| `--exclude <PKG>` | Package(s) to exclude from upgrading |
+| `--group <NAME>` | Upgrade dependencies in the given group(s) only |
+| `--all-groups` | Upgrade dependencies in all groups |
+| `--max-bump <level>` | Limit upgrades to at most `patch`, `minor`, or `major` |
+| `--prerelease` | Allow upgrading to pre-release versions |
+| `--index-url <URL>` | Base URL of the [PEP 691] package index (defaults to the project's uv index or PyPI) |
+| `--offline` | Disable network access, using only cached data |
+| `-n`, `--no-cache` | Avoid reading from or writing to the cache |
+| `--dry-run` | Preview the upgrades without writing to `pyproject.toml` |
+| `--check` | Exit with a non-zero status if any upgrades are available |
+| `--strict` | Roll back every upgrade and fail if the result does not lock |
+| `--no-lock` | Write the upgrades without running `uv lock` |
+| `--resolve` | When an upgrade does not lock, bump to the latest version that does |
+| `-q`, `--quiet` | Use quiet output |
+| `-v`, `--verbose` | Use verbose output (shows skipped dependencies) |
+| `--format <text\|json\|markdown>` | Output format for the upgrade summary |
+| `--color <auto\|always\|never>` | Control the use of color in output |
+| `-V`, `--version` | Show the version and exit |
+
+`uv-upsync` understands all three dependency tables: `project.dependencies`,
+`project.optional-dependencies`, and `dependency-groups` ([PEP 735]).
+
+### Resolution
+
+After bumping the specifiers, `uv-upsync` re-locks with `uv`. If the combined
+upgrade does not resolve, the default **best-effort** mode keeps the largest
+subset of upgrades that locks and reports which ones were held back (naming the
+conflicting dependency when it can) — so a single incompatible dependency never
+costs you the rest:
+
+```console
+$ uv-upsync
+Resolved 2 packages in 153ms
+Updated idna v2.0 -> v3.17
+Updated 1 dependency in pyproject.toml
+warning: Held back docutils v0.16 -> v0.23 (conflicts with sphinx)
+Locked dependencies
+```
+
+With `--resolve`, an upgrade that does not lock at its latest version is bisected
+for the **latest version that does**, instead of being held back entirely:
+
+```console
+$ uv-upsync --resolve
+Updated idna v2.0 -> v3.17
+Updated numpy v1.20 -> v2.0.2   # 2.4.6 needs a newer Python; 2.0.2 is the latest that fits
+Updated 2 dependencies in pyproject.toml
+Locked dependencies
+```
+
+Use `--strict` to instead roll back every upgrade and fail (exit code `2`) if the
+result does not lock, or `--no-lock` to write the upgrades and skip locking
+entirely.
+
+## Configuration
+
+`uv-upsync` reads defaults from a `[tool.uv-upsync]` table in your
+`pyproject.toml`, so you don't have to repeat them on every run:
+
+```toml
+[tool.uv-upsync]
+exclude = ["click", "ruff"]               # never upgrade these packages
+group = ["project", "test"]               # only these groups (omit for all)
+upgrade-package = ["httpx"]               # only these packages
+all-groups = true                         # upgrade every group
+max-bump = "minor"                        # hold back major upgrades
+prerelease = false                        # allow pre-release versions
+resolve = false                           # bisect for the latest version that locks
+index-url = "https://example.com/simple"  # PEP 691 index to query
+```
+
+Settings are resolved with the precedence **command line > `[tool.uv-upsync]` >
+defaults**: passing a flag always overrides the matching setting. The index is
+resolved as `--index-url` > `[tool.uv-upsync].index-url` > `[[tool.uv.index]]` >
+PyPI.
+
+## Examples
+
+### Preview the upgrades
+
+```shell
+uv-upsync --dry-run
+```
+
+### Upgrade a single package
+
+```shell
+uv-upsync --upgrade-package httpx
+```
+
+### Exclude packages
+
+```shell
+uv-upsync --exclude click --exclude ruff
+```
+
+### Upgrade specific groups
+
+```shell
+# Only the project dependencies
+uv-upsync --group project
+
+# A couple of named groups
+uv-upsync --group test --group docs
+```
+
+### Fail CI when dependencies are stale
+
+```shell
+uv-upsync --check
+```
+
+`--check` writes nothing and exits with a non-zero status when upgrades are
+available, which makes it easy to wire into a scheduled job or pre-merge gate.
+
+## Pre-commit
+
+Add `uv-upsync` to your [pre-commit] configuration:
+
+```yaml
+repos:
+  - repo: https://github.com/pivoshenko/uv-upsync
+    rev: v2.3.2
+    hooks:
+      - id: uv-upsync
+```
+
+Two hooks are available:
+
+- **`uv-upsync`** — upgrade the bounds in `pyproject.toml` and re-lock (runs
+  `uv lock`, so `uv` must be on your `PATH`)
+- **`uv-upsync-check`** — fail the commit if any dependency can be upgraded,
+  without writing changes
+
+## GitHub Action
+
+Keep dependencies fresh on a schedule and open a pull request with the results:
+
+```yaml
+name: upgrade-dependencies
+on:
+  schedule:
+    - cron: "0 6 * * 1" # every Monday
+  workflow_dispatch:
+
+jobs:
+  upsync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: upsync
+        uses: pivoshenko/uv-upsync@v2.3.2
+        with:
+          args: --all-groups --format markdown
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "build: upgrade dependencies"
+          title: "build: upgrade dependencies"
+          body: ${{ steps.upsync.outputs.summary }}
+          branch: build/uv-upsync
+```
+
+With `--format markdown` the action's `summary` output is a ready-made pull
+request body (`⬆️ click 8.1.8 → 8.2.1 …`). To gate pull requests instead, run
+the action with `args: --check` and drop the pull request step.
+
+| Input | Description | Default |
+| --- | --- | --- |
+| `args` | Additional arguments passed to `uv-upsync` | `""` |
+| `version` | Version of `uv-upsync` to run | latest |
+| `working-directory` | Directory to run in | `.` |
+
+| Output | Description |
+| --- | --- |
+| `summary` | The upgrade summary printed by `uv-upsync` |
+
+[PEP 691]: https://peps.python.org/pep-0691
+[PEP 735]: https://peps.python.org/pep-0735
+[`packaging`]: https://packaging.pypa.io
+[pre-commit]: https://pre-commit.com