Git for people who don't know git

Internally, with a small team, we build extensions for the software we use, like bug fixes and new features. Eventually that has to end up with the colleagues who work with it every day.

Those colleagues aren’t developers. They work in the software, not on it. Git is a foreign word to them, and so is GitHub. They don’t know what a repository is, they don’t know what a branch is, and they don’t need to know either.

The wrong approach

Still, we started with the obvious approach. We installed GitHub Desktop, explained what a repository is and showed them how to pull. It worked, but barely. They got an authentication error here, a merge conflict there, and constant questions about what “behind by 3 commits” actually means. The interface assumes a baseline that simply isn’t there.

The problem isn’t that they don’t want to learn it. They don’t need to learn it, they just want the latest version of a file. So the question became how to take the complexity away from the user and put it on the developer.

The simplification

At some point I thought: maybe this is the wrong tool, we’re making it too hard for the user. It has to be simpler.

We got to work and tried something else. Not explaining git, but hiding it. We can reduce the interface to one thing: get the latest version, without anyone needing to understand what happens underneath.

That became GitFetch, a Windows program with one big button in the middle that says FETCH. You press it and you have the current version.

The approach is deliberately destructive. GitFetch always syncs hard. Local changes are thrown overboard and the selected branch is mirrored exactly to what’s on GitHub, with no merge and no conflict.

It’s a crude solution, but it works. Our target users don’t make local changes to those files. They fetch them. For them, “overwrite everything” isn’t crude. It’s exactly what they want.

Behind the button

At the top you pick which repository and which branch you fetch, though for most colleagues that always stays on the same repo and on main. They never look at it.

Every time you press FETCH, the program runs through the same sequence of steps. First it checks whether there’s already a local copy. If not, it clones the repository. If the folder already exists, it updates the remote URL in case it ever changed.

Then comes the sync itself, and nothing magical happens there. These are the git commands a developer would type by hand too, except the program runs them for you:

git fetch --prune --tags
git checkout -f -B <branch> origin/<branch>
git reset --hard origin/<branch>
git clean -fd

Fetch what’s on GitHub, force the right branch into place, hard-reset to the remote and clean up loose files. After that the local folder is exactly the same as what’s online.

There’s still one step in between. Before the program throws anything away, it checks whether there are local changes. If there are, it pauses and asks in plain language whether you want to continue. Not overwriting quietly, but giving the person a choice. In practice almost everyone just presses continue, but they’ve seen it.

While all this happens, a log runs along the bottom. It’s the only thing the user sees of what’s going on behind the scenes, and the colors do most of the work. Green is good and most runs are almost entirely green. Orange means pay attention for a moment, usually because of those local changes. Red means something is broken.

With red, the important part is precisely what isn’t there. No exit code 128, no lines starting with fatal:. Just a sentence that says what’s wrong. That took more effort than you’d think, because git is anything but sparing with technical output.

If you want more, you can attach shell commands to a fetch in a settings screen, before or after, per repo or for all of them. Handy when something needs to run automatically after an update. But that’s optional, and most people never see that screen. We have a developer set up such a command group once, and after that no one has to bother with it again. We can export those settings as JSON and keep them as a default.

How it turned out

It’s been running for a few weeks now. People use it and don’t ask about it anymore. That’s the best sign something works. A colleague said he liked just pressing that button, without thinking about it too much.

The branch selection is a deliberate design choice. A developer puts a new version on a dev branch and tests it themselves. Then a few slightly more capable users pull that same branch to help test, before it goes out to everyone. They set GitFetch to the dev branch for a bit, try it out and then go back to main. Because every fetch is a clean hard sync, that switching costs nothing, no merge conflicts or half-finished work left hanging.

Something we also didn’t expect is that the developers use it themselves now and then too. They can use git just fine. They know exactly what’s behind that button. But for a quick test run on another machine it’s just handy. That told me something. Simplifying isn’t the same as hiding things away for beginners. Sometimes it’s just better design.