For a long time I would revert the whole branch without committing, then stage reverted chunks one at a time, clear the unstaged changes, and check for the bug or test failure. That worked alright, but it could often get confusing. It can be a little tricky to think in terms of staging reversions, and if the set of changes didn't fix the problem, or introduced a new problem, such as by not undoing some related changes, then I had to reset my git index and start over. Now I stage changes via diff files, instead of using Git's staging area. Here's how.

I start on a branch off the main development branch (main), then clear the working directory of uncommitted changes, either by committing them, stashing them, or discarding them. Then I create a reverse diff and save it to a file with git diff main... -R > changes.diff. That diff captures the changes that will undo the entire branch and make it identical to main. Since I only want to undo specific changes, I open a new file, say, candidate.diff, and copy sections of changes.diff over to it one at a time. Diff files are arranged as chunks within files, so it's easiest to copy across the full file then delete any unwanted chunks. Once I have the changes I want undone in candidate.diff, I apply it with cat candidate.diff | patch -p1, then check for the bug or test failure. If the problem isn't fixed, or if some additional reversions are needed, I try again by clearing changes with git checkout -- ., then I edit candidate.diff, run the new patch, and test again.

I've been using much smaller, more atomic commits lately, so git bisect works well, and it's been a while since I needed this workflow. Next time I do need it, though, I plan to write some helper scripts. For example, here's a small script to alleviate the confusion of patching reversions by first reverting the whole branch, then applying the positive diff:

#!/bin/bash

patch=$1

git diff main... -R | patch -p1
cat $patch | patch -p1

If you have other tips for troubleshooting changes on a Git branch, email me.

I briefly considered building my own web UI. I did that a few years ago when working on a team that hosted their code on BitBucket after I'd gotten used to GitHub reviews and treating review comments as notes to myself, coming back to delete questions answered by later code or clarifing thoughts before publishing anything. But before diving into a frontend application, I took a lesson from drafting pull requests locally and decided to see how far I could get with a diff, NeoVim, and some scripts.

A big advantage of reviewing code in a local text editor is that it can handle large diffs without requiring me to click "Load diff" on particular files or only showing one file at a time, which allows searching the whole set of changes for particular patterns, such as TODO comments or the catching of too broad exceptions. I can also exclude files in bulk, like generated code, documentation, and tests, depending on what my focus is for a given review. It's also a lot easier to review changes made since the last review, just by creating a diff with git diff <last-reviewed-commit>...HEAD.

But it's not a perfect experience, and I did a lot of customization to NeoVim to make it more diff-friendly. For starters, GitHub allows collapsing files. To support collapsing both files and chunks within a file, I defined a fold method and expression:

setlocal foldmethod=expr
setlocal foldexpr=v:lua.diff_fold_level()
setlocal foldtext=v:lua.diff_fold_text()
setlocal foldlevel=99

The Lua functions are implemented in Fennel:

(fn file-start? [line]
 (string.match line "^diff")

(fn chunk-start? [line]
  (string.match line "^@@"))

(fn _G.diff_fold_level [line]
  (let [line (vim.fn.getline (or line vim.v.lnum))]
    (if
      (file-start? line) :>1
      (chunk-start? line) :>2
      :=)))

(fn _G.diff_fold_text []
  (let [line (vim.fn.getline vim.v.foldstart)
        count (+ 1 (- vim.v.foldend vim.v.foldstart))
        level (_G.diff_fold_level vim.v.foldstart)
        prefix (case level
                 (where :>1) ""
                 (where :>2) "▶ "
                 _  "")]
    (.. prefix line " (" count " lines)")))

It's often helpful to jump from the diff to a particular file, to see the full context of the current code, so here's a command that uses the cursor's current position to find the right file name and chunk header, then calculate where to go and open it in a new tab.

Some chunks are not interesting and can be deleted from the diff, or whole files. Sometimes part of a chunk can be deleted but not others, so I also have a command to delete from the top of the chunk down to the cursor, which also updates the chunk header so jumping to the chunk's position in the file still works.

Often I start a review with the smallest changes, so here's a Babashka script that sorts the files in a diff by how many lines each file has. Using it for a while, I've added the ability to sort by how many additions each file has, or deletions, or how close the ratio of additions to deletions is, or whether the file name contains the word "test". And here's a script that moves the first file to the end of the diff, for cases where I don't want to delete the file but also don't want to review it yet.

Beyond shuffling code, I also needed to add comments. I opted to use markers in the first column of the dif, adding v and ^ to indicate what range of lines I'm commenting on, and x to indicate the end of a comment, like this:

diff --git a/old_file.txt b/new_file.txt
index 2a2e9f1..a48d7f5 100644
--- a/old_file.txt
+++ b/new_file.txt
@@ -1,1 +1,2 @@
-Notes on changes
+An ode
v
+To my code
^
👏
x

I add those markers with a couple of NeoVim commands that also put the highlighted lines into the copy register, which allows using them in an UltiSnips expansion, such as for making a suggestion. It's also trivial to adjust the range of lines being commented on by moving the markers, while to adjust the range of a comment on GitHub I have to copy a comment's content, delete the comment, select a new range, create a new comment, and paste the original comment.

I have a script to collect those comments as Markdown, with file and line metadata in the header of the fenced code block:

```diff new_file.txt -2 +2
+To my code
```

👏

Comments are separated by ---.

I write those comments to a file, tweak them if necessary, and create a pending GitHub review with this code. I keep that file of comments as a place to track what comments have been addressed and how, whether a requested change was made (and in what commit) or an answer was given for a question.

One final advantage of using NeoVim is how easy it is to define key bindings for all these actions, especially repeated actions using vim-repeat, making code review very fluid.

There are, however, some pitfalls. One is that it's easy to delete chunks that have comments. To avoid losing work, I added NeoVim functions that write any deleted or truncated code that have comments into a separate file, which I later use to create the Markdown comments. Another problem is that I don't see anyone else's comments while reviewing, so I occasionally make duplicate comments or miss explanations that aren't in the code. The most annoying pitfall, though, is not having the latest revision locally, causingy my comments to end up on the wrong lines of the current revision. That's part of the reason the script which creates the review only creates a pending review, so I can check it before submitting (though finding pending comments in GitHub's review UI is still a challenge).

