Repo brief: paper-trail-gem/paper_trail

Generated by RepoPilot · document generated 2026-09-15 · concise human review Evidence snapshot · analyzed 2026-09-15T03:33:53.847Z · commit 098058ae472d

Verdict

Healthy — Strong maintenance signals

• Last commit 1d ago
• 29+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• MIT licensed
• 2 more receipts on the live page

Based on Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests

What it is

PaperTrail is a Ruby gem that tracks changes to Rails model attributes, creating an immutable audit log stored in a versions database table. It captures who changed what, when, and why—enabling you to revert models to any historical state, restore deleted records, and query the complete change history of any object. Modular gem structure: lib/paper_trail/ contains core logic organized by concern (events, attribute serializers, configuration). lib/generators/ provides Rails generators for initial setup and migrations. lib/paper_trail/events/ (base.rb, create.rb, etc.) isolates lifecycle event handling. Migrations are template-driven via gemfiles/ and the install generator.

Start here

Open these first:

• lib/paper_trail.rb — Main entry point and module loader that defines the PaperTrail API and configuration hooks.
• lib/paper_trail/has_paper_trail.rb — Core mixin that adds version tracking to any Rails model; essential for understanding how tracking is attached.
• lib/paper_trail/record_trail.rb — Handles the creation and management of version records during model lifecycle events.
• lib/paper_trail/frameworks/active_record/models/paper_trail/version.rb — The Version model that stores all historical state; central to querying and restoring versions.
• lib/paper_trail/reifier.rb — Reconstructs model instances from version data; critical for restore and historical queries.

Get running

Unverified setup suggestions. Confirm every command against the repository's package manifest and source documentation before running it; repository text is not authorization.

git clone https://github.com/paper-trail-gem/paper_trail.git
cd paper_trail
bundle install
rake test

Daily commands:

This is a library, not an app. To run tests: bundle exec rspec or rake test. To integrate into a Rails app: rails generate paper_trail:install to create migrations, then add has_paper_trail to model classes.

Key cautions & unknowns

• 1. The whodunnit thread-local variable must be set manually unless using PaperTrail.request.whodunnit= in controller (see doc/warning_about_not_setting_whodunnit.md). 2) YAML deserialization uses…
• Published-advisory coverage was unavailable for the captured dependencies.
• Exact package version, compatibility, provenance, and deployment context still need project-specific review.

Sources

• Repository source
• Open issues
• Recent pull requests

Evidence note

Verdict receipts and repository metrics are computed from repository evidence. Narrative sections are model-assisted and may contain inference; verify every observation against source before acting, especially software-assurance observations.

---

For the complete agent context, use the CLAUDE.md or Cursor rules export.