It creates a temp branch and then pushes two commits onto it, one for the currently staged changes and one for the currently unstaged changes. It then checks out the original branch and reverts the file by checking out the previous version and then merging it into the top commit. Next, it checks out from the temp branch the changes to the file and also cherry-picks the staged and unstaged commits. Finally, it calls reset a bunch to restore the staged and unstaged state. I'm sure there is some edge case where it's completely broken, but it works very reliably for me.

The reason I wrote it is that I have a workflow where I build up a single commit gradually by adding changes once they are "done" and ready for the final code review. I think most people instead create a series of commits, rather than one, and then squash-merge them all at the end.

What I like about my approach is that at any time I have: committed changes that are complete, staged changes that still need a little cleanup (e.g. documentation or tests), and then unstaged changes that are what I'm working on right now. I may also edit the commit message as I go along.

It's not common, but I use the extract command when I've committed something but decide I want to revert it in part or in whole because I found a different way. Again, having all my committed changes in the top commit helps.