I volunteered to review these large PRs because I'm always curious where my personal workflow hits a breaking point, and finding the friction gives me an opportunity to improve my tools in ways that benefit small tasks too. If you have further suggestions, or ideas on how to mitigate the pitfalls, email me!

The buttons on the right add shapes to the both grids, the upper grid showing the shape in Euclidean geometry, while the lower uses the Manhattan distance to draw the shape in taxicab geometry. The same control points are used for both plots. Drag points to change the shapes. To reset the plots, click the "Clear" button. To export a plot as an SVG, click "Export SVG" on the upper right of each plot.

The current implementation defines each shape as a two-dimensional signed distance function, where negative values denote the inside of a shape, positive values the outside, and zero values the boundary. To draw the boundary, it uses a simple marching squares algorithm. It's not particularly fast, especially not at the level of recursion needed for a smooth curve. Thus, when dragging points, you'll see the recursion level drop and shapes become less precise, which helps keep the visual responsive, though it's by no means as fast as one would hope.

Nor is the algorithm flawless. The boundary will occasionally spill into a square whose corners are all outside the shape, so the boundary inside that square is missing. It also misses cases where the boundary itself becomes two-dimensional, as it can for midsets and difference-based hyperbolas. But speed wasn't necessary for the few static illustrations I needed, and unhandled edge cases were easy to avoid.

I played with partial support for additional Minkowski distances, but while the shapes were interesting, their meaning was much harder to intuit, and broken edge cases were more common.

The original prototype, with all the same functionality, was about 500 lines of ClojureScript code. The public playground is slightly shorter, thanks to offloading some functions I commonly use to a library.

If you have suggestions for improvements, I'm happy to hear them.

These shapes are cousins of the ovals of Cassini, which are a constant product of distances to two foci. Here, though, one of the foci is a line, so half the shape wraps a focus that extends to infinity:

Similarly for taxicab geometry:

Both can be fully disconnected:

or fully joined:

Interesting things happen to the taxicab shape when the directrix is neither horizontal or vertical. Here it is at 45° to the axes:

With a sloped directrix, the shape becomes asymmetric (and, to my imagination, birdlike):

In Euclidean geometry, these appear to be a parabola:

That makes sense, since a parabola is the set of points equidistant from a focus and a directrix, or having zero difference in distances.

Interestingly, though, this definition can also produce a kind of double parabola:

Taxicab geometry has analogs for both:

The double parabola above just looks like two angled lines, and to see them as overlapping parabloas requires some foreknowledge of what you're looking for.

With the directrix at 45° to the axes, the shape still looks like a taxicab parabola with a similarly sloped directrix:

When forming a double parabola against a directrix at 45°, the shape becomes two right angles:

With a sloped line, some foreknowledge again helps to see the underlying pair of overlapping parabolas:

The first is a shape defined as a constant sum of the distances to a focus and a directrix:

In Euclidean geometry, these are lens-shaped but asymmetric:

Taxicab geometry's versions seem to be hexagonal approximations of the Euclidean shape:

The only other case seems to be the occasional pentagon:

As the name indicates, in Euclidean geometry this definition produces circles:

In taxicab geometry, it can produce a kite:

Or a trapezoid:

Given these two examples, and the fact that in Euclidean geometry circles of Apollonius are always circles, it's tempting to think that in taxicab geometry a circle of Apollonius is another way of defining a conic ellipse. But it's not. Here's a circle of Apollonius that isn't the cross section of a pyramid:

