diff --git a/.gitignore b/.gitignore index 1e887ac3..c6bc5d28 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ /target .cache +__pycache__/ +site/ # Insta snapshots. *.pending-snap diff --git a/README.md b/README.md index 2ddd719f..2359aaf3 100644 --- a/README.md +++ b/README.md @@ -11,19 +11,21 @@ [![Discord](https://img.shields.io/discord/1403581202102878289?logo=discord)](https://discord.gg/3NRJUqJz86) - + [pre-commit](https://pre-commit.com/) is a framework to run hooks written in many languages, and it manages the language toolchain and dependencies for running the hooks. *prek* is a reimagined version of pre-commit, built in Rust. It is designed to be a faster, dependency-free and drop-in alternative for it, while also providing some additional long-requested features. + > [!WARNING] -> prek is not production-ready yet. Some subcommands and languages are not implemented. See the current gaps for drop-in parity: [TODO](https://prek.j178.dev/todo/). +> prek is not production-ready yet. Some subcommands and languages are not implemented. See the current gaps for drop-in parity: [TODO](https://prek.j178.dev/todo/). > -> It's already being adopted by [some projects](#who-is-using-prek), please give it a try - we'd love your feedback! +> It's already being adopted by [some projects](#who-is-using-prek), please give it a try - we'd love your feedback! + ## Features - 🚀 A single binary with no dependencies, does not require Python or any other runtime. @@ -33,6 +35,7 @@ while also providing some additional long-requested features. - 🐍 Integration with [`uv`](https://github.com/astral-sh/uv) for managing Python virtual environments and dependencies. - 🛠️ Improved toolchain installations for Python, Node.js, Go, Rust and Ruby, shared between hooks. - 📦 [Built-in](https://prek.j178.dev/builtin/) Rust-native implementation of some common hooks. + ## How to migrate @@ -53,6 +56,7 @@ cargo clippy.............................................................Passed For configuring `.pre-commit-config.yaml` and writing hooks, you can refer to the [pre-commit documentation](https://pre-commit.com/) as prek is fully compatible with it. + ## Why prek? ### prek is way faster @@ -69,9 +73,9 @@ For configuring `.pre-commit-config.yaml` and writing hooks, you can refer to th - No hassle with your Python version or virtual environments, prek automatically installs the required Python version and creates a virtual environment for you. - Built-in support for workspaces (or monorepos), each subproject can have its own `.pre-commit-config.yaml` file. - `prek run` has some nifty improvements over `pre-commit run`, such as: - - `prek run --directory ` runs hooks for files in the specified directory, no need to use `git ls-files -- | xargs pre-commit run --files` anymore. - - `prek run --last-commit` runs hooks for files changed in the last commit. - - `prek run [HOOK] [HOOK]` selects and runs multiple hooks. + - `prek run --directory ` runs hooks for files in the specified directory, no need to use `git ls-files -- | xargs pre-commit run --files` anymore. + - `prek run --last-commit` runs hooks for files changed in the last commit. + - `prek run [HOOK] [HOOK]` selects and runs multiple hooks. - `prek list` command lists all available hooks, their ids, and descriptions, providing a better overview of the configured hooks. - prek provides shell completions for `prek run ` command, making it easier to run specific hooks without remembering their ids. @@ -87,6 +91,7 @@ prek is pretty new, but it is already being used or recommend by some projects a - [OpenLineage](https://github.com/OpenLineage/OpenLineage/pull/3965) - [Authlib](https://github.com/authlib/authlib/pull/804) - [pre-commit-crocodile](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile/) + ## Installation @@ -97,15 +102,20 @@ prek provides a standalone installer script to download and install the tool, On Linux and macOS: + ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.sh | sh ``` + On Windows: + ```powershell powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.ps1 | iex" ``` + +
@@ -113,56 +123,71 @@ powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases prek is published as Python binary wheel to PyPI, you can install it using `pip`, `uv` (recommended), or `pipx`: -```console -pip install prek - -# or - + +```bash +# Using uv (recommended) uv tool install prek -# or +# Using pip +pip install prek +# Using pipx pipx install prek ``` + +
Homebrew + ```bash brew install prek ``` + +
mise + To use prek with [mise](https://mise.jdx.dev): ```bash mise use prek ``` + +
Cargo + Build from source using Cargo (Rust 1.89+ is required): ```bash cargo install --locked --git https://github.com/j178/prek ``` + +
GitHub Releases -prek release artifacts can be downloaded directly from the [GitHub releases](https://github.com/j178/prek/releases). + +Pre-built binaries are available for download from the [GitHub releases](https://github.com/j178/prek/releases) page. + +
GitHub Actions + prek can be used in GitHub Actions via the [j178/prek-action](https://github.com/j178/prek-action) repository. Example workflow: @@ -180,13 +205,16 @@ jobs: ``` This action installs prek and runs `prek run --all-files` on your repository. +
+ If installed via the standalone installer, prek can update itself to the latest version: ```bash prek self update ``` + ## Acknowledgements diff --git a/docs/hooks.py b/docs/hooks.py new file mode 100644 index 00000000..ab8a63b7 --- /dev/null +++ b/docs/hooks.py @@ -0,0 +1,32 @@ +import re + +def on_config(config, **kwargs): + """Read raw `site_url` from mkdocs.yml and store in `config._prek_docs`. + + This is needed because Mkdocs https://prek.j178.dev to http://127.0.0.1:8000 + when serving locally. + """ + + mkdocs_file_path = config['config_file_path'] + with open(mkdocs_file_path, 'r') as f: + for line in f: + if line.startswith('site_url:'): + config._prek_docs = { + 'site_url': line.split('site_url:')[1].strip() + } + break + return config + +def on_page_markdown(markdown, **kwargs): + """Convert absolute URLs like https://prek.j178.dev/installation into + relative paths like installation.md for local serving to avoid duplication + of content. + """ + site_url = kwargs['config']._prek_docs['site_url'] + + def replacement(match): + url = match.group(0) + path = url.replace(site_url, '').rstrip('/') + return f"{path}.md" + + return re.sub(rf'{re.escape(site_url)}([^)\s]+)', replacement, markdown) diff --git a/docs/index.md b/docs/index.md index 77d27ee8..8e2eb0b4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,74 +4,36 @@ prek -[pre-commit](https://pre-commit.com/) is a framework to run hooks written in many languages, and it manages the language toolchain and dependencies for running the hooks. - -*prek* is a reimagined version of pre-commit, built in Rust. It is designed to be a faster, dependency-free and drop-in alternative for it, while also providing some additional long-requested features. +{% + include-markdown "../README.md" + start="" + end="" +%} !!! warning "Not production-ready yet" - prek is not production-ready yet. Some subcommands and languages are not implemented. See the current gaps for drop-in parity on the [TODO page](./todo.md). + {% + include-markdown "../README.md" + start="" + end="" + %} - It's already being adopted by [some projects](#who-is-using-prek), please give it a try - we'd love your feedback! + {% + include-markdown "../README.md" + start="" + end="" + %} -## Features +{% + include-markdown "../README.md" + start="" + end="" +%} -- 🚀 A single binary with no dependencies, does not require Python or any other runtime. -- ⚡ About [10x faster](./benchmark.md) than `pre-commit` and uses only a third of disk space. -- 🔄 Fully compatible with the original pre-commit configurations and hooks. -- 🏗️ Built-in support for monorepos (i.e. [workspace mode](./workspace.md)). -- 🐍 Integration with [`uv`](https://github.com/astral-sh/uv) for managing Python virtual environments and dependencies. -- 🛠️ Improved toolchain installations for Python, Node.js, Go, Rust and Ruby, shared between hooks. -- 📦 Built-in implementation of some common hooks. - -## Quick Start - -1. [Install prek](./installation.md) -2. Replace `pre-commit` with `prek` in your commands -3. Your existing `.pre-commit-config.yaml` works unchanged - - ```console - $ prek run - trim trailing whitespace.................................................Passed - fix end of files.........................................................Passed - typos....................................................................Passed - cargo fmt................................................................Passed - cargo clippy.............................................................Passed - ``` - -## Why prek? - -### prek is way faster - -- It is about [10x faster](./benchmark.md) than `pre-commit` and uses only half the disk space. -- It redesigned how hook environments and toolchains are managed, they are all shared between hooks, which reduces the disk space usage and speeds up the installation process. -- Repositories are cloned in parallel, and hooks are installed in parallel if their dependencies are disjoint. -- It uses [`uv`](https://github.com/astral-sh/uv) for creating Python virtualenvs and installing dependencies, which is known for its speed and efficiency. -- It implements some common hooks in Rust, [built in prek](./builtin.md), which are faster than their Python counterparts. - -### prek provides a better user experience - -- No need to install Python or any other runtime, just download a single binary. -- No hassle with your Python version or virtual environments, prek automatically installs the required Python version and creates a virtual environment for you. -- Built-in support for workspaces (or monorepos), each subproject can have its own `.pre-commit-config.yaml` file. -- `prek run` has some nifty improvements over `pre-commit run`, such as: - - `prek run --directory ` runs hooks for files in the specified directory, no need to use `git ls-files -- | xargs pre-commit run --files` anymore. - - `prek run --last-commit` runs hooks for files changed in the last commit. - - `prek run [HOOK] [HOOK]` selects and runs multiple hooks. -- `prek list` command lists all available hooks, their ids, and descriptions, providing a better overview of the configured hooks. -- prek provides shell completions for `prek run ` command, making it easier to run specific hooks without remembering their ids. - -For more detailed improvements prek offers, take a look at [Difference from pre-commit](./diff.md). - -## Who is using prek? - -prek is pretty new, but it is already being used or recommend by some projects and organizations: - -- [Airflow](https://github.com/apache/airflow/issues/44995) -- [PDM](https://github.com/pdm-project/pdm/pull/3593) -- [basedpyright](https://github.com/DetachHead/basedpyright/pull/1413) -- [OpenLineage](https://github.com/OpenLineage/OpenLineage/pull/3965) -- [Authlib](https://github.com/authlib/authlib/pull/804) -- [pre-commit-crocodile](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile/) +{% + include-markdown "../README.md" + start="" + end="" +%} ## Getting Started diff --git a/docs/installation.md b/docs/installation.md index fa5540e2..231c3a55 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -8,15 +8,19 @@ The standalone installer automatically downloads and installs the correct binary ### Linux and macOS -```bash -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.sh | sh -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ### Windows -```powershell -powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.ps1 | iex" -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ## Package Managers @@ -24,48 +28,51 @@ powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases Install via pip, uv (recommended), or pipx: -```bash -# Using uv (recommended) -uv tool install prek - -# Using pip -pip install prek - -# Using pipx -pipx install prek -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ### Homebrew (macOS/Linux) -```bash -brew install prek -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ### mise -To use prek with [mise](https://mise.jdx.dev): - -```bash -mise use prek -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ## Build from Source -```bash -cargo install --locked --git https://github.com/j178/prek -``` +{% + include-markdown "../README.md" + start="" + end="" +%} ## Download from GitHub Releases -Pre-built binaries are available for download from the [GitHub releases](https://github.com/j178/prek/releases) page. +{% + include-markdown "../README.md" + start="" + end="" +%} ## Updating -If you installed via the standalone installer, you can update to the latest version: - -```bash -prek self update -``` +{% + include-markdown "../README.md" + start="" + end="" +%} For other installation methods, follow the same installation steps again. @@ -99,20 +106,8 @@ COMPLETE=powershell prek >> $PROFILE ## Use in GitHub Actions -prek can be used in GitHub Actions via the [j178/prek-action](https://github.com/j178/prek-action) repository. - -Example workflow: - -```yaml -name: Prek checks -on: [push, pull_request] - -jobs: - prek: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v5 - - uses: j178/prek-action@v1 -``` - -This action installs prek and runs `prek run --all-files` on your repository. +{% + include-markdown "../README.md" + start="" + end="" +%} diff --git a/docs/requirements.in b/docs/requirements.in index 215927c6..7a53594b 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -2,3 +2,4 @@ mkdocs>=1.6.1 mkdocs-material>=9.6.18 mkdocs-minify-plugin>=0.8.0 pymdown-extensions>=10.16.1 +mkdocs-include-markdown-plugin>=7.1.7 diff --git a/docs/requirements.txt b/docs/requirements.txt index 6a5da2df..ebf0f91a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,6 +4,8 @@ babel==2.17.0 # via mkdocs-material backrefs==5.9 # via mkdocs-material +bracex==2.6 + # via wcmatch certifi==2025.8.3 # via requests charset-normalizer==3.4.3 @@ -44,10 +46,13 @@ mergedeep==1.3.4 mkdocs==1.6.1 # via # -r docs/requirements.in + # mkdocs-include-markdown-plugin # mkdocs-material # mkdocs-minify-plugin mkdocs-get-deps==0.2.0 # via mkdocs +mkdocs-include-markdown-plugin==7.1.7 + # via -r docs/requirements.in mkdocs-material==9.6.18 # via -r docs/requirements.in mkdocs-material-extensions==1.3.1 @@ -86,3 +91,5 @@ urllib3==2.5.0 # via requests watchdog==6.0.0 # via mkdocs +wcmatch==10.1 + # via mkdocs-include-markdown-plugin diff --git a/mkdocs.yml b/mkdocs.yml index e6fc89cf..39887c0f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,6 +53,7 @@ plugins: - search - minify: minify_html: true + - include-markdown nav: - Introduction: index.md @@ -92,3 +93,6 @@ markdown_extensions: - tables - toc: permalink: true + +hooks: + - docs/hooks.py