We electronically control revisions for this topic and deploy it directly online. Any copies you generate from the latest revision are uncontrolled. Ensure you refer to the latest revision online when possible.
Latest revision: /docs-as-code//2020/08/06/analyzing-document-changes.html
Analyzing document changes
We can use git-diff or a document lifecycle tool to analyze changes between any document versions.
Overview
For a complete list of all content changes, the easiest way to compare differences between versions internally is to use a document lifecycle tool such as GitLab or GitHub. If you need to produce a file to share externally, use the pretty-diff function. For more complex diff functions such as excluding file types, use pretty-diff. These workflows capture all changes to a repository, whether manually logged or not.
Compare via Gitlab
- In a repository, navigate to Repository > Compare.
- Select two tags/branches/commits to compare.
Once you run the compare, you can share the compare internally by copy/pasting the address from the address bar.
Export compare to a file
You’ll need to install pretty-diff via https://github.com/scottgonzalez/pretty-diff.
Run pretty-diff as you’d run git diff. For example, pretty diff v1.3 HEAD -- source/topics/electrical-specifications.rst. This will show differences between v1.3 of a document and the most recent draft content, for the electrical-specifications.rst topic. It will output the diff as an HTML website that you can save locally and share as you would with any file.
List common commands and define workflows for producing diff reports in the CHANGELOG.md file. See the link below for an example.
Example
The below is the output of running pretty-diff v1.3 v1.4. We can see where values were updated for v1.4 of this document. You can see the corresponding web GUI output via the link below.