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

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

@@ -8,8 +8,11 @@ repos:
         args: ["--unsafe"]
         exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
       - id: check-toml
+      - id: check-case-conflict
       - id: end-of-file-fixer
       - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
       - id: no-commit-to-branch
         args: [--branch, develop, --branch, main]
   - repo: https://github.com/astral-sh/ruff-pre-commit

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

@@ -87,7 +87,7 @@ uv run ruff check . --fix
 - Tests have additional overrides in `tests/ruff.toml` (extends the root config).
 - All Python files must include `from __future__ import annotations` (enforced by isort rule `I002`).
 - Use `uv run ruff check . --fix` to auto-fix issues. Use `--unsafe-fixes` only if explicitly asked.
-- **Do NOT disable or ignore rules** unless the user explicitly asks you to.
+- **Do NOT disable or ignore rules** unless the user explicitly asks you to. You must **fix the underlying code** to pass the linter, rather than appending `# noqa` directives or adding rules to `ignore` in `pyproject.toml`.
 
 #### Understanding a Rule
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.1.dev1
+Version: 0.1.2.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/
@@ -137,48 +137,49 @@ pip install ruff-sync
 
 ```console
 # Pull rules from a central repository into your current project
-ruff-sync pull https://github.com/my-org/standards
+ruff-sync https://github.com/my-org/standards
 ```
 
 **Persistent Configuration**
 
 ```console
 # If configured in pyproject.toml (see Configuration), simply run:
-ruff-sync pull
+ruff-sync
 ```
 
 **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
+ruff-sync https://github.com/my-org/standards --init
 ```
 
 **Syncing Subdirectories or Specific Files**
 
 ```console
-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
+ruff-sync https://github.com/my-org/standards/tree/main/configs/shared
+ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
 ```
 
 **Using Git (SSH/HTTP)**
 
 ```console
 # Clones efficiently (depth 1, blob:none) to extract the config
-ruff-sync pull git@github.com:my-org/standards.git
+ruff-sync git@github.com:my-org/standards.git
 ```
 
 **Excluding Specific Rules**
 
 ```console
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync pull --exclude lint.ignore
+ruff-sync --exclude lint.ignore
 ```
 
 **Checking for Drift (CI)**
 
 ```console
-# Verify local config matches upstream. Exits 1 if out of sync.
+# Verify local config matches upstream. Exits 1 if config is out of sync.
+# If opted in via --pre-commit, exits 2 if only the pre-commit hook is out of sync.
 ruff-sync check https://github.com/my-org/standards
 
 # Semantic check — ignores cosmetic differences like comments and whitespace
