• python3

  An executable named python3 must be installed and on ${PATH}.

• pyqt6

This Python module must be installed to be able to generate the Tcl/Tk-based menu used for viewing the generated diffs:

If this module is not installed, the view-review will stop with an error indicating such.

On Ubuntu, this can be satisfied with:

sudo apt install python3-pyqt6 

• Linux
• MacOS (basic functionality)
• Windows (proof-of-concept functionality)

There are two managers that allow viewing of diffs in this package:

1. view-review-tabs (vrt)

This tool shows a single window, with the list of files contained in the change -- including the commit message, if one is present -- in the sidebar. Clicking on an element in the sidebar loads it into a tab in the view area.

This tool only provides viewing diffs with the built-in diff engine. This engine is sufficient, but will be undergoing improvements.

The diff navigation within the tab is identical to view-review's Claude-QT viewer.

2. view-review (vr)

This tool shows a menu of all the files in the change. Clicking on an element in the list will open the base and modified files in a separate window using the selected diff viewer.

Ultimately, the Claude-QT engine will be removed from this diff manager, as all of its functionality is now subsumed by view-review-tabs.

This system currently supports the following side-by-side diff viewers, selectable from the Viewer menu.

• Claude-QT (Claude-generated, experimental, pyqt6)
• Emacs
• Meld
• TkDiff
• Vim

If any of Emacs, Meld, TkDiff or Vim cannot be found in commonly-used install paths for that program, it will not be included in the Viewer menu.

Change is omnipresent in the software industry. To help you manage changes to source, this tool enables viewing of uncommitted and committed changes in a Git repository.

Before going further, let us take a moment to understand the terminology used herein to describe the constituent parts of a change. Each file contained in a change always has two components:

1. Base file

   The base file refers to the original file, before modifications have been made. In most cases, the base file comes from the SCM, but in some cases, such as an add, the base file does not exist in the SCM. When the base file does not exist in the SCM, and empty file is used in its stead.

2. Modified file

   The modified file, obviously, refers to the after-change file.

   For uncommitted changes, it usually refers to the change-containing on-disk file. But, for modification such as delete, an empty file will be used.

   For committed changes, the modified file usually comes from the SCM, but case where the modified file no longer exists, such as delete, an empty file will be used in its place.

There are two modes in which this tool can operate: uncommitted changes, and committed changes.

• Uncommitted Changes

  If no revision information (-c) is provided, diff-review will produce a review for for all untracked, unstaged and staged files.

  An uncommitted change includes all modified files, as well as untracked files, that are in the repository. By default, they will all be included in the generated review, but a command line option can disable reviewing of untracked files.

  For purposes of generating viewable diffs, there is no difference between unstaged and staged; the tool uses the current, on-disk, uncommitted content.

• Committed Changes

  If revision information (-c) is provided, diff-review will produce a review for all the files changed in the specified revision.

1. Clone this repository to any location on the computer. For purposes of this text, we shall assume it has been placed at ~/diff-review.

2. Load the aliases file.

   This alias file is for Bash users. Those using some other incompatible shell will have to provide their own translation. Any submissions will be gladly accepted.

   source ~/diff-review/scripts.d/aliases

   This will provide three aliases in your current shell environment: dr, vr and vrt. These directly reference the diff-review, view-review, and view-review-tabs programs respectively, bypassing the need to update ${PATH}.

   The examples below will use these aliases.

These examples with use emacs as the source of changes to review. Take the time now to go get a basic emacs source tree:

git clone https://github.com/emacs-mirror/emacs.git 

If you prefer to use the official site, it is here, but it is extremely slow:

git clone https://git.savannah.gnu.org/git/emacs.git 

As shown above in the Usage section, load the aliases into your shell.

The following command will generate diffs for a 25-year-old emacs change.

dr -c a3ba27daef3 

That command will produce the following output on the console:

