git-check-assertions

🚧 Merely a proof-of-concept right now.

I recently wrote two blogs posts arguing that there might be some value in writing verifiable claims, i.e. assertions, inside of our commit messages:

• Should we start writing verifiable claims in commit message?
• Writing the steps to validate a test in the commit message

This is a simple verifier for such assertions.

You include a small bash script inside your commit messages, and git-check-assertions will then check out every commit (from the point that your branch diverged from main), and verify that the script in the commit message runs successfully.

⚠️ Only run this on repositories and branches that you trust, since the bash scripts in the commit messages can do whatever they want.

Installation

On most systems, clone this repository and add the bin directory to your PATH.

If you use Nix with flakes, you can simply add it to your program's devshell instead:

@@ -2,12 +2,18 @@
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    git-check-assertions = {
+      url = "git+https://codeberg.org/svenvanheugten/git-check-assertions.git?ref=main";
+      inputs.nixpkgs.follows = "nixpkgs";
+      inputs.flake-utils.follows = "flake-utils";
+    };
   };
   outputs =
     {
       self,
       nixpkgs,
       flake-utils,
+      git-check-assertions,
     }:
     flake-utils.lib.eachDefaultSystem (
       system:
@@ -17,7 +23,7 @@
       {
         packages.default = pkgs.callPackage ./default.nix { };
         devShells.default = pkgs.mkShell {
-          packages = [ ];
+          packages = [ git-check-assertions.packages.${system}.default ];
         };
       }
     )

Examples of commit messages

Assert that a commit builds:

```git-check-assertions
dotnet build
```

Assert that a commit builds and that the tests succeed:

```git-check-assertions
dotnet build
dotnet test --no-build
```

Assert that a commit builds, but that the tests do not succeed (assert_fails is a helper function included in git-check-assertions):

```git-check-assertions
dotnet build
assert_fails dotnet test --no-build
```

Assert that a commit builds, and that the tests fail with exactly the error that you expect:

```git-check-assertions
dotnet build
(assert_fails dotnet test --no-build) | grep "Invalid URL"
```

Assert that a commit builds, and that a specific change breaks the tests (as discussed here):

```git-check-assertions
dotnet test
sed -i '/crucial code/d' Main.fs
dotnet build
assert_fails dotnet test --no-build
```