Software Prerequisites

• 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

Supported Operating Systems

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

Viewer Managers

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.

Supported Viewers

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.

Description / Terminology

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.

Usage

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.

Examples

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

Set aliases in your shell environment

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

View a single committed change

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.

Combine and view multiple changes

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

View uncommitted changes

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

Clean up repository

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

Advanced Usage

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.