Fix image files not re-copied during incremental rebuilds#14319
Open
worksbyfriday wants to merge 1 commit intosphinx-doc:masterfrom
Open
Fix image files not re-copied during incremental rebuilds#14319worksbyfriday wants to merge 1 commit intosphinx-doc:masterfrom
worksbyfriday wants to merge 1 commit intosphinx-doc:masterfrom
Conversation
When `force=True`, `copyfile` now overwrites the destination file even if its content is identical to the source. Previously, the `filecmp.cmp(shallow=False)` check caused the copy to be skipped when file contents matched, meaning modification times were never updated. This fixes the issue where image files referenced by documents were not re-copied during incremental rebuilds when only the image's mtime changed (e.g. replacing an image with a new version of the same size). Fixes sphinx-doc#14312 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
juniorcastro0152-hub
approved these changes
Feb 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #14312 — image files referenced by documents are not overwritten during incremental rebuilds when the image's modification time changes.
Root cause
copyfile(force=True)checksfilecmp.cmp(source, dest, shallow=False)before considering theforceflag. When source and destination have identical content (e.g.touchupdated the mtime but not the bytes), the function short-circuits and skips the copy entirely — even thoughforce=Truewas passed.During incremental builds,
copy_image_files()callscopyfile(..., force=True)for each image. The intent offorce=Trueis to always overwrite, but thefilecmp.cmpgate prevented this.Fix
When
force=True, skip thefilecmp.cmpcontent comparison and always copy the file (updating both content and modification times). This makesforce=Truebehave as documented: "Overwrite the destination file even if it exists."Test
Added
test_copyfile_force_overwrites_identical_contentto verify that:force, identical-content files are not re-copied (preserving the optimization)force=True, identical-content files are re-copied (mtime is updated)🤖 Generated with Claude Code