[Simon Tatham, 2025-03-05]

• Introduction
  • Purposes of this article
• How to interact with a bare git repo
  • What do I prefer in particular?
    • BEST: URL of a git repository + branch name
    • An incremental git bundle
    • A set of patch files from git
format-patch
    • A bare diff file generated by git diff
    • WORST: A series of separate emails generated
      by git send-email
• Why don’t I use a git forge?
  • Trust
  • Heavyweight
  • Account management
  • You get a workflow imposed on you
  • Plain old inertia
  • Special mention: especially not Github
• Should I start using a git forge instead?

Introduction

I’ve written quite a lot of free software in my life. Most of
it was from scratch: projects I started myself. So I get to
choose where to host them – or rather, I have to choose
where to host them.

These days, all my projects are held in Git. And mostly, I put
them in ‘bare’ git repositories on my personal website.

I don’t use any git ‘forge’ system layered on top of Git, like
Gitlab or Github, which automatically makes a bug tracking
database for each project, and provides a convenient button for
a user to open a merge request / pull request. I just use plain
Git. People can ‘git clone’ my code, and there’s a
web-based browsing interface (the basic gitweb) for
looking around without having to clone it at all. But that’s all
the automated facilities you get.

Occasionally this confuses people, so I thought I should write
something about it.

Purposes of this article

Sometimes people just can’t work out how to send me patches at
all. Or they can think of several ways, and aren’t sure which is
best. So one purpose of this article is to be a public statement
of my own preferences, which I can link to when people ask that
question.

But it’s also a bit of a musing about why I don’t use
a ‘forge’ style system like Gitlab or Github. People sometimes
ask me that too – “why don’t you do what everyone else does?” or
words to that effect.

How to interact with a bare git repo

People who are used to git forges look for a ‘pull request’
button. When they don’t find it, they sometimes get confused.

If you can’t find a button on a website to submit a patch, how
do you send your patch to the maintainer?

You send the author an email. And in the email, you put one of
these things:

1. A URL to your own clone of the repository, containing your
   patches on top of the ‘upstream’ code.
2. The actual patches, in some form of email attachment.

Either of these works. For option 2 there are multiple ways to
do it in detail, and all of those work too.

It doesn’t have to be by email, either. Any method of sending
this data to the maintainer is fine. For example, I’m on
Mastodon – so you could send me a repository URL via Mastodon if
you really wanted to (provided you didn’t mind my responses
being very short). Or you could send patches via any other
communications medium that you and the maintainer are both on,
if it lets you attach files to messages.

What do I prefer in particular?

But some people don’t just want to know any way to
send patches. They want to know which is the best way,
or at least the way I prefer.

So here’s my own list, in descending order: most preferred at
the top, least at the bottom.

BEST: URL of a git repository + branch name

This is my absolute favourite way to receive patches.
If there’s anywhere on the Internet you can put a clone of my
git repository with some extra patches, then the best thing is
to do that, and send me an email saying something like

I have some patches to [project] to [make some change]. You
can find them in the branch called [whatever] here: [URL]

The URL can be anything that’s convenient, as long as it’s
either something I can give to git clone, or a
human-readable web page containing something I can give
to git clone. It can be anything from a git forge
page (just because I don’t host my code on Github
doesn’t mean you can’t put your patched version there for me to
look at) to a static site where you’ve uploaded a repository and
run git update-server-info.

When you get right down to it, this is exactly what the
formalised ‘pull request’ or ‘merge request’ in a git forge
system is. That’s why you start by forking (i.e.
cloning) the target repository and put your changes in a branch
of your fork. A PR communicates to the maintainer: “Hey, see
this repo over here, this branch in particular? It has changes
I’d like you to take.” The formal PR button in a forge is a way
to do that with one click, but a short email with all the same
information is just as good.

Why I like it: This is my favourite way to receive
patches because the patches themselves don’t go through my
email. This saves space for me in the long term (I keep all my
email), and it saves me messing about with moving attachments
around (I read email on a different machine from the one I
develop on). All I need is to paste the URL from the email into
my git command line, and bing, I’ve got the patches in a form I
can look at, review, and maybe merge.

Also, if I make review comments and you want to update the
patches, it saves space again if you don’t have to send
a full set of updated patch files, but instead, push a modified
version of your branch and just send another email saying

OK, I’ve addressed those review comments. New patches are in
the same place as before.

An incremental git bundle

Git bundles don’t seem to be very widely known. I think that’s
a shame, because they’re awesome.

The simplest kind of git bundle – a full bundle – is a
whole git repository, wrapped up into a single file. It contains
a