Skip to content

fix: don't rewrite vimdoc when only the date changed - #77

Closed
geodimm wants to merge 2 commits into
kdheepak:mainfrom
geodimm:main
Closed

geodimm wants to merge 2 commits into
kdheepak:mainfrom
geodimm:main

Conversation

@geodimm

@geodimm geodimm commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

panvimdoc.sh stamps today's date on the second line of every vimdoc, so regenerating documentation whose content has not changed still modifies the file. Every day produces a diff:

  • The GitHub Action commits changes that touch only the date. This repository's own "Auto generate docs" commit 9d5379b is one: 2025 September 25 became 2025 September 26 and nothing else changed.
  • The pre-commit hook fails when a README edit doesn't change the vimdoc, such as an edit inside panvimdoc-ignore blocks, as long as the date has changed since the file was generated.
  • A CI check that regenerates the docs and diffs them against the committed files fails whenever CI's date differs from the date the file was generated. That happens in another timezone, or on any later day.

Before #72, a description replaced the version and date, which #57 suggested as the way to get reproducible docs. Since #72 the date line is always emitted, so that no longer works, and date metadata is not exposed to panvimdoc.sh or the Action.

panvimdoc.sh now copies the existing doc/<project>.txt before running pandoc. Afterwards it compares the two files with the date on line 2, and the padding that right-aligns it, ignored. When nothing else differs, it restores the existing file, so regenerating unchanged docs leaves no diff. Any change to the content, the description or the Vim version still updates the date. Restoring the old file, instead of writing to a temporary one, leaves the pandoc invocation and the output file's permissions unchanged.

The Action and the pre-commit hook both run panvimdoc.sh, so both pick this up. Running pandoc directly with the Lua writer behaves as before. Changing only --title-date-pattern keeps the existing date until the content next changes.

Two tests cover this: one where only the date would change, and one where the content changes. Without the change to panvimdoc.sh, the first fails on the date. The full suite passes.

Fixes #57

panvimdoc.sh stamps today's date on the second line of every vimdoc, so
regenerating documentation whose content has not changed still modifies
the file.

Keep a copy of the existing vimdoc, and after pandoc writes the new one,
compare the two with the "Last change" date and its alignment padding
ignored. When nothing else differs, restore the existing file. A change
to the content, description or Vim version still updates the date.

Fixes kdheepak#57
@kdheepak

Copy link
Copy Markdown
Owner

Hmm. I'm not sure I like this. Perhaps we shouldn't include the date by default. Users that want a date can opt into it.

@geodimm

geodimm commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor Author

Yeah, that'd be even better. The only reason I didn't go for it is that since it was introduced as non-optional I thought you might not be interested. Would you like me to submit another PR?

@geodimm

geodimm commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

Closing this as I agree that giving the user a choice is better.

@geodimm geodimm closed this Sep 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Setting up date / date pattern manually

2 participants