Lightweight terminal-launched Git diff viewer. Two-panel GUI: coloured diff on the left, clickable file list on the right.
uv tool install . # installs gitr and gitr-serveOr just point an alias at the script directly (no install step needed):
alias gitr=~/path/to/gitr/gitr.pygitr # git diff (unstaged changes)
gitr master # git diff master (to working tree)
gitr --merge-base master # diff from common ancestor to working tree
gitr master HEAD # git diff master HEAD (committed only)
git diff | gitr # pipe a patch
gitr - # read stdin explicitly
gitr -p patch.diff # read from a patch filegitr diff ... is the same as gitr ...; a ref named like one of gitr's
commands (diff, export, comments, serve, help) needs it, or a
-- before it: gitr diff comments, gitr -- comments.
The review comments (the window's and gitr-serve's, in .gitr/review.json
of the repository) can be read and written without a window, so an agent
or a script can take part in a review:
gitr export master # all comments as markdown for an agent
gitr export --kinds bad,note master # only these kinds (also: gitr --export)
gitr comments list [--kinds bad] [src/] # one line each: id, path:line, kind, text
gitr comments list --full # with the whole texts (--json for scripts)
gitr comments add src/foo.py:42 "this leaks the handle" --kind bad
gitr comments add src/foo.py:42 - < note.txt # the text from stdin
gitr comments accept 3f9a2c1 # resolved: a good comment ending in "(accepted)"
gitr comments rm src/foo.py:42 # by id (any unique prefix) or path:lineA comment from add goes on that line of the file as it is in the working
tree, with no diff involved: the window and gitr-serve show it on that
line whether their diff has it added or unchanged (a line outside every
hunk is listed after the diff). list gives the lines as they are now,
flagged when a line's text changed, its file is gone, or it is a removed
line (a comment from a window or gitr-serve). A line takes one
comment from add; remove the old one first, or edit it in a window.
gitr-serve is the same diff view and review in a browser, for several
repositories and all their worktrees. It runs where the repositories are
(e.g. a remote machine with agents working in worktrees), in the foreground,
and needs no Tk.
gitr-serve ~/dev/repo-a ~/dev/repo-b # http://127.0.0.1:4487/
gitr-serve --port 9000 ~/dev/repo-a
gitr serve ~/dev/repo-a # the sameFrom a checkout, without installing: python3 gitr_web/server.py, with
--reload to restart on changes to gitr_web/server.py or gitr.py. The
page files under gitr_web/static/ are read from disk on every request, so
changes to them only need a browser refresh. The Monaco bundle under
gitr_web/static/monaco/ is built and committed; to move to another Monaco
version, change it in monaco/package.json and run
cd monaco && npm install && npm run build (Node is needed for that only).
With no repository arguments the list is read from
~/.config/gitr/projects.json:
{"projects": ["~/dev/repo-a", {"path": "~/dev/repo-b", "name": "b"}]}gitr-serve --print-config [repo ...] prints one for the repos given (or the
one you are in), ready to redirect into that file.
The server listens on localhost only and has no authentication, so reach it from another machine through SSH or Tailscale rather than exposing the port. Plain http to a remote address is not enough either way: browsers allow the clipboard (the copy buttons) and app install only over https or on localhost.
Through an SSH tunnel the page is on localhost:
ssh -N -L 4487:127.0.0.1:4487 remote-host # then open http://127.0.0.1:4487/(or LocalForward 4487 127.0.0.1:4487 for that host in ~/.ssh/config).
With Tailscale, tailscale serve puts it on https with a real certificate,
for your tailnet only. On the remote machine:
tailscale serve --bg --https 4487 4487
gitr-serve --allow-host remote-host.your-tailnet.ts.net
# then open https://remote-host.your-tailnet.ts.net:4487/The same port number as the server's own does not clash with it: Tailscale
listens on the tailnet address, gitr-serve on 127.0.0.1. A port of its own
also leaves the default one (443) to whatever else the machine serves;
tailscale serve --bg 4487 would take it over. tailscale serve status shows what is served where. The allowed name does not depend on the
port.
--allow-host names the address the browser uses: the server refuses other
names, so that a web page cannot reach it by pointing its own name at
127.0.0.1. It can be given several times, and the names can be kept in
projects.json instead (they apply also when the repos are given on the
command line):
{"projects": ["~/dev/repo-a"], "allow_hosts": ["remote-host.your-tailnet.ts.net"]}--print-config fills in the machine's tailnet name when Tailscale runs
there (tailscale status --json shows it as Self.DNSName).
Chrome can install the page as an app with its own window (the install icon
in the address bar, or menu > Cast, save and share > Install page). The app
belongs to the address it was installed from, port included, so keep the
tunnel on the same local port. To install apps from two machines, reach them
on different local ports (e.g. ssh -L 4488:127.0.0.1:4487 remote-host for
the remote one) or one of them through Tailscale; each app is named after its
server's hostname.
Pick a worktree with the project > branch button at the top left; the
base defaults to main / master and can be any ref. Clicking the base
field lists the default, the branch's upstream, the branches of the
project's other worktrees, the branch's recent commits (to review only
what came after one), and all branches and tags, each with how many
commits HEAD is ahead of (and behind) it; typing filters the list, and
Enter takes the text as typed (a commit hash, HEAD~3). The counts for the
current base are also shown next to the merge-base. The base is
remembered per worktree on the server (~/.local/state/gitr/web.json); a
worktree opened for the first time starts from the one last used in its
project (a base that is a commit rather than a branch or tag stays with
its worktree). The review leaves untracked files out; the commits pane
shows them (below). Wrapping long lines and collapsing re-indented ones
are set in the settings popup (the gear), per browser. Monaco is
bundled in the package, so the page needs no internet access.
When the worktree changes, a "worktree changed" note with a reload button appears in the top bar (the view never re-renders by itself). It says what a reload would bring, compared with the diff on screen: the new commits, and how many changed lines would appear and go, in how many files. After the reload those changes stay marked, so an agent's follow-up stands out from what was already reviewed: an orange bar at the left of each new changed line, an orange line where changed lines went, marks in the scrollbar and the minimap, and a bar on those files (and their folders) in the file list. A note in the top bar sums them up; its x clears the marks, which otherwise stay until the next reload (or another base or commit). The server keeps what the marks are measured against in memory, so a reload just after it restarted has none (the note says so). When gitr-serve restarts or its page files change, an "app changed" note in the top bar offers to reload the page, whose code may no longer fit the server's.
As in gitr, collapsing re-indented lines shows a removed and added line that differ
only in whitespace as one dimmed ~ line, and the right-click menu copies
the file path, path:line, or path:line with the line (or the selection
holding it) in a diff code fence for pasting into an agent's chat.
Comment on a line with the + that appears in the gutter on hover, or
right-click a line for gitr's one-click presets; click a comment to edit it.
Each comment has "accept" (it becomes a good comment ending in "(accepted)",
e.g. once the agent has dealt with it), "copy" (the comment with its location
and line, as "copy for agent" gives them) and "delete". The arrows next to
the comment count jump to the next and previous comment. Comments on files
not in the current diff are listed in a section after its last line. The
icons at the top of the left bar switch the sidebar between the changed
files and a list of all comments by file; clicking a comment scrolls to it,
and its x (on hover) deletes it. The file list's header has collapse all and
expand all, and "Reveal in file list" in the right-click menu shows the
file of that line in the list, opening its folders. "Find..." in the same
menu (or Ctrl+F in the diff) opens Monaco's find, starting from the
selected text. Ctrl+P (or the magnifier in the file list's header, or "Go
to file..." in the right-click menu) opens a list of the changed files to
jump to, as in VS Code, followed by the worktrees of all projects to
switch to: type parts of the name (srvpy finds server.py, wtag the
agent-1 worktree of wt), pick with the arrows and Enter or a click.
The project switcher takes the arrows and Enter too.
The box at the end of each row in the file list marks a file (or all the
files of a folder, or in the list's header all files) as viewed; a folder
folds from its chevron. The same box is in the diff's gutter at each file
header and (in a file of several hunks) each hunk header, where other
lines show the + that adds a comment, and right-clicking a line marks its file or
hunk. Viewed hunks are dimmed, marked grey in the scrollbar and shaded in
the minimap; a half-filled box is a file with some hunks viewed, and the
arrows in the list's header go to the next and previous hunk not viewed
yet. The marks are
kept per hunk in the worktree's .gitr/viewed.json, under the hunk's
changed lines rather than its place, so when an agent changes a hunk only
that one comes back unviewed (the reload note counts the viewed files a
reload changed), a hunk that only moved stays viewed, and a hunk viewed in
a single commit is viewed in the whole review too, while it is the same.
The third icon of the left bar shows the commits between the base and
HEAD as a graph, as gitk draws them, with the uncommitted changes and the
untracked files on top, and the base at the bottom.
Clicking one shows only that commit, as git show does (a merge against
its first parent), or only the uncommitted changes or untracked files.
Shift-clicking a second row (or the compare icon in the pane's header,
then two clicks) shows everything from one to the other combined, both
included (from the older commit's parent). "Uncommitted changes" and
"Untracked files" can be the newer end (the working tree, without and with
the untracked files), and "All changes" the older one (from the merge
base): shift-clicking from "All changes" to "Untracked files" shows the
whole review with the untracked files. The "All changes" row at the
top of the list, or the x on the note in the top bar, goes back to the
whole review. Right-clicking a commit copies its hash or subject, or makes
it the base, to review only what came after it. Comments can be read and written there too; they are
placed on that commit's version of the file, and the agent export always
describes the whole review and the untracked files (so a comment on a file
an agent created but did not add keeps its line).
Comments are stored in the worktree's .gitr/review.json, the same file a
gitr window uses, so a review can move between the two. "copy for agent"
puts the agent export on the clipboard; an agent in the worktree can read
the same with gitr export (or gitr comments list, see above). When review.json changes from outside the page (a gitr
window, another tab, an agent), the comments reload by themselves, a note
in the top bar says how many were added, edited and removed, and the added
and edited ones are flagged; the note's x clears the flags, which otherwise
stay until the next such change or another diff. Keep .gitr/ out of commits (e.g. in a global gitignore), or
agents may commit it.
Python 3.10+, Tkinter (included in most Python distributions). No other dependencies.
gitr-serve's icons are from Codicons by Microsoft, licensed under CC BY 4.0.