VideosGenerating File Comparison Reports Using Command-Line Scripts


Duration: 06:49

This video offers a demonstration of using scripts from a command-line tool to compare files and generating comparison reports in various formats.


00:00:07The purpose of this video is to demonstrate  how to generate various reports that show  
00:00:11the results of a file comparison using  scripts in a command line window.  
00:00:16I start with my command line navigated to the  scripts folder within the Oxygen installation  
00:00:21directory ... and I'll paste a command I  have prepared to simply compare two files.  
00:00:29You can see that the comparison  report was generated in the console  
00:00:33and by default, it's in YAML format. The report shows information such as the  
00:00:38total number of differences found, the  number of differents for each category,  
00:00:43and a list of document offsets that  identify the fragments with differences.  
00:00:49As you can see, the report is not very easy to  interpret in this format, but you can generate  
00:00:54the report in other formats such as JSON, XML, or you can generate the report in HTML format with  
00:01:00the modified text displayed side-by-side. Note that I can use the -help option to show the  
00:01:06script's specifications, including information about the supported options and arguments. 
00:01:12For example, if I want to change the  output format for my comparison report,  
00:01:17I can use the -out option to specify the  output format and the -outfile option to  
00:01:22specify the path for an output file where  the comparison results will be saved.
00:01:29So, I'll show some examples using the -out option,  
00:01:32and for this first one, I'll specify JSON as the  format. And, you can see that it generated the  
00:01:38comparison results in the command line window and in a JSON file format.
00:01:46Next, an example using HTML for the format.  
00:01:50And, you can see that the resulting report is formatted in HTML structure.
00:01:57Back in the help documentation, there's  a recommendation that if you choose the  
00:02:01HTML output format (as I did), it is recommended  that you choose to save the console to a  
00:02:07specified HTML file to view the comparison result in your preferred browser...
00:02:13and this is where the -outfile option  is helpful. So, I'll add it to the end  
00:02:18of my previous command, specifying a  path and name for an output file.
00:02:24Now, I can locate that specified  file and open it in my browser.
00:02:29It results in a user-friendly HTML report with  the differences presented and highlighted based  
00:02:35on the types of differences. I'll  quickly go over parts of the report  
00:02:39so you understand what you're seeing. There is a legend at the top that shows the  
00:02:43number of differences and includes  some filtering checkboxes. 
00:02:48I can hover over a checkbox to see a tooltip  with more information about the filter, and  
00:02:52if I select a particular filter, the  results are filtered accordingly. 
00:02:57The columns in the middle separate the  two files and also include symbols that  
00:03:01represent the type of difference. Now, I'll talk about some of the  
00:03:05specific differences. Notice that the  2nd block of difference seems to just  
00:03:10be a comment added by John and doesn't affect the actual document content. 
00:03:16Within the 3rd block of differences, there seems  to be some empty lines that were added by Mary,  
00:03:22but again, they didn't affect the actual content. 
00:03:25and the 4th block of differences seems  to just be reporting a difference  
00:03:28in the order of an attribute. I also want to point out that I can  
00:03:34refine the report by using filtering  options in the script itself. 
00:03:39For example, back in the help  documentation, you can see that  
00:03:43there are various supported options for  ignoring certain types of differences. 
00:03:48I'll paste a command that includes  some ignore options ... specifically,  
00:03:53to ignore differences in whitespaces,  comments, and the order of attributes. 
00:03:59Again, I can open the resulting output file in  my browser and now there are 3 less entries in  
00:04:05the results table, since I chose to ignore  those specific types of differences. 
00:04:11It's also possible to generate a  comparison report for a 3-way comparison.  
00:04:15In this case, I need to specify the  paths of the 2 files to be compared,  
00:04:20immediately followed by the path  to the base reference file. 
00:04:25I'll open the resulting report ...  notice that it's a bit different.  
00:04:30For example, the filters are a little  different since the context is different  
00:04:35than with the 2-way comparison. For a 3-way  comparison, the report is structured according  
00:04:38to the context of what you would  expect for a versioning system.
00:04:43Back in the help documentation, notice that  when using the HTML format for the -out option,  
00:04:49it supports an inlineCSS qualifier that results  in the HTML report being formatted with inline  
00:04:56CSS styling that is, for instance, more suitable for inserting it into the body of emails.  
00:05:04So, I'll paste an example of a command  with the inline CSS qualifier...
00:05:10And when I view the resulting  HTML report in the browser,  
00:05:14the CSS styling is now "in-line",  the filters are hidden and the  
00:05:18middle columns that normally include  the diff symbols are now hidden. 
00:05:24Just for context, you could see the  results of the "behind the scenes"  
00:05:29implementation by viewing the source of  the reports. I can right-click anywhere in the  
00:05:31reports and then select "View page source" and you can see how each report is constructed. 
00:05:38For 3-way comparisons, you also have the ability  to merge the modifications that are detected,  
00:05:43as long as there are no conflicting changes.  This is achieved by using the -merge or -mergeout  
00:05:49options. The -merge option results in the incoming  differences being merged into the 1st file  
00:05:55(again, unless there are conflicts, in  which case, the merge is aborted).
00:06:01However, if you don't want to directly affect  the content of the first file, you can use the  
00:06:06-mergeout option to instead create a new file  that includes the results of the merge operation  
00:06:11and it is saved in a specified directory. Now, I'll paste a command that oompares the file  
00:06:17that just resulted from the mergeout option with the 2nd file involved in the comparison. 
00:06:23I'll open the resulting file in my browser. And  if I compare it to the first results file, you can  
00:06:27see that there are no more incoming changes.As you can see, there are a lot of different  
00:06:36options that you have available to refine  the HTML reports to suit your specific needs.  
00:06:42This concludes the demonstration.  Thank you for watching.

Use Oxygen Feedback to ask us anything about this video.