You don't need Github

Many people who are new to the world of programming have heard about Git and Github, but do not necessarily know exactly what they are and how they are related. These days, I find that many beginners have only heard of Github and don't realize that Git is a separate thing.

In this blog post I hope to inspire you to take back control and ownership of your work. You don't need corporate services like Github to host your projects! And you don't need to install bloated, complex services like Gitlab, or Gitea. There's a much simpler solution. Let me show you.

is not

Git is the actual software that people use to manage their projects. It helps to keep track of changes, share code between people, handle conflicting changes, and much more. It was written by Linus Torvalds, the creator of Linux, in 2005, and quickly became the de-facto standard tool for version control.

Github, which is owned by Microsoft these days, is an online service for storing your repo - the project files that you are managing with Git. In other words, this makes your project available online, so that there is always a central repo you can clone from, or push your changes to.

Apart from that, services like Github add extra functionality like issue tracking, browsing your source code, CI/CD, and much more. And all of that is of course very convenient, but remember: "When the product is free, you are the product." In return, Microsoft gets your data, and they train their AI on your code.

Personally, I moved all my personal projects away from Github and onto my own server years ago. I now use Github for public projects only.

Like I said above: if git can read it, we can clone it. So in another folder on the same machine, I can clone the repo:

  $ mkdir ~/another_location
  $ cd ~/another_location
  $ git clone ~/my_git_repo

All this does is to create a folder called my_git_repo, and duplicate the .git folder in there. Then it checks out the main branch. So you do not need Github to share your code or to clone it.

We now find a .git folder and our demo.txt file in the new location:

  $ cd ~/another_location/my_git_repo
  $ ls -la

total 8
drwxr-xr-x@  4 reindert  staff  128 Jun  2 23:13 .
drwxr-xr-x@  3 reindert  staff   96 Jun  2 23:13 ..
drwxr-xr-x@ 12 reindert  staff  384 Jun  2 23:13 .git
-rw-r--r--@  1 reindert  staff   23 Jun  2 23:13 demo.txt

Interestingly, if we look at the file .git/config in our cloned project:

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
	ignorecase = true
	precomposeunicode = true
[remote "origin"]
	url = /Users/reindert/my_git_repo
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main

Note how this references the original repo location as "origin". This is exactly the same behaviour you get when you clone from Github. This will allow you to pull changes from the original repo just like you're used to. I encourage you to try this for yourself: create a local repo, clone it, make a commit in the original repo, then pull it.

Pushing the other way (from the clone back to the original) is a different story. Git refuses this by default, because the original has a branch checked out, and pushing to that branch would overwrite that. We'll see how to solve that in a moment.

But this already proves my point: we don't need a third-party service to be able to exchange project revisions. Git just needs access to the repo files, that's all. So let's see how to make this work over the internet.

We start by creating the repository on the server. In practice, this will be the "origin" - the version that you clone, pull from and push your changes to. The best practice is to create a bare repo:

  # log into your server
  $ ssh user@myserver.org

  myserver:~ $ mkdir -p ~/repos/my_project
  myserver:~ $ cd ~/repos/my_project
  myserver:~ $ git init --bare

  Initialized empty Git repository in /home/user/repos/my_project/

A bare repository contains only the version information (the .git folder) and does not have a working directory. In other words, it does not checkout any of the files for you to work in. This is the typical setup when hosting a central repo. Git will now also accept pushing to any branch in this repo, which solves the problem we had with pushing earlier.

And that is all! You now have an empty, self-hosted repo.

So how do we clone this repo? We will ask git to do this over ssh. So we take the ssh argument to log into the server: user@myserver.org, and add the path to the git repo:

  # Run this on your local machine to clone the repo
  $ git clone user@myserver.org:repos/my_project

  Cloning into 'my_project'...
  warning: You appear to have cloned an empty repository.

This is just like setting up a new repo on Github and cloning it! But this time everything is under our own control. From here on, you can make changes, push and pull, just like always. So there you have it: your own git repo. Enjoy your freedom!

There is one thing that we cannot do with this setup: pull requests, because pull requests are not a native Git feature. They are an extra feature offered by platforms like Github and Gitlab.

Git’s own mechanism for collaborating is branching, merging, and reviewing patches. You can still have a Git-based code review process without a special "pull request" button. Just use branches and do a manual merge or cherry-pick after reviewing.

Or do it the way Linus himself does on the Linux kernel: use git format-patch and git send-email to share and review patches by email. This is the original Git collaboration workflow, it's a bit old school but it does work!

SSH in general is pretty safe, but make sure you use a strong password to prevent anyone from guessing it and getting access to your server!

Or even better: learn about key-based login. This is MUCH safer than passwords, and once you do this, you can disable password-based login altogether.

The approach above uses your own login on the server to host your git repo. That does not work well if you want to share your work with others. The simplest approach would be to create a separate git user on your server, and move the repo to that user's home directory. The url to clone from would then become git@myserver.org:repos/my_project.

You then ask each team mate for their public SSH key, and add those to .ssh/authorized_keys for the git user. That way, all your team mates will be able to push and pull to the repo.

As an extra precaution, set the git user's login shell to /usr/bin/git-shell. This restricts your team mates to git operations only, instead of giving them full shell access to your server.

Of course the ssh approach to serving git is quite simplistic and it will not fit everybody's needs. At some point, you may outgrow this simple setup. You might have many repos, or many users, or need more fine-grained permissions per user. I would suggest gitolite or soft-serve as nice light-weight soltuions for that. Or you can always reach for some of the more full-featured platforms (forgejo, gitea, gitlab), but I just think those are generally bloated and quite crappy.