diff-review: /home/thutt/review/default modify src/ChangeLog modify src/gmalloc.c Changes: committed [2 files, 249 lines] Viewer : vrt -R /home/thutt/review -r default Viewer : vr -R /home/thutt/review -r default Elapsed: 0:00:00.106696 

The lines beginning with Viewer are commands that can be executed to view the diffs.

vr 

Pressing Esc from both vrt and vr will quit.

The following command will generate diffs for a sequential range of emacs commits.

dr -c 4418a37c5df^..cb17a8bbf39 

That command will produce the following output on the console, which can be directly viewed by executing vrt or vr:

diff-review: /home/thutt/review/default modify admin/notes/unicode modify doc/lispref/modes.texi modify doc/lispref/parsing.texi modify doc/lispref/positions.texi modify lisp/comint.el modify lisp/dired-x.el modify lisp/emacs-lisp/easy-mmode.el modify lisp/emacs-lisp/ring.el modify lisp/international/mule-cmds.el modify lisp/international/ucs-normalize.el modify lisp/net/eww.el modify lisp/net/rcirc.el modify lisp/progmodes/gdb-mi.el modify lisp/progmodes/php-ts-mode.el modify lisp/subr.el modify lisp/time.el modify lisp/vc/log-edit.el modify lisp/vc/vc.el modify src/doc.c modify src/editfns.c modify test/lisp/comint-tests.el modify test/lisp/dom-tests.el modify test/lisp/international/mule-tests.el modify test/lisp/international/ucs-normalize-tests.el modify test/lisp/net/tramp-tests.el modify test/lisp/textmodes/ispell-resources/fake-aspell-new.bash modify test/lisp/textmodes/ispell-tests/ispell-aspell-tests.el modify test/lisp/textmodes/ispell-tests/ispell-hunspell-tests.el modify test/lisp/textmodes/ispell-tests/ispell-international-ispell-tests.el modify test/lisp/textmodes/ispell-tests/ispell-tests.el Changes: committed [30 files, 378 lines] Viewer : vrt -R /home/thutt/review -r default Viewer : vr -R /home/thutt/review -r default Elapsed: 0:00:00.987920 

This example will show how untracked, unstaged and staged changes are processed.

Execute the following:

touch untracked; cat README README >readme; mv readme README; git rm config.bat; 

Now, run dr, which will produce the console output:

diff-review: /home/thutt/review/default unstaged README delete config.bat untracked untracked Changes: unstaged [1 files, 130 lines] staged [1 files 384 lines] Viewer : vrt -R /home/thutt/review -r default Viewer : vr -R /home/thutt/review -r default Elapsed: 0:00:00.114457 

As ever, both vrt and vr can be used to view the changes.

Next, stage the README file and re-generate the diffs with dr.

git add README 

The console output will appear like this:

diff-review: /home/thutt/review/default staged README delete config.bat untracked untracked Changes: unstaged [0 files, 0 lines] staged [2 files 514 lines] Viewer : vrt -R /home/thutt/review -r default Viewer : vr -R /home/thutt/review -r default Elapsed: 0:00:00.114509 

Finally, make another modification to README to show how its state returns to unstaged after executing dr.

cp BUGS README 

The console output will look like this:

diff-review: /home/thutt/review/default unstaged README delete config.bat untracked untracked Changes: unstaged [1 files, 274 lines] staged [2 files 514 lines] Viewer : vrt -R /home/thutt/review -r default Viewer : vr -R /home/thutt/review -r default Elapsed: 0:00:00.113634 

Now that the examples are finished, you can delete the emacs clone.

Invoking either dr or vr with --help will show the current set options that the program takes. Using these options will allow more complex invocations -- such as naming the output, or putting it into a different directory location.

• Claude-QT (pyqt6)

  This viewer program was entirely generated through conversations with Claude.ai. When it is deemed to be working well-enough, it will likely become the default viewer, replacing TkDiff.

  The Help menu describes how to use the features of the program.