The Real Git

2020-05-02

This post is for young developers like me, ditching GitHub/Lab for Gitea with a self-recognition as a hipster. There is a TL;DR at the bottom.

For too long have I held the incorrect belief that we needed a GitHub alternative that federates, and joins the fediverse using ActivityPub. Well, it could be a thing. Gitea is good, and I'd be pleased to see it get better by implementing AP.

Interface

Ask yourself: is a web app the only way to do issues/tickets, pull requests/merge requests, etc? Hear me out: people take it for granted that a good product deserves a shiny dashboard. Over the course of GitHub's "success", shiny tabs labeled "issues" and "pull requests" gain ubiquity on other VCS frontends. It disrupted the industry.

How did developers contribute to FOSS projects back when GitHub wasn't a thing? Well, before StackOverflow, we had forums. Similarly, before GitHub, we had mailing lists. It has been long known to me that the Linux kernel is developed on a mailing list, where contributors would submit patches and receive a Wish You Were Never Born, Dumbass Certificate from Linus. However I, along with many others had no idea how it's actually done. Check out the PR page of the Linux repo on GitHub. Too many people have mistaken a web UI, if not limited to GitHub, for the development platform for anything. Well, it's definitely not how Linux is developed.

The web interface is intrusive. You may be unsurprised to hear some people, typically new coders making their own GitHub page, code directly into GitHub's web editor, commit one file at a time, and test changes in the browser. It's the UI mindset. GitHub and websites alike hijacked us, and we didn't even know. The reason why will be analyzed.

You notice a clear distinction between "coders" and "developers": it's like human evolution, the command of tools. Git is a tool; so is GitHub. A tool is intended to excel at a limited range of work. If you cry about how GitHub sucks as a cloud drive, you are cracking a walnut with a drill. Sharpening your skill is a superset of mastering the toolchain. Likewise, it seems sensible for me to, at this point of my coding hobby, leap out of the interfaces and embrace what Git should have been. After all, what we really wanted is not an interface, but a workflow, in which field Git's utilities work just fine.

The Real Git

I will use sourcehut, aka sr.ht as an example. I stumbled upon it a while ago, but it wasn't until yesterday that I tried it out for its simplicity. Simple as in no bloat, not in being for dummies. For starters, there's no JavaScript. Really, you should check out its interface. Or not. It doesn't matter, something else does, and I sincerely regret having overlooked this "selling point": the absence of selling points. The web design does not only look simple, it is simple. Almost read-only, you can't do pretty much anything with it. For this reason, I refuse to call it "Git on steroids"; instead, it's "Git without hurdles", hurdles scattered in your dev work every single day. OK, listen carefully: all the interactions I used to assume to be web-only, happen on mailing lists. To submit a patch (retro version of "pull request" - remember that?), you simply commit your changes locally, run this command: git send-email --to="~user/list@lists.sr.ht" HEAD~, and your patch is out there waiting for review. Of course, a shitload of configuration has to be done ahead, which is partly why this email-driven development hasn't really taken off in the younger demographic.

Despite its drawbacks, I find it superior to web apps. First of all it obviously saves bandwidth as well as time, since no time is wasted on the UI; the terminal plus an email client satisfy all needs. Second is because it's dank as shit. With the right configuration, you can set up a TUI email client, which enables you to combine the entirety of your workflow in the terminal. Finally, and the most importantly: it does not require an account for contributors to submit a patch. All it takes is your email address as your identity, and an email containing your patch. And this, is how Git is supposed to work. Read more on @OTheB's blogpost, the one that had me sold: how to use git (with fancy screenshots I'm too lazy to take). I'm not asking you to stop using web UI's; I'm reasoning how the alternative is more efficient, and should be considered as a solid option.

When is this approach favorable?

Under what circumstance should you try this? When you're in a (probably small in core contributors) team maintaining a project actively. Mails feel more like a to-do list for today than a kanban for this month, as you may find in a web forge. Patches and feedback get stuck in the mailbox before you resolve them. You'll be more motivated to fix them or respond to them.

Pains

Email

With any given Git hosting platform with a fancy web interface, you very likely use your email to login. After that, you only occasionally receive notifications in your mailbox. Stuff happens over HTTP mainly, so it doesn't matter if you're using a shitty webmail interface like GMail. Let's say you ditched GitHub and went all in on email-driven development. Now email becomes a crucial part of your web-free workflow, and you can't just use another web interface while expecting to be a 10x dev. Furthermore, the email address is no longer part of your identity; it is your identity. Your patches are submitted through it, PGP key generated under it. So it is utterly critical to get this right before you even start.

Provider

It would be best if you have a personal server and are able to install a mail server yourself. I can't. Fortunately, I found a provider, thanks to Drew DeVault's recommendation (first on the list). (Oh, did I mention Drew is Sourcehut's creator?)

Local client

IMAP and SMTP are old. This means were you to manually set up your account, there'd be standards and conventions, old and new, in any given field to fill out when configuring a client. For example (excuse my stupidity), TLS and STARTTLS are somewhat different, but I'm too lazy to check. I spent a tediously long time configuring 5 clients, 2 of which are working.

In the list.sr.ht wiki, I learned to use plain text in email and keep email etiquette in mind. This is easily achievable.

I also had a reasonably short time setting up an SMTP client (turns out to be different from an fully-fledged email client), namely msmtp. It's a CLI utility for sending emails. You can configure git send-email to use it as one of the possible methods. See git-send-email website.

Community

Admit it: mailing lists, although barrier-free, rarely gets as much attention as a web UI like a GitHub issue thread. Also, easy it may have been for you to get a email address you're proud to tell others, others' may be crap like SweeetBabe.69owo@gmail.com. Using email just feels more personal. For this reason, I suggest we use email-driven development for collaborative projects with a firm maintainer team, encourage experienced devs to join, and leave the mailing list as a feedback channel for regular users. Keep a mirror on a "regular" forge, as is the case for Linux, but I can't help cringing at how many joke PR's it's got. (I mean, some of them are funny.) And a bot would reply under them, taking them to the mailing list. When you make a mirror, however, perhaps you should tell people about it in advance.

Reflection

I reflected on myself, the guy who thought himself a hipster migrating from GitHub to Codeberg.

Why had I never heard of email-driven development?

At the news GitHub banned Iranian users without notice under the sanction, I was equally outraged as many of its users. I reached out to ForgeFed to discuss how we should make federated forge services, unaware the distributed nature of Git itself. I also started an issue thread in a repo protesting GitHub's abrupt decision, under which although one person noted how Git is decentralized already, nobody seemed to bring up anything about mailing lists or stuff like git am. I suppose the mailing list gang had left GitHub for good? A few days later, speaking up my opinions on IRC, some friends reminded me of the email-as-an-identity thing, but still no mailing list. So, that's basically why I heard of such a thing nine months later than I should have.

What made me think web UI is the orthodoxy?

It's the first impression. GitHub (ironically) is my first mentor in FOSS. Like many others, I had no idea what GitHub and Git actually are, nor their relationship. As a result, it became a mindset, a mindset where I push buttons for actions and click checkboxes for options. It's undesirable, if you know what I mean. It's a shame for a Linux user for 3 years to be stuck in the web app for what could've been done in the terminal. Interfaces made email appear more old-fashioned than it really is, and this illusion harmed me. I wish I could ask for compensation.

How many other young devs exactly like me are out there, suffering?

A lot. While beginners tend to wet their hands in a web environment they're familiar with, others like me will regret not having heard of the opposite sooner. That's why I'm asking you to share the word to whoever wants to take their development efficiency one level higher. Not necessarily on sr.ht (they do release their applications as free software, with the need of a mail server). It's worth learning how to amend a commit, rebase, etc.

TL;DR

Many people believed the GitHub-like UI is the way all FOSS is developed. They are wrong. A web UI is not the only nor the original way to use git; you could use git-send-email to submit patches in mailing lists, and as maintainers you can merge them using git's stock utilities. Some people have never heard of the latter because they were never told about it; meanwhile, the web UI has hijacked their mindset. Sourcehut is an example of email-driven development with a minimalistic web frontend. In such development scheme you will find your workflow more efficient, especially if you are used to a terminal. The obvious pain in the neck is a good mailbox as your identity and a local client that doesn't suck. I hope you're experienced enough to figure those out. Then it's the low public exposure of a mailing list. Perhaps maintain a mirror on a UI-driven site as a portfolio.

The reason why I had never heard of such a thing before is no one told me the exact thing I needed to know. Also GitHub formed the stereotype of a git forge. There are certainly other young people suffering, unaware of email-driven development being an option. Tell them this thing has been around for 15 years.