Skip to content

Add diagnostic logging for checkpoint linking failures #135

@jcleira

Description

@jcleira

When Partio hooks run successfully but no Partio-Checkpoint trailer appears on commits, there is currently no way to diagnose why. Add structured debug logging at the overlap detection step so users can self-diagnose path mismatch issues.

Description

The most common silent failure mode in Partio is: hooks run, no error is reported, but commits never receive a Partio-Checkpoint trailer. This happens when stagedFilesOverlapWithContent returns false — typically because file paths don't match between what git staged and what the session recorded.

Add diagnostic logging in the post-commit hook path:

  1. In internal/hooks/ post-commit logic: when the overlap check fails, log at slog.LevelDebug the full list of staged file paths and the full list of session content file paths. This lets users running PARTIO_LOG_LEVEL=debug immediately see the mismatch.

  2. Warn on no-trailer commit: if the post-commit hook finishes without amending the commit with a trailer, emit a slog.LevelWarn message including the commit hash and the specific reason (no active session, overlap check failed, no checkpoint created, etc.).

Use the existing internal/log package — no new dependencies.

Why

Issues like entireio/cli#768 and the local equivalent show this is the most common support request: "hooks are installed and running, but nothing is being captured." Right now there is no way to self-diagnose without reading source code. A single debug log line would make this immediately actionable.

User Relevance

Users can run PARTIO_LOG_LEVEL=debug git commit -m "..." to see exactly why a checkpoint wasn't created, dramatically reducing the time to resolve configuration or path-mismatch issues.

Source

Inspired by entireio/cli PR #785 (changelog 0.5.2)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions