The story of building Superlog (previously SmallPR)
How I go from a complete git n00b to building a git GUI that I preferred over all other alternatives
Hi, My name is Yu-Chien Chan, the creator of Superlog.
I created this app because I’ve been struggling with git a lot. I struggled so hard that I laid down on the floor feeling utterly defeated and cursing git multiple times while using git.
My world as a software engineer
You probably think I’m terrible at software engineering if I suck at git. How can someone survive the Tech industry while not knowing how to use git!?
But on the other hand, I’m a very tech-savvy guy graduating with a CS background from top universities in Taiwan and United States. I got my first job working at Facebook and worked there for 6 years. I got promoted twice. I mentored many interns and junior developers. I shipped thousands of commits and reviewed thousands of them for other people. I pride myself as a software engineer shipping concise, high-quality code. And my code review helped other people move fast and shipped high-quality code as well!
It turns out that Facebook internally has this nifty little UI that abstracts away the version control system from me. It allows me to perform all the commands I need through a simple UI that focus on what job needs to get done. It was so easy to use that I can teach any new employee in 10 minutes. And then they will also be able to just forget about the version control system completely.
In fact, I never encountered anyone who messed up with their source tree in the past couple of years. And I never had to think about the version control system at all.
For people who are interested in what our source tree would look like: it's an incredibly clean main branch. There is no “merge” commit. Every commit in the main branch has a single parent. I think what’s more impressive is that it is a monorepo where thousands of engineers ship thousands of commits each day.
Roaming outside the FAANG bubble
Earlier this year, my younger brother founded this startup that got accepted into YCombinator. They are just a couple of young engineers in their 20s without much industry experience, and I thought I could help.
Their setup was pretty straightforward with git and GitHub. Their CTO reviews and merges PR. They didn’t bother to enforce PR reviews because other people weren’t committed to the main branch directly.
I used git in college, so I have the basic ideas, even though it was 6 years ago. I assumed the workflow I’m used to at Facebook is also what the world is using. So I quickly cloned the codebase, made some trivial changes, and shipped.
And man, that was just the start of the many frustrations I’ve had with git.
First of all, I commit to the main branch because that’s the default option with git. When I tried to sync with the remote by pull and then push, I immediately messed up everyone’s source tree with the weird “merge” commit. I tried to “undo” my changes. But that added another “revert” commit on top of the main branch and messed things up even further.
I quickly grabbed my girlfriend, who has been using git daily for her job, to help me undo my mess. She opens my terminal and executes some weird git command I don’t even remember and fixed everything. She explained some of the git commands to me, but all I could think of at that moment was just how shitty git and GitHub were in allowing me to shoot myself in the foot so damn easy and quick.
The real-world problem of git for me
After I learned my lesson of creating a branch first and merging with “rebase” instead of “merge,” I quickly encountered another problem.
I was working on adding a debug tool to the codebase to do some refactoring. The workflow I’m used to at Facebook would look something like this:
- Send the first PR #1: Add debug tool
- While waiting for PR #1 to get reviewed and merged, I branch off #1 and continue my work of refactoring
- Send a second PR #2 based on #1, with my refactoring work
- Address some feedback on #1, wait for another review
- Continue to work on more refactoring that’s branching off #2
- Send a third PR #3 based on #2, with more refactoring work
- Merged #1 to main
- Address feedback on #2 and wait for review
- Merged #2 to main
- Address feedback on PR #3 and wait for review
- Merged #3 to main.
This workflow enables me not to get blocked by reviewers at any time. And every little PR I send out during the process is an incremental step that is easy to review and mergeable. It dramatically reduces the possibility of merge conflict because I’m merging the bottom stack of the PR as soon as they get approved. The differences between my latest work and the main branch are minimal.
At Facebook, we called this “Stacked Diff” workflow, and everyone is using it because it makes staying unblocked, shipping changes, and reviewing code all so straightforward. And that nifty little UI I talked about earlier is also optimized for this workflow.
I explained this workflow to my girlfriend and asked what’s the equivalent in the git and GitHub world. And I was told that there’s none. I should just either
- Ask for a quick review for PR #1 and wait for it to merge before I work on the rest.
- Lump PR #1~3 together into just 1 PR.
The first one was not acceptable because my brother’s CTO and I had a huge timezone difference. And the second one, from my own experience, is only going to slow down the code review process. (See my other post talking about this)
In search of solutions
So I went off searching for solutions. I found a few CLI tools specifically designed to enable stacked pull request workflow: gh-stack, ghstack, spr, git-town, and graphite-cli. So I think the workflow is possible on git and GitHub. But after trying out all those CLI solutions, none of them clicks. And more importantly, they all make me feel like I need to be an expert in git to dare try those things out.
I also tried a bunch of git GUI, such as GitHub Desktop, SourceTree, SublimeMerge, Tower, and GitKraken, VS Code extensions, but no luck.
In the process, I did figure out the vanilla git commands needed to perform this Stacked Pull Request workflow. But it was so tedious and error-prone that it’s not acceptable even for me to bear with it.
So there I was, without a solution, staring at that little nifty UI on my work computer, wondering if I could ever decide to take a productivity hit and work at a company without that piece of UI. In addition, I also genuinely believe a codebase developed with the Stacked Pull Request workflow will be healthier and easier to understand in years to come. Because I’ve been benefiting from people using this workflow since 5+ years ago, that makes it easier for me to understand the legacy code.
I hope Facebook would open-source this thing, but it was integrated with our version control system that’s not git and with our own code review/DevOps platform. I see very little incentive for Facebook to make it work on git/GitHub and open-sourced it.
Eventually, the idea that an engineering best practice I embraced fully and loved for years would not be there if I left Facebook is too frightening. So I decided to build this myself.
Coincidently, I have a 6 weeks sabbatical lined up starting mid-March. My original plan was to travel around the world. But this feels more important.
I quickly got an MVP working in a week and another 2 weeks polishing it up. I can now perform my Stacked Pull Request workflow with only some bearable friction! 😆
I launched it prematurely to see how excited people outside of Facebook were about this, and there are only very few. After talking to many of my engineering friends, I guess I have a lot of user education work ahead if I want to get some real traction. I also need to make the value proposition of this app clearer. And finally, I need to make the privacy and security part more transparent since people will need to enter their GitHub Personal Access Token into the app for it to work.
I addressed most of the user feedback I got around the functionality and polished the app further for the rest of my sabbatical. You can give the app a try today at my website:
Now that my 6 weeks sabbatical has ended, I’m proud to get this app off the ground.
Even though I have to work on this part-time from now on, I do intend to take it far. Ultimately, I want to live in a world where the engineering team can ship high-quality code fast and stay unblocked by default. And I’m afraid the current state of git / GitHub is just the opposite of that.
If you see the potential of SmallPR and want to help, feel free to join my Slack group and reach out to me personally!