Skip to content

Documentation: Add guide geared towards devs working in prek-enabled repositories #2116

@Feuermurmel

Description

@Feuermurmel

There's a lot of documentation on how to use the prek CLI, how to configure it via prek.toml and .pre-commit-config.yaml, how to develop hooks, etc. But I can't find any good documentation geared towards developers that work in repositories that use prek, but that don't necessarily edit its configuration (same for pre-commit for that matter).

I'm thinking of a guide that could be linked to from a repository's README that explains how to set up prek for working on the repository and how to handle different scenarios (e.g. when a commit fails due to a hook).

I think it would be great if prek's documentation at https://prek.j178.dev included a guide that documents the following items:

  • Setting up a repository that already uses prek (installing prek, prek install).
  • Explain what happens when running git commit.
  • What to do when a commit fails because a hook failed (i.e. look at error message, fix problems, re-add files, and try to commit again).
  • What to do when a commit fails because a hook edited a file (i.e. optionally look at diff, re-add files, and try to commit again.).
  • Mention some additional tips (e.g. prek run, git commit --no-verify).
  • Optimally, the explanations would contain some example terminal sessions, so that users know what to expect and where to look for.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions