-
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:
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.
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:
-
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. -
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 alluntracked
,unstaged
andstaged
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
andstaged
; 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.
-
Clone this repository to any location on the computer. For purposes of this text, we shall assume it has been placed at
~/diff-review
. -
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
andvrt
. These directly reference thediff-review
,view-review
, andview-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.