Merge pull request #203 from stepchowfun/pre-commit-test

Add documentation and a test for the pre-commit configuration

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         password: ${{ secrets.DOCKER_PASSWORD }}
     - uses: stepchowfun/toast/.github/actions/toast@main
       with:
-        tasks: build test lint release run
+        tasks: build test test_precommit lint release run
         docker_repo: stephanmisc/toast
         read_remote_cache: true
         write_remote_cache: ${{ github.event_name == 'push' }}

.gitignore

@@ -1,3 +1,4 @@
-# [tag:gitignore] Keep this in sync with [ref:excluded_input_paths].
+# [tag:gitignore] Keep this in sync with [ref:excluded_input_paths_1] and
+# [ref:excluded_input_paths_2].
 /artifacts/
 /target/

.pre-commit-hooks.yaml

@@ -1,5 +1,5 @@
 - id: tagref
-  name: tagref
+  name: Tagref
   description: "Tagref helps you manage cross-references in your code."
   entry: tagref
   language: rust

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.5] - 2024-02-16
+
+### Added
+- Tagref now provides a [pre-commit](https://pre-commit.com/) hook configuration.
+
 ## [1.8.4] - 2023-06-18
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tagref"
-version = "1.8.4"
+version = "1.8.5"
 authors = ["Stephan Boyer <[email protected]>"]
 edition = "2021"
 description = "Tagref helps you maintain cross-references in your code."

MAINTAINERS.md

@@ -31,5 +31,5 @@ The GitHub workflow will fail initially because the jobs which test the installe
 Releasing a new version is a two-step process:
 
 1. Bump the version in `Cargo.toml`, run `cargo build` to update `Cargo.lock`, and update `CHANGELOG.md` with information about the new version. Ship those changes as a single commit.
-2. Once the GitHub workflow has finished on the `main` branch, update the version in `install.sh` to point to the new release.
+2. Once the GitHub workflow has finished on the `main` branch, update the version in `install.sh` to point to the new release. Also, update the `rev` in the example pre-commit configuration in `README.md` to point to the new version.
 3. Create a pull request in the `Homebrew/homebrew-core` repository on GitHub to bump the version in [this file](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/t/tagref.rb).

README.md

@@ -123,6 +123,20 @@ cargo install tagref
 
 You can run that command with `--force` to update an existing installation.
 
+### Installation with pre-commit
+
+If you use [pre-commit](https://pre-commit.com/), you can install Tagref by adding it to your `.pre-commit-config.yaml` as follows:
+
+```yaml
+repos:
+- repo: https://github.com/stepchowfun/tagref
+  rev: v1.8.5
+  hooks:
+  - id: tagref
+```
+
+If you happen to have Rust installed, make sure it's up-to-date since pre-commit will use it to install Tagref. If you don't already have Rust, pre-commit will install it for you.
+
 ## Acknowledgements
 
 The idea for Tagref was inspired by [the GHC notes convention](https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Commentsinthesourcecode). [This article](http://www.aosabook.org/en/ghc.html) has more insights into how the GHC developers manage their codebase.

toast.yml

@@ -32,10 +32,19 @@ tasks:
       # - curl                  - Used for installing Tagref and Rust
       # - gcc-aarch64-linux-gnu - Used for linking the binary for AArch64
       # - gcc-x86-64-linux-gnu  - Used for linking the binary for x86-64
+      # - git                   - Required by pre-commit
+      # - python3-pip           - Used for installing and running pre-commit
       # - ripgrep               - Used for various linting tasks
       # - shellcheck            - Used for linting shell scripts
       apt-get update
-      apt-get install --yes curl gcc-aarch64-linux-gnu gcc-x86-64-linux-gnu ripgrep shellcheck
+      apt-get install --yes \
+        curl \
+        gcc-aarch64-linux-gnu \
+        gcc-x86-64-linux-gnu \
+        git \
+        python3-pip \
+        ripgrep \
+        shellcheck
 
   install_tagref:
     description: Install Tagref, a reference checking tool.
@@ -124,6 +133,44 @@ tasks:
       # tests that make assertions regarding the output [tag:colorless_tests].
       NO_COLOR=true cargo-offline test
 
+  test_precommit:
+    description: Check that the provided pre-commit configuration works.
+    dependencies:
+      - build
+    input_paths:
+      - .
+    excluded_input_paths:
+      - .git
+
+      # [tag:excluded_input_paths_1] Keep this in sync with [ref:excluded_input_paths_2] and
+      # [ref:gitignore].
+      - artifacts
+      - target
+    command: |
+      # Install pre-commit.
+      pip3 install pre-commit
+      PATH="$PATH:/home/user/.local/bin"
+
+      # Set up a Git repository.
+      git config --global user.email "[email protected]"
+      git config --global user.name "Tagref"
+      git config --global --add safe.directory "$PWD"
+      git init .
+      git add .
+      git commit --message 'First commit!'
+
+      # Create a pre-commit configuration.
+      cat << EOF > .pre-commit-config.yaml
+      repos:
+      - repo: .
+        rev: $(git rev-parse HEAD)
+        hooks:
+        - id: tagref
+      EOF
+
+      # Run the Tagref hook.
+      pre-commit run tagref --all-files
+
   lint:
     description: Run the linters.
     dependencies:
@@ -133,7 +180,8 @@ tasks:
     excluded_input_paths:
       - .git
 
-      # [tag:excluded_input_paths] Keep this in sync with [ref:gitignore].
+      # [tag:excluded_input_paths_2] Keep this in sync with [ref:excluded_input_paths_1] and
+      # [ref:gitignore].
       - artifacts
       - target
     command: |