ruff-sync 0.1.0.dev1__tar.gz → 0.1.1.dev1__tar.gz

ruff_sync-0.1.1.dev1/.agents/skills/release-notes-generation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: release-notes-generation
+description: Draft professional and categorized release notes for ruff-sync using GitHub CLI, git history, and the `invoke release` task.
+---
+
+# Release Notes Generation
+
+This skill guides you through drafting high-quality release notes for `ruff-sync`. It leverages the `invoke release` task and GitHub CLI for context.
+
+## Prerequisites
+
+- **GitHub CLI (`gh`)**: Must be authenticated.
+- **Invoke**: Dev tasks are defined in `tasks.py`.
+- **Git**: Recent history and tags must be available.
+
+## Workflow
+
+### 1. Gather Context
+
+Before drafting, understand what has changed since the last release.
+
+```bash
+# Get the latest release tag and notes
+gh release list --limit 1
+gh release view <tag>
+
+# List merged PRs since the last tag
+# Replace <tag> with the tag found above
+gh pr list --state merged --search "merged:><tag-date>"
+
+# Or simple git log
+git log <tag>..HEAD --oneline
+```
+
+### 2. Create Draft Release
+
+Use the project's built-in release task to scaffold the release. This task automatically tags the release based on the version in `pyproject.toml` and uses GitHub's `--generate-notes` feature to create a starting point.
+
+```bash
+# Create a draft release (default behavior of invoke release)
+uv run invoke release --draft --skip-tests
+```
+
+> [!NOTE]
+> `invoke release` will:
+> 1. Check if you are on `main`.
+> 2. Check for clean git state.
+> 3. Create a GitHub Release with `--generate-notes`.
+
+### 3. Refine Release Notes
+
+GitHub's automatically generated notes are a good start but often lack professional categorization and narrative. Use the following structure for final refinement:
+
+#### Categorization
+- **🚀 Features**: New capabilities added to `ruff_sync`.
+- **🐞 Bug Fixes**: Issues resolved in CLI, merging logic, or HTTP handling.
+- **✨ Improvements**: Enhancements to existing features, performance, or logging.
+- **📖 Documentation**: Updates to `README.md`, `docs/`, or docstrings.
+- **🛠️ Maintenance**: Dependency updates, CI changes, or test refactoring.
+
+#### Writing Style
+- Use clear, action-oriented language (e.g., "Add support...", "Fix issue where...", "Refactor...").
+- Link to PRs and contributors using their GitHub handles.
+- Include a "Breaking Changes" section if applicable (use `[!WARNING]` alerts).
+
+### 4. Finalize
+
+Once the notes are drafted and refined, you can view the draft on GitHub or update it via CLI.
+
+```bash
+# View the draft notes
+gh release view v<version>
+
+# Edit the draft (opens your editor)
+gh release edit v<version> --notes "your new notes"
+```
+
+## Tips
+
+- **Consistency**: Refer to the `AGENTS.md` for project-specific terminology (e.g., "Upstream Layers").
+- **Screenshots**: If the release includes significantly visible changes (e.g., new logging or CLI output formats), consider embedding a screenshot or recording in the notes.
+- **Automated Summary**: You can ask the AI assistant to "Draft release notes based on the git log since <tag>" to get a structured summary before applying it to the release.

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/.pre-commit-config.yaml

@@ -7,12 +7,13 @@ repos:
       - id: check-yaml
         args: ["--unsafe"]
         exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
+      - id: check-toml
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: no-commit-to-branch
         args: [--branch, develop, --branch, main]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.5"
+    rev: "v0.15.6"
     hooks:
       - id: ruff-check
         args: ["--fix"]

ruff_sync-0.1.1.dev1/.pre-commit-hooks.yaml

@@ -0,0 +1,15 @@
+- id: ruff-sync-pull
+  name: ruff-sync-pull
+  description: Pull and apply upstream ruff configuration.
+  entry: ruff-sync pull
+  language: python
+  files: ^(\.ruff\.toml|ruff\.toml|pyproject\.toml)$
+  pass_filenames: false
+
+- id: ruff-sync-check
+  name: ruff-sync-check
+  description: Check if ruff configuration is in sync with upstream.
+  entry: ruff-sync check --semantic
+  language: python
+  files: ^(\.ruff\.toml|ruff\.toml|pyproject\.toml)$
+  pass_filenames: false

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/AGENTS.md

@@ -150,6 +150,7 @@ uv run coverage run -m pytest -vv
 - Use `pathlib` over `os.path` (enforced by `PTH` rules).
 - Prefer f-strings for logging (we ignore `G004`).
 - Do not create custom exception classes for simple errors (`TRY003` is ignored).
+- **Prefer `NamedTuple` for return types** over plain tuples to improve readability and type safety.
 
 ### TOML Handling
 

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.0.dev1
+Version: 0.1.1.dev1
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
 Project-URL: Documentation, https://kilo59.github.io/ruff-sync/
@@ -54,6 +54,7 @@ Description-Content-Type: text/markdown
 - [Quick Start](#quick-start)
 - [Key Features](#key-features)
 - [Configuration](#configuration)
+- [Pre-commit Integration](#pre-commit-integration)
 - [CI Integration](#ci-integration)
 - [Example Workflow](#example-workflow)
 - [Detailed Check Logic](#detailed-check-logic)
@@ -132,37 +133,64 @@ pip install ruff-sync
 
 ### Usage
 
+**The Basic Sync**
+
+```console
+# Pull rules from a central repository into your current project
+ruff-sync pull https://github.com/my-org/standards
+```
+
+**Persistent Configuration**
+
+```console
+# If configured in pyproject.toml (see Configuration), simply run:
+ruff-sync pull
+```
+
+**Initializing a New Project**
+
+```console
+# Scaffold a new pyproject.toml if your directory is empty
+ruff-sync pull https://github.com/my-org/standards --init
+```
+
+**Syncing Subdirectories or Specific Files**
+
 ```console
-# 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
+ruff-sync pull https://github.com/my-org/standards/tree/main/configs/shared
+ruff-sync pull https://github.com/my-org/standards/blob/main/pyproject.toml
+```
 
-# Or a direct blob/file URL (auto-converts to raw)
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
+**Using Git (SSH/HTTP)**
 
-# Clone from any git repository (using SSH or HTTP, defaults to --depth 1)
-# You can use the --branch flag to specify a branch (default: main)
-ruff-sync git@github.com:my-org/standards.git
-ruff-sync ssh://git@gitlab.com/my-org/standards.git
+```console
+# Clones efficiently (depth 1, blob:none) to extract the config
+ruff-sync pull git@github.com:my-org/standards.git
+```
 
-# Or if configured in pyproject.toml (see Configuration), simply run:
-ruff-sync
+**Excluding Specific Rules**
 
+```console
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync --exclude lint.per-file-ignores lint.ignore
+ruff-sync pull --exclude lint.ignore
+```
+
+**Checking for Drift (CI)**
 
-# Check if your local config is in sync (useful in CI)
+```console
+# Verify local config matches upstream. Exits 1 if out of sync.
 ruff-sync check https://github.com/my-org/standards
 
-# Semantic check — ignore cosmetic differences like comments and whitespace
+# Semantic check — ignores cosmetic differences like comments and whitespace
 ruff-sync check --semantic
 ```
 
-Run `ruff-sync --help` for full details on all available options.
+See the [Usage documentation](https://kilo59.github.io/ruff-sync/usage/) for more detailed examples and advanced workflows.
 
 ## 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.
+- 📂 **Upstream Layers** — Merge configurations from several sources sequentially (e.g., base company config + team-specific overrides).
 - 🌐 **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.
@@ -200,8 +228,9 @@ Here are all the possible values that can be provided in `[tool.ruff-sync]` alon
 
 ```toml
 [tool.ruff-sync]
-# The source of truth URL for your Ruff configuration. (Required, unless passed via CLI)
-upstream = "https://github.com/my-org/standards"
+# The source of truth URL(s) for your Ruff configuration. (Required, unless passed via CLI)
+# Accepts a single string URL or a list of URLs.
+upstream = ["https://github.com/my-org/standards", "https://github.com/my-org/team-tweaks"]
 
 # A list of config keys to exclude from being synced. (Default: ["lint.per-file-ignores"])
 # Use simple names for top-level keys, and dotted paths for nested keys.
@@ -221,6 +250,19 @@ path = "config/ruff"
 to = "."
 ```
 
+## Pre-commit Integration
+
+Ensure your configuration is always in sync before every commit. Add this to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.0  # Use the latest version
+  hooks:
+    - id: ruff-sync-check
+```
+
+See the [Pre-commit Guide](https://kilo59.github.io/ruff-sync/pre-commit/) for more details.
+
 ## CI Integration
 
 The `check` command is designed for use in CI pipelines. Add it as a step to catch config drift before it merges:
@@ -329,10 +371,13 @@ When you run `ruff-sync check`, it follows this process to determine if your pro
 ```mermaid
 flowchart TD
     Start([Start]) --> Local[Read Local Configuration]
-    Local --> Upstream[Download Upstream Configuration]
-    Upstream --> Extract[Extract tool.ruff section if needed]
+    Local --> Upstreams{For each Upstream}
+    Upstreams --> Download[Download/Clone Configuration]
+    Download --> Extract[Extract section if needed]
     Extract --> Exclude[Apply Exclusions]
-    Exclude --> Merge[Perform in-memory Merge]
+    Exclude --> Merge[Merge into in-memory Doc]
+    Merge --> Upstreams
+    Upstreams -- Done --> Comparison
 
     subgraph Comparison [Comparison Logic]
         direction TB

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/README.md

@@ -23,6 +23,7 @@
 - [Quick Start](#quick-start)
 - [Key Features](#key-features)
 - [Configuration](#configuration)
+- [Pre-commit Integration](#pre-commit-integration)
 - [CI Integration](#ci-integration)
 - [Example Workflow](#example-workflow)
 - [Detailed Check Logic](#detailed-check-logic)
@@ -101,37 +102,64 @@ pip install ruff-sync
 
 ### Usage
 
+**The Basic Sync**
+
+```console
+# Pull rules from a central repository into your current project
+ruff-sync pull https://github.com/my-org/standards
+```
+
+**Persistent Configuration**
+
+```console
+# If configured in pyproject.toml (see Configuration), simply run:
+ruff-sync pull
+```
+
+**Initializing a New Project**
+
+```console
+# Scaffold a new pyproject.toml if your directory is empty
+ruff-sync pull https://github.com/my-org/standards --init
+```
+
+**Syncing Subdirectories or Specific Files**
+
 ```console
-# 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
+ruff-sync pull https://github.com/my-org/standards/tree/main/configs/shared
+ruff-sync pull https://github.com/my-org/standards/blob/main/pyproject.toml
+```
 
-# Or a direct blob/file URL (auto-converts to raw)
-ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
+**Using Git (SSH/HTTP)**
 
-# Clone from any git repository (using SSH or HTTP, defaults to --depth 1)
-# You can use the --branch flag to specify a branch (default: main)
-ruff-sync git@github.com:my-org/standards.git
-ruff-sync ssh://git@gitlab.com/my-org/standards.git
+```console
+# Clones efficiently (depth 1, blob:none) to extract the config
+ruff-sync pull git@github.com:my-org/standards.git
+```
 
-# Or if configured in pyproject.toml (see Configuration), simply run:
-ruff-sync
+**Excluding Specific Rules**
 
+```console
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync --exclude lint.per-file-ignores lint.ignore
+ruff-sync pull --exclude lint.ignore
+```
+
+**Checking for Drift (CI)**
 
-# Check if your local config is in sync (useful in CI)
+```console
+# Verify local config matches upstream. Exits 1 if out of sync.
 ruff-sync check https://github.com/my-org/standards
 
-# Semantic check — ignore cosmetic differences like comments and whitespace
+# Semantic check — ignores cosmetic differences like comments and whitespace
 ruff-sync check --semantic
 ```
 
-Run `ruff-sync --help` for full details on all available options.
+See the [Usage documentation](https://kilo59.github.io/ruff-sync/usage/) for more detailed examples and advanced workflows.
 
 ## 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.
+- 📂 **Upstream Layers** — Merge configurations from several sources sequentially (e.g., base company config + team-specific overrides).
 - 🌐 **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.
@@ -169,8 +197,9 @@ Here are all the possible values that can be provided in `[tool.ruff-sync]` alon
 
 ```toml
 [tool.ruff-sync]
-# The source of truth URL for your Ruff configuration. (Required, unless passed via CLI)
-upstream = "https://github.com/my-org/standards"
+# The source of truth URL(s) for your Ruff configuration. (Required, unless passed via CLI)
+# Accepts a single string URL or a list of URLs.
+upstream = ["https://github.com/my-org/standards", "https://github.com/my-org/team-tweaks"]
 
 # A list of config keys to exclude from being synced. (Default: ["lint.per-file-ignores"])
 # Use simple names for top-level keys, and dotted paths for nested keys.
@@ -190,6 +219,19 @@ path = "config/ruff"
 to = "."
 ```
 
+## Pre-commit Integration
+
+Ensure your configuration is always in sync before every commit. Add this to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.0  # Use the latest version
+  hooks:
+    - id: ruff-sync-check
+```
+
+See the [Pre-commit Guide](https://kilo59.github.io/ruff-sync/pre-commit/) for more details.
+
 ## CI Integration
 
 The `check` command is designed for use in CI pipelines. Add it as a step to catch config drift before it merges:
@@ -298,10 +340,13 @@ When you run `ruff-sync check`, it follows this process to determine if your pro
 ```mermaid
 flowchart TD
     Start([Start]) --> Local[Read Local Configuration]
-    Local --> Upstream[Download Upstream Configuration]
-    Upstream --> Extract[Extract tool.ruff section if needed]
+    Local --> Upstreams{For each Upstream}
+    Upstreams --> Download[Download/Clone Configuration]
+    Download --> Extract[Extract section if needed]
     Extract --> Exclude[Apply Exclusions]
-    Exclude --> Merge[Perform in-memory Merge]
+    Exclude --> Merge[Merge into in-memory Doc]
+    Merge --> Upstreams
+    Upstreams -- Done --> Comparison
 
     subgraph Comparison [Comparison Logic]
         direction TB

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/docs/ci-integration.md

@@ -72,26 +72,9 @@ ruff-sync-check:
 
 ---
 
-## 🛠️ Pre-commit Integration
-
 You can use `ruff-sync` with `pre-commit` to ensure your configuration is always in sync before pushing.
 
-Add this to your `.pre-commit-config.yaml`:
-
-```yaml
-repos:
-  - repo: local
-    hooks:
-      - id: ruff-sync-check
-        name: ruff-sync-check
-        entry: uvx ruff-sync check --semantic
-        language: system
-        files: ^pyproject\.toml$
-        pass_filenames: false
-```
-
-!!! note
-    Running `ruff-sync check` in pre-commit is fast because it only performs a network request if the local `pyproject.toml` is older than the upstream or if no cache exists.
+See the [Pre-commit Guide](pre-commit.md) for details on using the official hooks.
 
 ---
 
@@ -101,6 +84,12 @@ repos:
 
 In CI, you usually only care about the functional configuration. Using `--semantic` ensures that minor formatting changes don't break your builds, while still guaranteeing that the actual rules are identical.
 
+### Handle Exclusions Properly
+
+If your project intentionally diverges from the upstream (e.g., using different `per-file-ignores` or ignoring a specific rule), ensure those overrides are listed in the `[tool.ruff-sync]` `exclude` list in your `pyproject.toml`.
+
+The `check` command respects your local `exclude` list. If you exclude a setting, `ruff-sync check` will completely ignore it when comparing against the upstream, ensuring that intended deviations never cause CI to fail!
+
 ### 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.

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/docs/configuration.md

@@ -6,7 +6,7 @@
 
 | Key | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `upstream` | `str` | *Required* | The URL of the upstream `pyproject.toml` or `ruff.toml`. |
+| `upstream` | `str \| list[str]` | *Required* | The URL(s) 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. |
@@ -58,6 +58,21 @@ If your projects are on different Python versions but share linting rules:
 exclude = ["target-version"]
 ```
 
+#### Sequential merging of multiple sources
+
+You can specify multiple upstream sources as a list. They will be merged in order—from top to bottom—with later sources overriding or extending earlier ones.
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/shared-config",  # 1. Base rules
+    "https://github.com/my-org/team-overrides", # 2. Team-specific tweaks (wins)
+]
+```
+
+!!! tip "Last One Wins"
+    The merge logic follows a "last one wins" approach for simple keys (like `line-length`), while performing a deep merge for configuration tables like `lint.per-file-ignores`.
+
 ## Deprecation Notes
 
 - The key `source` in `[tool.ruff-sync]` is deprecated and will be removed in a future version. Use `to` instead.

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/docs/index.md

@@ -13,10 +13,13 @@
 ## 🚀 Key Features
 
 * **⚡ Fast & Lightweight**: Zero-config needed for most projects.
-* **✨ Formatting Preserved**: Uses `tomlkit` to keep your comments, indentation, and whitespace exactly as they are.
-* **🛡️ Smart Merging**: Safely merges nested tables (like `lint.per-file-ignores`) without overwriting local overrides.
-* **🔗 Flexible Sources**: Sync from GitHub, GitLab, raw URLs, or local files.
-* **✅ CI Ready**: Built-in `check` command with semantic diffs for automated pipelines.
+* **✨ Formatting Preserved**: Keeps all comments and whitespace via `tomlkit`.
+* **🛡️ Smart Merging**: Safely merges nested tables without overwriting local overrides.
+* **📂 Upstream Layers**: Combine and merge configurations from several sources sequentially.
+* **🌐 Flexible Sources**: Sync from GitHub, GitLab, raw URLs, or local files.
+* **📥 Efficient Git Support**: Shallow clones and sparse checkouts for fast extraction.
+* **🚀 Zero-Config Bootstrapping**: Use `--init` to scaffold a new project in one command.
+* **✅ CI Ready**: Built-in `check` command with semantic comparison logic.
 
 ---
 
@@ -37,16 +40,26 @@ Internal "base" configurations or shared presets often fall out of sync, or requ
 
 ## 🏁 Quick Start
 
-### 1. Configure your project
+### 1. Initialize a new project (Optional)
 
-Add the upstream URL to your `pyproject.toml`:
+If your local directory doesn't have a configuration file yet, you can fetch the standard and create one instantly:
+
+```bash
+uv run ruff-sync pull https://github.com/my-org/standards --init
+```
+
+### 2. Configure an existing project
+
+Add the upstream URL to your `pyproject.toml` to make it the default:
 
 ```toml
 [tool.ruff-sync]
 upstream = "https://github.com/my-org/standards/blob/main/pyproject.toml"
 ```
 
-### 2. Pull the configuration
+### 3. Pull the configuration
+
+Once configured, simply run:
 
 ```bash
 uv run ruff-sync pull

ruff_sync-0.1.1.dev1/docs/pre-commit.md

@@ -0,0 +1,69 @@
+# Pre-commit Integration
+
+Using `ruff-sync` with [pre-commit](https://pre-commit.com/) ensures that your Ruff configuration stays in sync with your organization's standards automatically.
+
+## Official Hooks
+
+`ruff-sync` provides two official hooks:
+
+### `ruff-sync-check`
+
+Verifies that your local `pyproject.toml` or `ruff.toml` matches the upstream configuration. It is recommended to use this hook to prevent accidental drift.
+
+```yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.0  # Use the latest version
+  hooks:
+    - id: ruff-sync-check
+```
+
+### `ruff-sync-pull`
+
+Automatically pulls and applies the upstream configuration if a drift is detected.
+
+```yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.0  # Use the latest version
+  hooks:
+    - id: ruff-sync-pull
+```
+
+## Configuration
+
+The hooks will automatically respect the configuration defined in your `pyproject.toml` under `[tool.ruff-sync]`. Any arguments passed via `args` in `.pre-commit-config.yaml` will override these settings.
+
+> [!NOTE]
+> For a full list of configuration options, see the [Configuration Guide](configuration.md).
+
+### Example `.pre-commit-config.yaml`
+
+```yaml
+repos:
+  - repo: https://github.com/Kilo59/ruff-sync
+    rev: v0.1.0
+    hooks:
+      - id: ruff-sync-check
+        # Common arguments:
+        # --semantic: ignore cosmetic changes (default in check hook)
+        # --no-diff: hide the unified diff
+        # --to PATH: sync to a specific file or directory
+        args: ["--semantic", "--no-diff"]
+```
+
+## Why use `ruff-sync-check`?
+
+Running `ruff-sync check` in pre-commit is fast because:
+
+1. It only checks the `[tool.ruff]` section of the configuration.
+2. It minimizes network overhead by only fetching exactly what it needs (e.g., using direct HTTP requests for single files or partial git cloning for repositories).
+3. By default, it uses `--semantic` to ignore formatting-only differences, reducing false positives.
+
+For more complex scenarios, such as syncing from multiple upstreams or using directory prefixes, see [Advanced Usage](usage.md#advanced-usage).
+
+## Manual Execution
+
+You can always run the hooks manually using:
+
+```bash
+pre-commit run ruff-sync-check --all-files
+```

{ruff_sync-0.1.0.dev1 → ruff_sync-0.1.1.dev1}/docs/troubleshooting.md

@@ -4,6 +4,21 @@ Common issues and questions when using `ruff-sync`.
 
 ## Common Issues
 
+### Debug Logging
+
+If `ruff-sync` is not behaving as expected, you can increase the verbosity of the logs to see what's happening under the hood.
+
+**Usage**:
+
+- `-v`: Shows `INFO` level logs (e.g., which configuration file is being used, where upstreams are being sourced from).
+- `-vv`: Shows `DEBUG` level logs (e.g., detailed TOML merging operations and raw HTTP/Git requests).
+
+Example:
+
+```bash
+ruff-sync pull -vv
+```
+
 ### Upstream URL not found
 
 **Error**: `Error: Upstream Required. No upstream URL found in pyproject.toml or provided as argument.`
@@ -31,6 +46,30 @@ Use the `--exclude` flag to keep your local settings:
 ruff-sync pull --exclude lint.line-length
 ```
 
+### Multi-upstream Fetch Failures
+
+**Error**: `❌ <N> upstream fetches failed`
+
+This happens when one or more of the specified upstream URLs cannot be reached, do not exist, or return an error (e.g., 404 or 403). `ruff-sync` fetches all upstreams concurrently for speed, but requires ALL of them to succeed before it will attempt to merge.
+
+**Solution**:
+1. Check each URL in the terminal output to see which specific one failed.
+2. Verify you have network access and the correct permissions for each source.
+3. If an HTTP source is blocked or private, consider using a Git SSH URL instead.
+
+### Git SSH Workaround for Fetch Errors
+
+If you see an HTTP `403 Forbidden` or `404 Not Found` when trying to fetch from GitHub or GitLab, it might be due to authentication requirements.
+
+**Solution**:
+Use the git-clone alternative suggested in the error message:
+
+```bash
+ruff-sync pull git@github.com:org/repo.git
+```
+
+This uses your local SSH keys and is often more reliable for internal or private repositories.
+
 ## FAQ
 
 ### Does it support `ruff.toml`?