ruff-sync 0.0.5.dev2__tar.gz → 0.1.0.dev0__tar.gz

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev0}/.github/workflows/ci.yaml

@@ -66,8 +66,10 @@ jobs:
 
   pre-publish:
     name: Test package installation
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: [static-analysis, tests]
+    if: >-
+      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'pull_request' && github.event.pull_request.draft == false)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -80,14 +82,29 @@ jobs:
         run: uv python install 3.10
 
       - name: Build package
-        run: uv build
+        run: |
+          echo "Building ruff-sync package..."
+          uv build
 
-      - name: Install and test packaged program
+      - name: Install packaged program
         run: |
+          echo "Installing built wheel..."
           uv tool install $(ls dist/*.whl)
-          ruff-sync --version
+          echo "Version: $(ruff-sync --version)"
+
+      - name: Test package installation (Pull)
+        run: |
+          echo "Testing ruff-sync pull against Kilo59/ruff-sync..."
           ruff-sync https://github.com/Kilo59/ruff-sync
+
+      - name: Test package installation (Check)
+        run: |
+          echo "Testing ruff-sync check against Kilo59/ruff-sync..."
           ruff-sync check https://github.com/Kilo59/ruff-sync
+
+      - name: Verify semantic check failure
+        run: |
+          echo "Verifying that --semantic check fails for kitchen-sink config (expected failure)..."
           ! ruff-sync check --semantic https://github.com/Kilo59/ruff-sync --path configs/kitchen-sink
 
   publish:

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev0}/.github/workflows/complexity.yaml

@@ -28,11 +28,10 @@ jobs:
           DIFF=$(wily diff ruff_sync.py tasks.py tests/ --no-detail -r origin/${{ github.event.pull_request.base.ref }})
           echo "$DIFF"
 
-          # Build multine output
-          DIFF="${DIFF//'%'/'%25'}"
-          DIFF="${DIFF//$'\n'/'%0A'}"
-          DIFF="${DIFF//$'\r'/'%0D'}"
-          echo "diff=$DIFF" >> "$GITHUB_OUTPUT"
+          # Build multiline output
+          echo "diff<<DIFF_EOF" >> "$GITHUB_OUTPUT"
+          echo "$DIFF" >> "$GITHUB_OUTPUT"
+          echo "DIFF_EOF" >> "$GITHUB_OUTPUT"
       - name: Add Wily PR Comment
         uses: marocchino/sticky-pull-request-comment@v2
         if: github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.number && steps.wily.outputs.diff != ''

ruff_sync-0.1.0.dev0/.github/workflows/docs.yaml

@@ -0,0 +1,32 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --group docs
+
+      - name: Build and deploy documentation
+        run: uv run mkdocs gh-deploy --force

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev0}/AGENTS.md

@@ -5,7 +5,7 @@
 **ruff-sync** is a CLI tool that synchronizes [Ruff](https://docs.astral.sh/ruff/) linter configuration across multiple Python projects. It downloads an upstream `pyproject.toml`, extracts the `[tool.ruff]` section, and merges it into a local project's `pyproject.toml` while preserving formatting, comments, and whitespace.
 
 - **GitHub Repository**: [`Kilo59/ruff-sync`](https://github.com/Kilo59/ruff-sync)
-- The entire application lives in a single module: `ruff_sync.py`.
+- The application uses a `src` layout in `src/ruff_sync/`.
 - Dev tasks are defined in `tasks.py` using [Invoke](https://www.pyinvoke.org/).
 
 ## GitHub Context
@@ -54,11 +54,14 @@ gh label list                           # See available labels
 
 ## Project Structure
 
-```
+```text
 .agents/               # Agent-specific instructions (Deep Standards)
   TESTING.md           # Mandatory testing patterns and rules
   workflows/           # Step-by-step guides for common tasks
-ruff_sync.py           # The entire application — CLI, merging logic, HTTP
+src/ruff_sync/         # The application source
+  __init__.py          # Public API
+  cli.py               # CLI, merging logic, HTTP
+  __main__.py          # -m support
 tasks.py               # Invoke tasks: lint, fmt, type-check, deps, new-case
 pyproject.toml         # Project config, dependencies, ruff/mypy settings
 tests/
@@ -114,7 +117,7 @@ uv run mypy .
 ```
 
 - mypy is configured in strict mode with `python_version = "3.10"`.
-- It checks `ruff_sync.py`, `tests/`, and `tasks.py`.
+- It checks `src/`, `tests/`, and `tasks.py`.
 - Tests have relaxed rules: `type-arg` and `no-untyped-def` are disabled for `tests.*`.
 - `tomlkit` returns complex union types — use `cast(Any, ...)` in tests when indexing parsed TOML documents to satisfy mypy without verbose type narrowing.
 
@@ -130,7 +133,7 @@ Or with coverage:
 uv run coverage run -m pytest -vv
 ```
 
-- Coverage is tracked for `ruff_sync.py` only.
+- Coverage is tracked for `src/ruff_sync/` only.
 - Tests use `respx` to mock HTTP calls and `pyfakefs` for filesystem mocking.
 - `pytest-asyncio` is in **strict** mode — async tests need the `@pytest.mark.asyncio` decorator.
 
@@ -165,13 +168,13 @@ uv run coverage run -m pytest -vv
 
 Defined in `tasks.py`. **ALWAYS** run these through uv: `uv run invoke <task>`
 
-| Task         | Alias        | Description                         |
-| ------------ | ------------ | ----------------------------------- |
-| `lint`       |              | Lint with ruff (auto-fixes by default) |
-| `fmt`        |              | Format with ruff format             |
-| `type-check` | `types`      | Type-check with mypy                |
-| `deps`       | `sync`       | Sync dependencies with uv           |
-| `new-case`   | `new-lifecycle-tomls` | Scaffold lifecycle TOML fixtures (See [Workflow](.agents/workflows/add-test-case.md)) |
+| Task         | Alias                 | Description                            |
+| ------------ | --------------------- | -------------------------------------- |
+| `lint`       |                       | Lint with ruff (auto-fixes by default) |
+| `fmt`        |                       | Format with ruff format                |
+| `type-check` | `types`               | Type-check with mypy                   |
+| `deps`       | `sync`                | Sync dependencies with uv              |
+| `new-case`   | `new-lifecycle-tomls` | Scaffold lifecycle TOML fixtures       |
 
 ## CI
 

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.0.5.dev2
+Version: 0.1.0.dev0
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
 Project-URL: Documentation, https://github.com/Kilo59/ruff-sync#readme
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-### Table of Contents
+## Table of Contents
 
 - [The Problem](#the-problem)
 - [How It Works](#how-it-works)
@@ -102,9 +102,9 @@ Ruff's `extend` is perfect inside a monorepo, but if your projects live in **sep
 └─────────────────────────────┘
 ```
 
-1. You point `ruff-sync` at the URL of your canonical `pyproject.toml`.
-2. It downloads the file, extracts the `[tool.ruff]` section.
-3. It **merges** the upstream config into your local `pyproject.toml` — updating values that changed, adding new rules, but preserving your local comments, whitespace, and any sections you've chosen to exclude (like `per-file-ignores`).
+1. You point `ruff-sync` at the URL of your canonical configuration (repository, directory, or direct file).
+2. It downloads the file and extracts the configuration (from `[tool.ruff]` in `pyproject.toml` or the top-level in `ruff.toml`).
+3. It **merges** the upstream config into your local project — updating values that changed, adding new rules, but preserving your local comments, whitespace, and any sections you've chosen to exclude (like `per-file-ignores`).
 
 No package registry. No publishing step. Just a URL.
 
@@ -133,8 +133,9 @@ pip install ruff-sync
 ### Usage
 
 ```console
-# Sync from a GitHub/GitLab repository (defaults to main/pyproject.toml)
+# Sync from a GitHub/GitLab repository (root or specific directory)
 ruff-sync https://github.com/my-org/standards
+ruff-sync https://github.com/my-org/standards/tree/main/configs/shared
 
 # Or a direct blob/file URL (auto-converts to raw)
 ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
@@ -162,7 +163,8 @@ Run `ruff-sync --help` for full details on all available options.
 ## Key Features
 
 - 🏗️ **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
-- 🌐 **GitHub & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs or blob URLs to raw content URLs.
+- 🌐 **GitHub & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs, tree (directory) URLs, or blob (file) URLs to raw content URLs.
+- 🔍 **Smart configuration discovery** — Point at a directory and `ruff-sync` will automatically find your config. It checks `pyproject.toml`, `ruff.toml`, and `.ruff.toml` (in that order).
 - 📥 **Git clone support** — If the URL starts with `git@` or uses the `ssh://`, `git://`, or `git+ssh://` schemes, `ruff-sync` will perform an efficient shallow clone (using `--filter=blob:none` and `--no-checkout`) to safely extract the configuration with minimal network traffic.
 - 🛡️ **Selective exclusions** — Keep project-specific overrides (like `per-file-ignores` or `target-version`) from being clobbered by the upstream config.
 - 🌍 **Works with any host** — GitHub, GitLab, Bitbucket, private SSH servers, or any raw URL that serves a `pyproject.toml` or `ruff.toml`.
@@ -267,18 +269,46 @@ git commit -am "sync ruff config from upstream"
 
 While `ruff-sync` is designed to sync from _any_ repository or URL of your choosing, this repository also provides a few curated configurations in the [`configs/`](./configs/) directory that you can use directly.
 
-For example, to sync an exhaustive "kitchen-sink" configuration that explicitly enables all rules and documents them:
+`ruff-sync` is flexible with URLs. You can point it at a repository root, a specific directory (tree), a direct file (blob), or even a raw content URL.
+
+#### Kitchen Sink
+
+An exhaustive configuration that explicitly enables and documents almost all available Ruff rules. Great for establishing a strict baseline.
 
 ```console
+# Directory URL (recommended)
+ruff-sync https://github.com/Kilo59/ruff-sync/tree/main/configs/kitchen-sink
+
+# Direct file URL (blob)
 ruff-sync https://github.com/Kilo59/ruff-sync/blob/main/configs/kitchen-sink/ruff.toml
+
+# Raw content URL
+ruff-sync https://raw.githubusercontent.com/Kilo59/ruff-sync/main/configs/kitchen-sink/ruff.toml
+
+# Git SSH URL (clones the repo)
+ruff-sync git@github.com:Kilo59/ruff-sync.git --path configs/kitchen-sink
+```
+
+#### FastAPI & Async
+
+Tailored for modern web applications. Includes rules for `asyncio`, security (`flake8-bandit`), and Pydantic-friendly naming conventions.
+
+```console
+# Repository Root (if the config is at the root)
+ruff-sync https://github.com/my-org/fastapi-standards
+
+# Directory URL
+ruff-sync https://github.com/Kilo59/ruff-sync/tree/main/configs/fastapi
 ```
 
-Or configure it using `pyproject.toml` so it's always the default for your local project:
+#### Default Syncing
+
+Set your preferred standard as the default in your `pyproject.toml`:
 
 ```toml
 [tool.ruff-sync]
 upstream = "https://github.com/Kilo59/ruff-sync"
-path = "configs/kitchen-sink"
+path = "configs/fastapi"
 ```
 
 ## Bootstrapping a New Project

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev0}/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-### Table of Contents
+## Table of Contents
 
 - [The Problem](#the-problem)
 - [How It Works](#how-it-works)
@@ -71,9 +71,9 @@ Ruff's `extend` is perfect inside a monorepo, but if your projects live in **sep
 └─────────────────────────────┘
 ```
 
-1. You point `ruff-sync` at the URL of your canonical `pyproject.toml`.
-2. It downloads the file, extracts the `[tool.ruff]` section.
-3. It **merges** the upstream config into your local `pyproject.toml` — updating values that changed, adding new rules, but preserving your local comments, whitespace, and any sections you've chosen to exclude (like `per-file-ignores`).
+1. You point `ruff-sync` at the URL of your canonical configuration (repository, directory, or direct file).
+2. It downloads the file and extracts the configuration (from `[tool.ruff]` in `pyproject.toml` or the top-level in `ruff.toml`).
+3. It **merges** the upstream config into your local project — updating values that changed, adding new rules, but preserving your local comments, whitespace, and any sections you've chosen to exclude (like `per-file-ignores`).
 
 No package registry. No publishing step. Just a URL.
 
@@ -102,8 +102,9 @@ pip install ruff-sync
 ### Usage
 
 ```console
-# Sync from a GitHub/GitLab repository (defaults to main/pyproject.toml)
+# Sync from a GitHub/GitLab repository (root or specific directory)
 ruff-sync https://github.com/my-org/standards
+ruff-sync https://github.com/my-org/standards/tree/main/configs/shared
 
 # Or a direct blob/file URL (auto-converts to raw)
 ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
@@ -131,7 +132,8 @@ Run `ruff-sync --help` for full details on all available options.
 ## Key Features
 
 - 🏗️ **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
-- 🌐 **GitHub & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs or blob URLs to raw content URLs.
+- 🌐 **GitHub & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs, tree (directory) URLs, or blob (file) URLs to raw content URLs.
+- 🔍 **Smart configuration discovery** — Point at a directory and `ruff-sync` will automatically find your config. It checks `pyproject.toml`, `ruff.toml`, and `.ruff.toml` (in that order).
 - 📥 **Git clone support** — If the URL starts with `git@` or uses the `ssh://`, `git://`, or `git+ssh://` schemes, `ruff-sync` will perform an efficient shallow clone (using `--filter=blob:none` and `--no-checkout`) to safely extract the configuration with minimal network traffic.
 - 🛡️ **Selective exclusions** — Keep project-specific overrides (like `per-file-ignores` or `target-version`) from being clobbered by the upstream config.
 - 🌍 **Works with any host** — GitHub, GitLab, Bitbucket, private SSH servers, or any raw URL that serves a `pyproject.toml` or `ruff.toml`.
@@ -236,18 +238,46 @@ git commit -am "sync ruff config from upstream"
 
 While `ruff-sync` is designed to sync from _any_ repository or URL of your choosing, this repository also provides a few curated configurations in the [`configs/`](./configs/) directory that you can use directly.
 
-For example, to sync an exhaustive "kitchen-sink" configuration that explicitly enables all rules and documents them:
+`ruff-sync` is flexible with URLs. You can point it at a repository root, a specific directory (tree), a direct file (blob), or even a raw content URL.
+
+#### Kitchen Sink
+
+An exhaustive configuration that explicitly enables and documents almost all available Ruff rules. Great for establishing a strict baseline.
 
 ```console
+# Directory URL (recommended)
+ruff-sync https://github.com/Kilo59/ruff-sync/tree/main/configs/kitchen-sink
+
+# Direct file URL (blob)
 ruff-sync https://github.com/Kilo59/ruff-sync/blob/main/configs/kitchen-sink/ruff.toml
+
+# Raw content URL
+ruff-sync https://raw.githubusercontent.com/Kilo59/ruff-sync/main/configs/kitchen-sink/ruff.toml
+
+# Git SSH URL (clones the repo)
+ruff-sync git@github.com:Kilo59/ruff-sync.git --path configs/kitchen-sink
+```
+
+#### FastAPI & Async
+
+Tailored for modern web applications. Includes rules for `asyncio`, security (`flake8-bandit`), and Pydantic-friendly naming conventions.
+
+```console
+# Repository Root (if the config is at the root)
+ruff-sync https://github.com/my-org/fastapi-standards
+
+# Directory URL
+ruff-sync https://github.com/Kilo59/ruff-sync/tree/main/configs/fastapi
 ```
 
-Or configure it using `pyproject.toml` so it's always the default for your local project:
+#### Default Syncing
+
+Set your preferred standard as the default in your `pyproject.toml`:
 
 ```toml
 [tool.ruff-sync]
 upstream = "https://github.com/Kilo59/ruff-sync"
-path = "configs/kitchen-sink"
+path = "configs/fastapi"
 ```
 
 ## Bootstrapping a New Project

ruff_sync-0.1.0.dev0/docs/ci-integration.md

@@ -0,0 +1,59 @@
+# CI Integration
+
+`ruff-sync` is designed to be run in CI pipelines to ensure that all repositories in an organization stay in sync with the central standards.
+
+## Usage in CI
+
+The best way to use `ruff-sync` in CI is with the `check` command. If the configuration has drifted, `ruff-sync check` will exit with a non-zero code, failing the build.
+
+### GitHub Actions
+
+We recommend using `uv` to run `ruff-sync` in GitHub Actions.
+
+```yaml
+name: "Standards Check"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ruff-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Check Ruff Sync
+        run: uvx ruff-sync check --semantic
+```
+
+### GitLab CI
+
+```yaml
+ruff-sync-check:
+  image: python:3.12
+  script:
+    - pip install ruff-sync
+    - ruff-sync check --semantic
+```
+
+## Best Practices
+
+### Use `--semantic`
+
+By default, `ruff-sync check` does a strict comparison of the TOML files. This means that if you manually reformat `pyproject.toml` or add a comment, the check will fail even if the actual Ruff rules are the same.
+
+In CI, you usually only care about the functional configuration. Using `--semantic` ensures that minor formatting changes don't break your builds.
+
+### Use a Dedicated Workflow
+
+Running `ruff-sync` as a separate job in your linting workflow makes it easy to identify when a failure is due to configuration drift rather than a code quality issue.
+
+### Automated PRs
+
+Instead of just checking, some organizations prefer to have a bot automatically open a PR when the upstream configuration changes. You can achieve this by running `ruff-sync pull` and using an action like `create-pull-request`.

ruff_sync-0.1.0.dev0/docs/configuration.md

@@ -0,0 +1,64 @@
+# Configuration
+
+`ruff-sync` can be configured in your `pyproject.toml` file under the `[tool.ruff-sync]` section.
+
+## Reference
+
+| Key | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `upstream` | `str` | *Required* | The URL of the upstream `pyproject.toml` or `ruff.toml`. |
+| `to` | `str` | `"."` | The local directory or file where configuration should be merged. |
+| `exclude` | `list[str]` | `["lint.per-file-ignores"]` | A list of configuration keys to preserve locally. |
+| `branch` | `str` | `"main"` | The default branch to use when resolving repository URLs. |
+| `path` | `str` | `""` | The directory path within the repository where the config is located. |
+| `semantic` | `bool` | `false` | Whether `check` should default to semantic matching. |
+| `diff` | `bool` | `true` | Whether `check` should show a diff by default. |
+
+## Exclude Patterns
+
+The `exclude` setting is powerful. It allows you to adopt most of an upstream configuration while keeping some parts specific to your repository.
+
+Exclusions use dotted paths to target specific sections or keys.
+
+### Examples
+
+#### Preserve per-file ignores
+
+This is the default. It ensures that any custom ignores you've set for specific files in your repo aren't overwritten by the upstream.
+
+```toml
+[tool.ruff-sync]
+exclude = ["lint.per-file-ignores"]
+```
+
+#### Manage specific plugins locally
+
+If you want to use the upstream rules but manage `isort` settings yourself:
+
+```toml
+[tool.ruff-sync]
+exclude = ["lint.isort"]
+```
+
+#### Keep a specific rule toggle
+
+If you want to manage whether a specific rule is ignored or selected:
+
+```toml
+[tool.ruff-sync]
+exclude = ["lint.ignore", "lint.select"]
+```
+
+#### Preserve target version
+
+If your projects are on different Python versions but share linting rules:
+
+```toml
+[tool.ruff-sync]
+exclude = ["target-version"]
+```
+
+## Deprecation Notes
+
+- The key `source` in `[tool.ruff-sync]` is deprecated and will be removed in a future version. Use `to` instead.
+- The `--source` CLI flag is also deprecated in favor of `--to`.

ruff_sync-0.1.0.dev0/docs/gen_ref_pages.py

@@ -0,0 +1,34 @@
+"""Generate the code reference pages."""
+
+from __future__ import annotations
+
+import pathlib
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()  # type: ignore[attr-defined,no-untyped-call]
+
+for path in sorted(pathlib.Path("src").rglob("*.py")):
+    module_path = path.relative_to("src").with_suffix("")
+    doc_path = path.relative_to("src").with_suffix(".md")
+    full_doc_path = pathlib.Path("reference", doc_path)
+
+    parts = list(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts.pop()
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[tuple(parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print(f"::: {identifier}", file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

ruff_sync-0.1.0.dev0/docs/index.md

@@ -0,0 +1,40 @@
+# ruff-sync
+
+[![PyPI](https://img.shields.io/pypi/v/ruff-sync.svg)](https://pypi.org/project/ruff-sync/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ruff-sync.svg)](https://pypi.org/project/ruff-sync/)
+[![License](https://img.shields.io/github/license/Kilo59/ruff-sync.svg)](https://github.com/Kilo59/ruff-sync/blob/main/LICENSE)
+
+**ruff-sync** is a lightweight CLI tool to synchronize [Ruff](https://docs.astral.sh/ruff/) linter configuration across multiple Python projects.
+
+## The Problem
+
+Maintaining a consistent Ruff configuration across 10, 50, or 100 repositories is painful. When you decide to adopt a new rule or change a setting, you have to manually update every single `pyproject.toml`.
+
+Internal "base" configurations or shared presets often fall out of sync, or require complex inheritance setups that are hard to debug.
+
+## The Solution
+
+`ruff-sync` lets you define a "source of truth" (a URL to a `pyproject.toml` or `ruff.toml`) and pull the `[tool.ruff]` section into your local projects with a single command.
+
+- **Formatting Preserved**: Unlike standard TOML parsers, `ruff-sync` uses `tomlkit` to preserve your comments, indentation, and whitespace.
+- **Smart Merging**: Intelligently merges nested tables (like `lint.per-file-ignores`) while allowing you to exclude specific keys you want to manage locally.
+- **CI Friendly**: Use `ruff-sync check` in your CI pipeline to ensure projects haven't drifted from the upstream standard.
+
+## Quick Start
+
+### 1. Configure your project
+
+Add the upstream URL to your `pyproject.toml`:
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards/blob/main/pyproject.toml"
+```
+
+### 2. Pull the configuration
+
+```bash
+uv run ruff-sync pull
+```
+
+This will download the upstream file, extract the `[tool.ruff]` section, and merge it into your local file.

ruff_sync-0.1.0.dev0/docs/installation.md

@@ -0,0 +1,47 @@
+# Installation
+
+`ruff-sync` is a Python CLI tool. We recommend using `uv` for the best experience, but it works with standard Python package managers as well.
+
+## Recommended: Using `uv`
+
+If you are using [uv](https://docs.astral.sh/uv/), you can run `ruff-sync` without installing it globally:
+
+```bash
+uvx ruff-sync pull
+```
+
+Or add it to your project's development dependencies:
+
+```bash
+uv add --dev ruff-sync
+uv run ruff-sync pull
+```
+
+## Other Methods
+
+=== "pipx"
+
+    [pipx](https://github.com/pypa/pipx) is the recommended way to install Python CLIs globally in isolated environments.
+
+    ```bash
+    pipx install ruff-sync
+    ```
+
+=== "pip"
+
+    You can install `ruff-sync` from PyPI using `pip`:
+
+    ```bash
+    pip install ruff-sync
+    ```
+
+    > [!WARNING]
+    > We recommend using a virtual environment or `pipx` to avoid dependency conflicts with other global packages.
+
+## Verifying Installation
+
+Check that `ruff-sync` is installed correctly by running:
+
+```bash
+ruff-sync --version
+```