what does git branchless undo do when it hides a commit?

[jvns]

I tried to make a commit and then undo it with git branchless undo, but I can't figure out what changes the undo operation made to my repo -- it looks exactly the same to me as before the undo. Here are the exact commands I ran and the results.

It says that it's "hiding" a commit, but as far as I can tell, there's no actual change to my commit graph -- refs/heads/main is still pointing at the exact same commit, and the output of git log --oneline is the same as before the undo operation.

$ git commit -m'test commit'
branchless: processing 2 updates: branch main, ref HEAD
branchless: processed commit: b265735 test commit
[main b265735] test commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test.txt
$ git log --oneline
b265735 (HEAD -> main) test commit
b004719 start
$ git branchless undo
Will apply these actions:
1. Hide commit b265735 test commit

Confirm? [yN] y
Applied 1 inverse event.
$ git log --oneline
b265735 (HEAD -> main) test commit
b004719 start
$  git sl
* b265735 Julia Evans HEAD -> main
|     test commit
|
* b004719 Julia Evans
      start

some notes:

• I'm running git branchless v0.8.0
• I ran git branchless init to set it up
• I did all of this in a brand new git repository

[arxanas]

When using git-branchless, you should prefer to use git branchless smartlog instead of git log --graph, because it will take into account git-branchless-specific information such as hidden commits.

• In this case, git branchless smartlog should show that the current commit is marked as "hidden" with an X, which would make it clearer that something happened, even though it's not exactly what you wanted.

Tragically, it looks like you already had a git sl alias that invokes git log --graph (?), so git-branchless did not install its own version for you.

• To rectify this, you can remove your own alias and re-run git branchless init, or simply update your existing alias yourself.
  • Note that git-branchless aliases installed with git branchless init are installed per-repo rather than globally.
• I forget if git branchless init warns about this or not. Either way, it's probably not obvious that it would be problematic.

Information about hidden/rewritten commits is not stored in Git directly, and is instead stored out-of-band in a git-branchless-specific on-disk database. git-branchless and Git have different conceptions about what commits are "visible":

• In Git, normally only commits reachable from a branch or references would be considered "visible" (by convention).
• In git-branchless, it's possible to have additional visible commits beyond the above. The information about those commits being visible has to be stored out-of-band somehow.
• (In Jujutsu, I believe that the visible "heads" are stored as non-branch refs in the repo, but they are not meaningful to most Git tooling.)

What you probably would have liked/expected to happen would be an undo operation consisting of a few steps, something like these:

• "hiding" the commit
• updating HEAD/switching to a different commit
• updating the currently-checked-out branch
• possibly restoring from a working copy snapshot

The best way for you to do this in your current setup is to do an interactive undo with git undo -i and go back in time (press the left arrow key) until the commit graph looks correct (i.e. the current commit will be start and the test commit won't appear at all).

---

git-branchless can't undo the full logical operation in this case because it's informed about these operations individually, and it doesn't know which consecutive real operations are part of the same logical operation. You can alias git to git-branchless wrap -- like in Step 3 of the installation instructions, and it should be able to coalesce all those events into a single undoable transaction.

• If I had run git undo -y in my setup (with wrapped transactions), I would have expected it to hide the commit, update the branch, and also leave the unstaged pre-commit changes in the working copy.

---

The invocation you performed could probably inform the user more effectively that transactions aren't being grouped.

• It could probably detect if it wasn't invoked inside git-branchless wrap -- and warn if so.
• Originally, git undo only operated interactively, so it was a little clearer what the commit graph would look like, and it was a little more obvious that one should go back in time further to get the desired results.
• The non-interactive mode doesn't show the resulting commit graph (or warn that transactions are not being wrapped), so, just from the textual descriptions, it's easy to not understand that "hiding" the commit isn't sufficient.

[jvns]

Thanks so much for the detailed explanation! I felt like I was missing something obvious and I guess my git sl alias was that thing :). Now I understand git branchless a lot better, I really like it.

One more question about the interactive undo mode -- I'm looking at the events that happen around a commit, and it looks like in event 52, 1e2032d is checked out, but the commit 1e2032d is created in event 53, after the checkout. This seems in line with how undos work (first it hides the commit, then it moves the branch back, which makes sense) but the causality is a little confusing to me. Is the situation that those events actually happened in the opposite order, but then git branchless reordered them to support a better undo UI?

(also I apologize if all this is already covered in the wiki somewhere, I couldn't find anything)

┌─────────────────────────────────────────────────────────────────┤ Events ├────
│Repo after transaction 39 (event 52) (2s ago). Press 'h' for help, 'q' to quit.
│1. Check out from 9f86f93 test 5                                               
│               to 1e2032d test 6                                               
└───────────────────────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────────┤ Events ├──────
│Repo after transaction 40 (event 53) (3s ago). Press 'h' for help, 'q' to quit. 
│1. Commit 1e2032d test 6                                                        
│                                                                                
└────────────────────────────────────────────────────────────────────────────────

[arxanas]

I suspect the events actually happened in the opposite order of what you might expect, in terms of the ordering of Git hook calls. Normally, when you commit to a branch, you have to create the commit object and update the branch reference to point to the new commit. If you are the writer of a post-commit hook, you probably want to observe the repository after the branch has been updated (quite reasonably, as you might want to know which branch is checked out, etc.). So Git waits until the branch has been updated before invoking the post-commit hook. (The branch update itself is tracked by the reference-transaction hook.)

• It's worth noting that the post-commit hook does not receive any information about what commit was just created, so you have to check HEAD and assume that it refers to the new commit. This is arguably a design flaw, although there are very few workflows where it matters. It does mean that git-branchless never invokes the user's post-commit hook when a commit is created in-memory rather than on-disk via a git command, as you would have to check out that commit just for the post-commit hook to run, which would be slow and largely defeat the purpose of in-memory operations.

Admittedly, undoing just the "commit" event without the "checkout" event is unlikely to be what you wanted as a user. If you use git-branchless wrap, then the two steps should appear as part of the same transaction, and you would be able to undo them together as an atomic unit.

[jvns]

thank you! I've been trying to understand git hook ordering so this is really helpful.