@@ -198,6 +199,7 @@ See the [Usage documentation](https://kilo59.github.io/ruff-sync/usage/) for mor
 - 🌍 **Works with any host** — GitHub, GitLab, Bitbucket, private SSH servers, or any raw URL that serves a `pyproject.toml` or `ruff.toml`.
 - 🤖 **CI-ready `check` command** — Verify that your local config is in sync without modifying anything. Exits 1 if out of sync, making it perfect for pre-merge gates. ([See detailed logic](#detailed-check-logic))
 - 🧠 **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
+- 🔗 **Pre-commit hook sync** — Use `--pre-commit` to automatically keep your `ruff-pre-commit` hook version in `.pre-commit-config.yaml` matching your project's Ruff version.
 
 ## Configuration
 
@@ -208,6 +210,9 @@ You can configure `ruff-sync` itself in your `pyproject.toml`:
 # The source of truth for your Ruff configuration
 upstream = "https://github.com/my-org/standards"
 
+# Automatically sync the pre-commit Ruff hook version
+pre-commit-version-sync = true
+
 # Use simple names for top-level keys, and dotted paths for nested keys
 exclude = [
     "target-version",                      # Top-level [tool.ruff] key — projects target different Python versions
@@ -242,12 +247,15 @@ exclude = [
 # The branch, tag, or commit hash to use when resolving a Git repository URL. (Default: "main")
 branch = "develop"
 
-# A directory prefix to use when looking for a configuration file in a repository. (Default: "")
+# The directory path within the repository where the config is located. (Default: "")
 # Useful if the upstream config is not at the repository root.
 path = "config/ruff"
 
 # The local target directory or file to sync into. (Default: ".")
 to = "."
+
+# Keep the pre-commit Ruff hook version in sync with the project's Ruff version. (Default: false)
+pre-commit-version-sync = true
 ```
 
 ## Pre-commit Integration
@@ -292,6 +300,10 @@ $ ruff-sync check --semantic
    ]
 ```
 
+> [!TIP]
+> See the [Best Practices](https://kilo59.github.io/ruff-sync/best-practices/) guide for recommendations on whether to make your CI checks blocking or informational.
+
+
 ## Example Workflow
 
 A typical setup for an organization:
@@ -359,7 +371,7 @@ By default, `ruff-sync` requires an existing configuration file (`pyproject.toml
 
 ```console
 # Create a new pyproject.toml (or ruff.toml) pre-configured with upstream settings
-ruff-sync pull https://github.com/my-org/standards --init
+ruff-sync https://github.com/my-org/standards --init
 ```
 
 `ruff-sync` seamlessly supports both `pyproject.toml` and standalone `ruff.toml` (or `.ruff.toml`) files. If your local target is a directory, it will look for configuration files in the following order: `ruff.toml` -> `.ruff.toml` -> `pyproject.toml`. If your upstream source or your local target is a `ruff.toml`, it will automatically adapt and sync the root configuration rather than looking for a `[tool.ruff]` section.
@@ -389,18 +401,25 @@ flowchart TD
 
     Merge --> Comparison
 
-    CompareVal --> ResultNode{Match?}
+    CompareVal --> ResultNode{Ruff Sync Match?}
     CompareFull --> ResultNode
 
-    ResultNode -- Yes --> Success([Exit 0: In Sync])
+    ResultNode -- Yes --> PCNode{--pre-commit?}
+    PCNode -- Yes --> CheckPC[Check pre-commit hook version]
+    CheckPC -- Match --> Success([Exit 0: In Sync])
+    CheckPC -- Mismatch --> PCOut([Exit 2: Pre-commit Out of Sync])
+    PCNode -- No --> Success
+
     ResultNode -- No --> Diff[Generate Diff]
-    Diff --> Fail([Exit 1: Out of Sync])
+    Diff --> Fail([Exit 1: Ruff Config Out of Sync])
 
     %% Styling
     style Start fill:#4a90e2,color:#fff,stroke:#357abd
     style Success fill:#48c774,color:#fff,stroke:#36975a
     style Fail fill:#f14668,color:#fff,stroke:#b2334b
+    style PCOut fill:#ff9800,color:#fff,stroke:#e65100
     style ResultNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
+    style PCNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
     style Comparison fill:none,stroke:#9e9e9e,stroke-dasharray: 5 5,stroke-width:2px
     style SemanticNode fill:#f4f4f4,color:#363636,stroke:#dbdbdb
 ```

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

@@ -106,48 +106,49 @@ pip install ruff-sync
 
 ```console
 # Pull rules from a central repository into your current project
-ruff-sync pull https://github.com/my-org/standards
+ruff-sync https://github.com/my-org/standards
 ```
 
 **Persistent Configuration**
 
 ```console
 # If configured in pyproject.toml (see Configuration), simply run:
-ruff-sync pull
+ruff-sync
 ```
 
 **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
+ruff-sync https://github.com/my-org/standards --init
 ```
 
 **Syncing Subdirectories or Specific Files**
 
 ```console
-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
+ruff-sync https://github.com/my-org/standards/tree/main/configs/shared
+ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
 ```
 
 **Using Git (SSH/HTTP)**
 
 ```console
 # Clones efficiently (depth 1, blob:none) to extract the config
-ruff-sync pull git@github.com:my-org/standards.git
+ruff-sync git@github.com:my-org/standards.git
 ```
 
 **Excluding Specific Rules**
 
 ```console
 # Exclude specific sections from being overwritten using dotted paths
-ruff-sync pull --exclude lint.ignore
+ruff-sync --exclude lint.ignore
 ```
 
 **Checking for Drift (CI)**
 
 ```console
-# Verify local config matches upstream. Exits 1 if out of sync.
+# Verify local config matches upstream. Exits 1 if config is out of sync.
+# If opted in via --pre-commit, exits 2 if only the pre-commit hook is out of sync.
 ruff-sync check https://github.com/my-org/standards
 
 # Semantic check — ignores cosmetic differences like comments and whitespace
@@ -167,6 +168,7 @@ See the [Usage documentation](https://kilo59.github.io/ruff-sync/usage/) for mor
 - 🌍 **Works with any host** — GitHub, GitLab, Bitbucket, private SSH servers, or any raw URL that serves a `pyproject.toml` or `ruff.toml`.
 - 🤖 **CI-ready `check` command** — Verify that your local config is in sync without modifying anything. Exits 1 if out of sync, making it perfect for pre-merge gates. ([See detailed logic](#detailed-check-logic))
 - 🧠 **Semantic mode** — Use `--semantic` to ignore cosmetic differences (comments, whitespace) and only fail on real value changes.
+- 🔗 **Pre-commit hook sync** — Use `--pre-commit` to automatically keep your `ruff-pre-commit` hook version in `.pre-commit-config.yaml` matching your project's Ruff version.
 
 ## Configuration
 
@@ -177,6 +179,9 @@ You can configure `ruff-sync` itself in your `pyproject.toml`:
 # The source of truth for your Ruff configuration
 upstream = "https://github.com/my-org/standards"
 
+# Automatically sync the pre-commit Ruff hook version
+pre-commit-version-sync = true
+
 # Use simple names for top-level keys, and dotted paths for nested keys
 exclude = [
     "target-version",                      # Top-level [tool.ruff] key — projects target different Python versions
@@ -211,12 +216,15 @@ exclude = [
 # The branch, tag, or commit hash to use when resolving a Git repository URL. (Default: "main")
 branch = "develop"
 
-# A directory prefix to use when looking for a configuration file in a repository. (Default: "")
+# The directory path within the repository where the config is located. (Default: "")
 # Useful if the upstream config is not at the repository root.
 path = "config/ruff"
 
 # The local target directory or file to sync into. (Default: ".")
 to = "."
+
+# Keep the pre-commit Ruff hook version in sync with the project's Ruff version. (Default: false)
+pre-commit-version-sync = true
 ```
 
 ## Pre-commit Integration
@@ -261,6 +269,10 @@ $ ruff-sync check --semantic
    ]
 ```
 
+> [!TIP]
+> See the [Best Practices](https://kilo59.github.io/ruff-sync/best-practices/) guide for recommendations on whether to make your CI checks blocking or informational.
+
+
 ## Example Workflow
 
 A typical setup for an organization:
@@ -328,7 +340,7 @@ By default, `ruff-sync` requires an existing configuration file (`pyproject.toml
 
 ```console
 # Create a new pyproject.toml (or ruff.toml) pre-configured with upstream settings
-ruff-sync pull https://github.com/my-org/standards --init
+ruff-sync https://github.com/my-org/standards --init
 ```
 
 `ruff-sync` seamlessly supports both `pyproject.toml` and standalone `ruff.toml` (or `.ruff.toml`) files. If your local target is a directory, it will look for configuration files in the following order: `ruff.toml` -> `.ruff.toml` -> `pyproject.toml`. If your upstream source or your local target is a `ruff.toml`, it will automatically adapt and sync the root configuration rather than looking for a `[tool.ruff]` section.
@@ -358,18 +370,25 @@ flowchart TD
 
     Merge --> Comparison
 
-    CompareVal --> ResultNode{Match?}
+    CompareVal --> ResultNode{Ruff Sync Match?}
     CompareFull --> ResultNode
 
-    ResultNode -- Yes --> Success([Exit 0: In Sync])
+    ResultNode -- Yes --> PCNode{--pre-commit?}
+    PCNode -- Yes --> CheckPC[Check pre-commit hook version]
+    CheckPC -- Match --> Success([Exit 0: In Sync])
+    CheckPC -- Mismatch --> PCOut([Exit 2: Pre-commit Out of Sync])
+    PCNode -- No --> Success
+
     ResultNode -- No --> Diff[Generate Diff]
-    Diff --> Fail([Exit 1: Out of Sync])
+    Diff --> Fail([Exit 1: Ruff Config Out of Sync])
 
     %% Styling
     style Start fill:#4a90e2,color:#fff,stroke:#357abd
     style Success fill:#48c774,color:#fff,stroke:#36975a
     style Fail fill:#f14668,color:#fff,stroke:#b2334b
+    style PCOut fill:#ff9800,color:#fff,stroke:#e65100
     style ResultNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
+    style PCNode fill:#ffdd57,color:#4a4a4a,stroke:#d4b106
     style Comparison fill:none,stroke:#9e9e9e,stroke-dasharray: 5 5,stroke-width:2px
     style SemanticNode fill:#f4f4f4,color:#363636,stroke:#dbdbdb
 ```

ruff_sync-0.1.2.dev1/configs/data-science-engineering/ruff.toml

@@ -0,0 +1,25 @@
+# configs/data-science-engineering/ruff.toml
+
+# Enable Jupyter notebook linting
+extend-include = ["*.ipynb"]
+extend-exclude = [".ipynb_checkpoints"]
+
+[lint]
+# Enable rules tailored for data science and engineering.
+extend-select = [
+    # https://docs.astral.sh/ruff/rules/#isort-i
+    "I",      # isort: Import sorting
+    # https://docs.astral.sh/ruff/rules/#numpy-specific-rules-npy
+    "NPY",    # NumPy-specific rules: NumPy conventions
+    # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
+    "PD",     # pandas-vet: Pandas code checks
+]
+# Ignore rules that conflict with `ruff format` (formatter-managed concerns).
+# Keep this in sync with other curated configs (e.g. fastapi/ruff.toml).
+ignore = [
+    "E111",  # indentation is handled by the formatter
+    "E114",  # indentation with comments is handled by the formatter
+    "E117",  # over-indented code is handled by the formatter
+    "E501",  # line length is handled by the formatter
+    "W191",  # tabs vs spaces is handled by the formatter
+]

ruff_sync-0.1.2.dev1/docs/best-practices.md

@@ -0,0 +1,79 @@
+# Best Practices
+
+When managing linter configurations across multiple projects with `ruff-sync`, following these best practices helps ensure a smooth, predictable, and manageable workflow for your entire organization.
+
+---
+
+## 📌 Pin Upstream Versions
+
+Instead of syncing directly from the `main` branch, it can be beneficial to **pin to specific tags, releases, or stable branches**.
+
+Linting rules evolve. If you sync from `main`, a new rule added to the central repository could instantly break CI across dozens of downstream projects the next time they run `ruff-sync` in an automated pipeline.
+
+Instead, configure your upstream like this:
+
+```toml
+[tool.ruff-sync]
+# Pin to a specific tag or commit for stability
+upstream = "https://github.com/my-org/standards/blob/v1.2.0/pyproject.toml"
+```
+
+When you are ready to roll out new linting rules, you can update the version across repositories in a controlled manner.
+
+---
+
+## 🎯 Use Strategic Exclusions
+
+Not every setting should be centralized. Some configurations are inherently project-specific.
+
+Use the `exclude` option to prevent `ruff-sync` from overwriting configurations that should remain local.
+
+For example, do not force all repositories to use the same Python target version, and allow projects to selectively ignore specific upstream rules that don't make sense locally:
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+exclude = [
+    # Always preserve local file-level exceptions (excluded by default)
+    "lint.per-file-ignores",
+    # Allow projects to define their own Python version
+    "target-version",
+    # Preserve local ignored rules that don't apply to this specific project
+    "lint.ignore"
+]
+```
+
+By excluding `lint.ignore`, a project can adopt the organization's standard `lint.select` list, but gracefully opt out of specific rules that cause issues in their specific domain without breaking the sync process.
+
+---
+
+## 🚦 Semantic Checks in CI
+
+To ensure your repository hasn't drifted from your organization's unified standards, you should run `ruff-sync check --semantic` in your Continuous Integration pipeline.
+
+**If you pin to a stable tag (as recommended above):**
+Make this a **blocking check**. Since the upstream configuration won't change unexpectedly, any drift means a developer inadvertently modified the local rules. Failing the build ensures the repository stays perfectly compliant.
+
+**If you sync directly from a moving branch (like `main`):**
+We recommend making this an **informational, non-failing check**. If a new rule is added upstream while a developer is working on a feature, blocking their PR can cause frustration. Instead, pair the informational check with a **weekly automated workflow** that pulls down the latest configuration and opens a pull request. This groups linter updates into a single controllable PR that can be reviewed and tested in isolation.
+
+See the [CI Integration Guide](ci-integration.md#automated-sync-prs) for an example GitHub Actions workflow that automatically syncs the configuration and opens a PR.
+
+---
+
+## 🏢 Hierarchical Configuration
+
+For large organizations with distinct teams or sub-projects (like a frontend-heavy full stack repo vs. a pure backend service), you can define multiple upstreams to create a hierarchy.
+
+Because `ruff-sync` merges multiple upstreams sequentially (from top to bottom), the "last one wins." This allows you to have a strict company-wide base config, and a slightly looser (or tighter) team-specific config.
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    # 1. Base company rules
+    "https://github.com/my-org/standards/blob/main/base.toml",
+
+    # 2. Team-specific tweaks (these override the base rules)
+    "https://github.com/my-org/standards/blob/main/team-alpha.toml",
+]
+```

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

@@ -47,7 +47,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
       - name: Pull upstream
-        run: uvx ruff-sync pull
+        run: uvx ruff-sync
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v6
         with:
@@ -80,6 +80,9 @@ See the [Pre-commit Guide](pre-commit.md) for details on using the official hook
 
 ## 💡 Best Practices
 
+> [!TIP]
+> Read the complete [Best Practices](best-practices.md) guide for a broader look at organizing `ruff-sync` deployments, including when semantic checks should be blocking vs. informational.
+
 ### Use `--semantic`
 
 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.

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

@@ -13,11 +13,15 @@
 | `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. |
+| `pre-commit-version-sync` | `bool` | `false` | Sync the pre-commit Ruff hook version with the project's Ruff version. |
 
 ## 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.
 
+> [!TIP]
+> See [Strategic Exclusions](best-practices.md#use-strategic-exclusions) in our Best Practices guide for recommendations on what settings to keep local.
+
 Exclusions use dotted paths to target specific sections or keys.
 
 ### Examples

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

@@ -20,6 +20,7 @@
 * **📥 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.
+* **🔗 Pre-commit Sync**: Automatically keep your `.pre-commit-config.yaml` Ruff hook version matched with your project's Ruff version.
 
 ---
 
@@ -45,7 +46,7 @@ Internal "base" configurations or shared presets often fall out of sync, or requ
 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
+uv run ruff-sync https://github.com/my-org/standards --init
 ```
 
 ### 2. Configure an existing project
@@ -62,7 +63,14 @@ upstream = "https://github.com/my-org/standards/blob/main/pyproject.toml"
 Once configured, simply run:
 
 ```bash
-uv run ruff-sync pull
+uv run ruff-sync
 ```
 
 This will download the upstream file, extract the `[tool.ruff]` section, and merge it into your local file while **preserving your artisanal comments and formatting**.
+
+---
+
+## 📚 Next Steps
+
+- Check out our [Best Practices](best-practices.md) for recommendations on adopting `ruff-sync` across your organization.
+- Read the [Usage](usage.md) guide for advanced examples.

{ruff_sync-0.1.1.dev1 → ruff_sync-0.1.2.dev1}/docs/installation.md

@@ -11,7 +11,7 @@ The easiest way to use `ruff-sync` across all your projects is by installing it
 ```bash
 uv tool install ruff-sync
 # Then simply run:
-ruff-sync pull
+ruff-sync
 ```
 
 ### One-off Invocation
@@ -19,7 +19,7 @@ ruff-sync pull
 If you just want to run `ruff-sync` once without installing it, use `uvx`:
 
 ```bash
-uvx ruff-sync pull
+uvx ruff-sync
 ```
 
 ### Project-specific Development
@@ -29,7 +29,7 @@ To keep the version consistent across your team and locked to your project, add
 ```bash
 uv add --dev ruff-sync
 # Then run it with:
-uv run ruff-sync pull
+uv run ruff-sync
 ```
 
 ---

{ruff_sync-0.1.1.dev1 → ruff_sync-0.1.2.dev1}/docs/pre-commit.md

@@ -58,7 +58,7 @@ Running `ruff-sync check` in pre-commit is fast because:
 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).
+For more complex scenarios, such as syncing from multiple upstreams or using directory prefixes, see [Usage](usage.md).
 
 ## Manual Execution
 
@@ -67,3 +67,26 @@ You can always run the hooks manually using:
 ```bash
 pre-commit run ruff-sync-check --all-files
 ```
+
+## Syncing the Ruff Hook Version
+
+In addition to syncing your Ruff configuration rules, `ruff-sync` can also automatically synchronize the version of the `astral-sh/ruff-pre-commit` hook in your `.pre-commit-config.yaml` to match the Ruff version installed in your project (e.g., from `uv.lock` or `pyproject.toml`).
+
+To enable this, use the `--pre-commit` flag:
+
+```bash
+ruff-sync --pre-commit
+```
+
+Or enable it permanently in your `pyproject.toml`:
+
+```toml
+[tool.ruff-sync]
+pre-commit-version-sync = true
+```
+
+If you have `pre-commit-version-sync` enabled in your configuration but need to explicitly disable it for a specific run (for example, during a CI step where pre-commit is turned off), you can bypass it using the `--no-pre-commit` flag:
+
+```bash
+ruff-sync check --no-pre-commit
+```

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

@@ -16,7 +16,7 @@ If `ruff-sync` is not behaving as expected, you can increase the verbosity of th
 Example:
 
 ```bash
-ruff-sync pull -vv
+ruff-sync -vv
 ```
 
 ### Upstream URL not found
@@ -26,14 +26,14 @@ ruff-sync pull -vv
 **Solution**:
 
 1. Ensure you have a `[tool.ruff-sync]` section in your `pyproject.toml` with an `upstream` key. See the [Configuration](configuration.md) guide for details.
-2. Or provide the URL directly as an argument: `ruff-sync pull https://github.com/org/repo/blob/main/pyproject.toml`
+2. Or provide the URL directly as an argument: `ruff-sync https://github.com/org/repo/blob/main/pyproject.toml`
 
 ### Local file not found (with `check`)
 
 **Error**: `FileNotFoundError: pyproject.toml not found`
 
 **Solution**:
-The `check` command expects a local `pyproject.toml`, `ruff.toml`, or `.ruff.toml` to exist. If you are setting up a new project, use `pull --init` first.
+The `check` command expects a local `pyproject.toml`, `ruff.toml`, or `.ruff.toml` to exist. If you are setting up a new project, use `ruff-sync --init` first.
 
 ### Merge conflicts in TOML
 
@@ -43,7 +43,7 @@ The `check` command expects a local `pyproject.toml`, `ruff.toml`, or `.ruff.tom
 Use the `--exclude` flag to keep your local settings:
 
 ```bash
-ruff-sync pull --exclude lint.line-length
+ruff-sync --exclude lint.line-length
 ```
 
 ### Multi-upstream Fetch Failures
@@ -65,7 +65,7 @@ If you see an HTTP `403 Forbidden` or `404 Not Found` when trying to fetch from
 Use the git-clone alternative suggested in the error message:
 
 ```bash
-ruff-sync pull git@github.com:org/repo.git
+ruff-sync git@github.com:org/repo.git
 ```
 
 This uses your local SSH keys and is often more reliable for internal or private repositories.