🕰️ 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:
- You run the docs task.
- YARD regenerates HTML.
- Git reports changed files.
- You inspect the diff.
- 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
Or add it with Bundler:
bundle add yard-timekeeper
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)
Then generate docs with:
bin/rake yard
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
- GitHub: https://github.com/galtzo-floss/yard-timekeeper
- RubyDoc: https://www.rubydoc.info/gems/yard-timekeeper
- Docs: https://yard-timekeeper.galtzo.com
yard-timekeeper v0.1.0 is available now.
🕰️ May your docs be fresh, and your diffs quiet.
