TL;DR: Use git diff to view and store the set of changes in overridden template files.

There are many things I really like in WordPress development. Template overriding is not one of them. It is a feature of child themes that comes with WordPress itself: A template file of the parent theme can be overridden by a child theme. If the same template file (page.php, archive.php, et cetera) exists in a parent and child theme, WordPress will use the child theme one and ignore the parent’s template. I suggest you try literally everything else before doing this. But people make mistakes and all projects have to make tradeoffs, so sometimes we have to deal with ugly things. What should we do with ugly code? Document it well. Of course, if the effort required to document it is greater or equal to the effort required to refactor it, then clean things up by all means. But in the case of overridden templates I have found a really simple way to improve the development experience with automatically generated documentation.

Git all the things!

The idea is to use the diff command of Git 1 to view all changes of a template file between parent and child theme. It does not matter if one of the files is outside of the git repository. I usually encounter this with child themes where the child template is the Git repository I am working in and the parent template is outside of it. That’s okay, Git will find all changes and create a diff view for them. Let’s say I want to do this for the archive.php template file. In my child theme, I would run the following:

git diff ../parent-theme/archive.php ./archive.php

This will display the diff view directly in the terminal. Initially I simply took a screenshot of the diff and added it to documentation. This is pretty stupid in a number of ways and I just learned how to do it better today. A screenshot can only capture so much, plus storing raw text as an image is just a complete waste of resources. So what do we do? We can capture and store the diff content in a text file. This way it will be complete and can be viewed anytime in the terminal. And yes, we can store the nice green and red highlighting colors too! Here is how:

git diff --color ../parent-theme/archive.php ./archive.php > docs/archive-diff.txt

Now the complete diff is stored in this text file. If you want to look at the diff, you can view it with cat 2 to get nice highlighting colors and diff syntax:

cat docs/archive-diff.txt

That is it! Simple enough. To make this technique as effective as possible I would try to automate the diff generation somehow. It would probably make most sense as a Git hook to make sure documentation is always up to date. I have been doing it manually for now, but will try to automate it the next time I work in a project with overridden templates!

Afterthought: You might wonder why store the diff at all? It is redundant information that can be generated whenever needed by running the diff command. That is true, but requires anyone who wants to check documentation for overridden templates to checkout the repository and have a copy of the parent theme. If this is the case anyway, I guess you would not want to store the diff at all.