mirror of
https://github.com/j178/prek.git
synced 2026-04-25 02:11:36 +02:00
Deduplicate docs between README and MkDocs site (#792)
This commit is contained in:
Álvaro Mondéjar Rubio
committed by
GitHub
GitHub
parent
c2d611d9ac
commit
a95a3d0912
@@ -1,6 +1,8 @@
|
||||
/target
|
||||
|
||||
.cache
|
||||
__pycache__/
|
||||
site/
|
||||
|
||||
# Insta snapshots.
|
||||
*.pending-snap
|
||||
|
||||
@@ -11,19 +11,21 @@
|
||||
[](https://discord.gg/3NRJUqJz86)
|
||||
|
||||
</div>
|
||||
|
||||
<!-- description:start -->
|
||||
[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.
|
||||
<!-- description:end -->
|
||||
|
||||
> [!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/).
|
||||
> <!-- warning-p1:start -->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/).<!-- warning-p1:end -->
|
||||
>
|
||||
> It's already being adopted by [some projects](#who-is-using-prek), please give it a try - we'd love your feedback!
|
||||
> <!-- warning-p2:start -->It's already being adopted by [some projects](#who-is-using-prek), please give it a try - we'd love your feedback!<!-- warning-p2:end -->
|
||||
|
||||
<!-- features:start -->
|
||||
## 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.
|
||||
<!-- features:end -->
|
||||
|
||||
## 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:start -->
|
||||
## 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 <dir>` runs hooks for files in the specified directory, no need to use `git ls-files -- <dir> | 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 <dir>` runs hooks for files in the specified directory, no need to use `git ls-files -- <dir> | 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 <hook_id>` 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/)
|
||||
<!-- why:end -->
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -97,15 +102,20 @@ prek provides a standalone installer script to download and install the tool,
|
||||
|
||||
On Linux and macOS:
|
||||
|
||||
<!-- linux-standalone-install:start -->
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.sh | sh
|
||||
```
|
||||
<!-- linux-standalone-install:end -->
|
||||
|
||||
On Windows:
|
||||
|
||||
<!-- windows-standalone-install:start -->
|
||||
```powershell
|
||||
powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/download/v0.2.1/prek-installer.ps1 | iex"
|
||||
```
|
||||
<!-- windows-standalone-install:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
@@ -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
|
||||
|
||||
<!-- pypi-install:start -->
|
||||
```bash
|
||||
# Using uv (recommended)
|
||||
uv tool install prek
|
||||
|
||||
# or
|
||||
# Using pip
|
||||
pip install prek
|
||||
|
||||
# Using pipx
|
||||
pipx install prek
|
||||
```
|
||||
<!-- pypi-install:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Homebrew</summary>
|
||||
|
||||
<!-- homebrew-install:start -->
|
||||
```bash
|
||||
brew install prek
|
||||
```
|
||||
<!-- homebrew-install:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>mise</summary>
|
||||
|
||||
<!-- mise-install:start -->
|
||||
To use prek with [mise](https://mise.jdx.dev):
|
||||
|
||||
```bash
|
||||
mise use prek
|
||||
```
|
||||
<!-- mise-install:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Cargo</summary>
|
||||
|
||||
<!-- cargo-install:start -->
|
||||
Build from source using Cargo (Rust 1.89+ is required):
|
||||
|
||||
```bash
|
||||
cargo install --locked --git https://github.com/j178/prek
|
||||
```
|
||||
<!-- cargo-install:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>GitHub Releases</summary>
|
||||
|
||||
prek release artifacts can be downloaded directly from the [GitHub releases](https://github.com/j178/prek/releases).
|
||||
<!-- pre-built-binaries:start -->
|
||||
Pre-built binaries are available for download from the [GitHub releases](https://github.com/j178/prek/releases) page.
|
||||
<!-- pre-built-binaries:end -->
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>GitHub Actions</summary>
|
||||
|
||||
<!-- github-actions:start -->
|
||||
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.
|
||||
<!-- github-actions:end -->
|
||||
</details>
|
||||
|
||||
<!-- self-update:start -->
|
||||
If installed via the standalone installer, prek can update itself to the latest version:
|
||||
|
||||
```bash
|
||||
prek self update
|
||||
```
|
||||
<!-- self-update:end -->
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
|
||||
@@ -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)
|
||||
+25
-63
@@ -4,74 +4,36 @@
|
||||
<img width="220" alt="prek" src="/assets/logo_512.webp" />
|
||||
</div>
|
||||
|
||||
[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="<!-- description:start -->"
|
||||
end="<!-- description: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="<!-- warning-p1:start -->"
|
||||
end="<!-- warning-p1: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="<!-- warning-p2:start -->"
|
||||
end="<!-- warning-p2:end -->"
|
||||
%}
|
||||
|
||||
## Features
|
||||
{%
|
||||
include-markdown "../README.md"
|
||||
start="<!-- features:start -->"
|
||||
end="<!-- features: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 <dir>` runs hooks for files in the specified directory, no need to use `git ls-files -- <dir> | 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 <hook_id>` 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="<!-- why:start -->"
|
||||
end="<!-- why:end -->"
|
||||
%}
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
||||
+45
-50
@@ -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="<!-- linux-standalone-install:start -->"
|
||||
end="<!-- linux-standalone-install: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="<!-- windows-standalone-install:start -->"
|
||||
end="<!-- windows-standalone-install: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="<!-- pypi-install:start -->"
|
||||
end="<!-- pypi-install:end -->"
|
||||
%}
|
||||
|
||||
### Homebrew (macOS/Linux)
|
||||
|
||||
```bash
|
||||
brew install prek
|
||||
```
|
||||
{%
|
||||
include-markdown "../README.md"
|
||||
start="<!-- homebrew-install:start -->"
|
||||
end="<!-- homebrew-install:end -->"
|
||||
%}
|
||||
|
||||
### mise
|
||||
|
||||
To use prek with [mise](https://mise.jdx.dev):
|
||||
|
||||
```bash
|
||||
mise use prek
|
||||
```
|
||||
{%
|
||||
include-markdown "../README.md"
|
||||
start="<!-- mise-install:start -->"
|
||||
end="<!-- mise-install:end -->"
|
||||
%}
|
||||
|
||||
## Build from Source
|
||||
|
||||
```bash
|
||||
cargo install --locked --git https://github.com/j178/prek
|
||||
```
|
||||
{%
|
||||
include-markdown "../README.md"
|
||||
start="<!-- cargo-install:start -->"
|
||||
end="<!-- cargo-install: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="<!-- pre-built-binaries:start -->"
|
||||
end="<!-- pre-built-binaries: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="<!-- self-update:start -->"
|
||||
end="<!-- self-update: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="<!-- github-actions:start -->"
|
||||
end="<!-- github-actions:end -->"
|
||||
%}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user