The jut from the lower corner of what would otherwise be a trapezoid is an interesting feature of circles of Apollonius in taxicab geometry. To understand why it appears, consider the case when the ratio of distances to each focus is 1. When that happens, the circle of Apollonius is equidistant from each focus, making the shape the set of points equidistant from both foci. In Euclidean geometry, that's a perpendicular bisector. Here are several circles between the same foci, with distance ratios approaching 1:

When the ratio is exactly 1, the circle's radius is infinite and the shape is a perpendicular bisector.

The same happens in taxicab geometry, where the set of points equidistant from two foci is a degenerate case of hyperbola. I typically call such a shape a "midset", since it's frequently not a single line nor perpendicular, more often a line with a pair of bends in it. It's also a circle of Apollonius with a distance ratio of 1:

The jut off one corner of some circles of Apollonius is how a growing shape transforms from a trapezoid into a midset.

Filling in the lower-left gap, I learned that the shape based on a ratio of the distances two foci is called a circle of Apollonius. However, I haven't found names for the shapes based on the sum, difference, or product of the distances to a focus and a directrix. (AI has suggested limaçon, which as far as I can tell is unrelated.) If you have suggestions, please email me.

Names or not, in the next few posts I'll illustrate each shape in both Euclidean and taxicab geometries.

One possibility might be to have a solar panel powering an electric motor that can counter the sheet's spin. A more in-kind solution would be to attach the TARS sheet to a second TARS sheet that has its reflectivity reversed, like this:

In the initial setup, only one sheet would be unfurled, allowing solar pressure to initiate spin:

Once the assembly is spinning fast enough, the extended sheet is pulled in, increasing its speed by conservation of angular momentum and approaching the limits of the material's tensile strength. At that point payloads can be released from both sheets, which are spinning at the same rate:

Retracted, the sheet no longer experiences solar pressure and spins faster and faster to the point it destroys itself. But it does continue to spin. To slow it down, we can unfurl the second sheet, which immediately reverts the spin to the slower rotation the assembly had before the first sheet was drawn in. Also, since the second sheet has swapped which side is reflective, solar pressure on the second sheet begins to counteract the spin of the whole assembly and slow rotation.

Once the assembly stops rotating, new payloads can be installed and the whole assembly spun up again to repeat the process.

The weakest point of this setup is likely the rod connecting the two sheets, which would have to be strong enough to withstand the twisting forces caused by the changes in angular momentum when sheets are pulled sheets in and let. The force of the counteracting spin, though, should be minor.

While this setup doesn't require a power source or electric motor to spin down the apparatus, it does require them to pull in the sheets.

If you have thoughts on this idea, please email me.

This video by the paper's author includes this animation of a TARS sheet unfolding in space and spinning up. Once it's spun up, reversing the unfolding process and folding the sheet back up would reduce the object's radius and thus increase its speed (usually demonstrated by a figure skater pulling their arms in to spin faster). One question, however, is whether that increase in speed is an increase in linear edge speed, or only in rotational speed.

In the example of a figure skater, rotational speed clearly increases, but does it increase only enough to maintain the same linear speed at the edge, spinning faster because an object on the edge is now traversing a smaller circumference? Wikipedia shows that for a point mass, angular momentum L is

With constant angular momentum but two different radii, we have

So radius and linear edge speed are inversely proportional, and drawing a point mass toward its center of motion would increase its edge speed. For TARS, this means that operators could increase the launch speed of a payload by re-folding the sheet back toward its center before releasing the payload. But that may not be viable in practice. Payloads would be released at the maximum speed allowed by the sheet's material, and pulling the sheet in and increasing rotational velocity would only increase stresses. Possibly the sheet could be pulled in by a material stronger than the sheet itself. Even without such a material, though, I can see two advantages to pulling in the sheet.

The first is that the sheet does not need to wait as long to spin up to its maximum launch speed. Solar pressure only needs to spin the sheet up to a fraction of that speed, and drawing in the sheet can increase the spin to the material's limits. When spin-up times are measured in years due to the relative weakness of solar pressure, being able to reach max speed in a fraction of that time makes a meaningful difference.

The second advantage of drawing the sheet in is that, once refolded, it would no longer have a surface to be acted on by solar pressure, stopping acceleration and preserving the sheet. Electric motors may be able to counter rotation, slowly spinning down the sheet to a speed at which new payloads can be installed. That would turn a TARS sheet from an expendable launch vehicle into a reusable one.

One caveat to all this is the moment of inertia of a TARS sheet. Radius and edge speed are only inversely proportional with a point mass spinning around a center, but the video shows a TARS sheet with a mass concentrated much closer to the axis of rotation. Drawing in such a sheet may not make that much of difference in edge speed, though it should still preserve the sheet.

If you have thoughts, I'm happy to hear them.