DEV Community

Cover image for yard-timekeeper: Stop YARD Timestamp Churn in Checked-In Docs
Peter H. Boling
Peter H. Boling

Posted on

yard-timekeeper: Stop YARD Timestamp Churn in Checked-In Docs

#ruby #rubygem #yard #opensource

yard-timekeeper logo

🕰️ I just released yard-timekeeper v0.1.0, a small RubyGem for Ruby projects that check generated YARD HTML into git.

It solves a very specific kind of documentation noise: timestamp-only churn.

The Problem

If your project publishes generated YARD documentation from a checked-in docs/ directory, you have probably seen this:

  1. You run the docs task.
  2. YARD regenerates HTML.
  3. Git reports changed files.
  4. You inspect the diff.
  5. The only change is the footer timestamp.

That is not a documentation change. It is build noise.

For projects that keep generated docs under version control, this creates unnecessary diffs, noisier pull requests, and extra review work. It also makes it harder to notice when documentation actually changed.

What yard-timekeeper Does

yard-timekeeper runs after YARD generates HTML and checks tracked files under docs/**/*.html.

If a file's only change is the generated footer timestamp, it restores that file from git.

If the page has real content changes, it leaves the file alone.

The goal is not to hide documentation changes. The goal is to remove timestamp-only churn while preserving the signal that matters.

Install 

gem install yard-timekeeper
Enter fullscreen mode Exit fullscreen mode

Or add it with Bundler:

bundle add yard-timekeeper
Enter fullscreen mode Exit fullscreen mode

Configuration

The supported workflow is through rake yard, so the post-process hook can run after YARD finishes.

In your Rakefile or documentation task setup:

require "yard/timekeeper"

Yard::Timekeeper.install_rake_tasks!(:yard)
Enter fullscreen mode Exit fullscreen mode

Then generate docs with:

bin/rake yard
Enter fullscreen mode Exit fullscreen mode

No .yardopts plugin entry is required for this integration. If you were experimenting with --plugin timekeeper, remove it for this workflow and use the rake integration instead.

Behavior

yard-timekeeper is intentionally conservative:

  • It only post-processes docs/**/*.html.
  • It only restores files already tracked by git.
  • It only restores files whose diff is timestamp-only.
  • It preserves real generated documentation changes.
  • It can be disabled with YARD_TIMEKEEPER_DISABLE=true.

That means new documentation pages, deleted pages, and pages with real content edits remain visible to git.

Why This Exists

I maintain a lot of Ruby gems, and many of them publish YARD docs from checked-in HTML. I want documentation generation to be repeatable without filling commits with timestamp changes.

Small tooling like this is not glamorous, but it improves the daily maintenance loop. Cleaner diffs mean easier review. Easier review means fewer mistakes.

Links

yard-timekeeper v0.1.0 is available now.

🕰️ May your docs be fresh, and your diffs quiet.

Top comments (0)