Why I use Git Patches (and you should too!)
Git patches are a way to send others changes to your code, different from the pull requests model used by sites like GitHub. I’ve begun using them for a few of the programming tasks I’ve had to do in my time as a computer science student, so I wanted to write this post about how & why I use them.
How to Use Git Patches
To create a patch for every commit between A (exclusive) and B (inclusive):
git format-patch A..B
git format-patch A does the same thing as above, but it uses the current location as the value of B.
This seems to have been designed so you can easily get patches for a feature branch. For example, if your repository has the following commits:
A - B - C - D - E ← master
\- F - G ← feature
and your current branch is feature, then git format-patch master makes patches for commits F and G.
These patches will be output as files within the current directory, one per commit. These files can be shared to share your changes. To apply a patch:
git am [path to patch file]
This will create a commit with the content (and author) of the patch.
For more info, check out the Git documentation:
git format-patch: creates git patches
git send-email: sends a collection of patches as emails
git am: apply a series of patches from files
git apply: applies patches without creating a commit
Why Use Patches?
Contributing to Projects
Imagine I want to make a change to a libre/open source project that I don’t have push access to.
If I want to do this using pull requests, the steps to do so are:
- Make an account on the site where the project is hosted, or log on if I already have one.
- Make a copy of the repository on the website, if I don’t already have one. If I do, make sure this copy is up to date.
- Clone this copy of the repository onto my computer. If I already have a clone, pull.
- Make the changes on this local copy.
- Push the changes from my local clone to my online copy.
- Create a pull request.
If I want to do this using patches, the steps are:
- Clone the repository onto my computer. If I already have a clone, pull.
- Make the changes on my local copy.
- Create the patch files using git format-patch.
- Send the patch files to the project owner.
The latter is much simpler than the former.
Pull requests were invented by GitHub, and I think they did so to keep people on their site: if you want to make a pull request to a GitHub project, you need to have a GitHub account, and your changes need to be on a GitHub fork of the original.
Hosting Projects
I self-host a few of my programming projects on this website, and if you thought patches make contributors’ lives easier, wait until you see the benefits of patches for hosts!
In order to allow people to make pull requests to my projects, I have to:
- Setup a more fully features frontend for my projects, such as Gitea.
- Allow people to make accounts on my website.
- Handle all the privacy/security/legal/etc. concerns that come from having to store other peoples’ data on my personal website.
- Probably rent a more expensive VPS to store all the new forks that I have to store on my website.
More likely, I’d just give up on self-hosting and host all my projects on a third-party service like GitHub.
In order to allow people to send patches, I have to:
- Add a notice to my README telling people to email me their patches, linking to a guide that explains how to do so (e.g. git-send-email.io).
That’s it! If I want to make all my patches & discussions public, I’d also have to setup a public mailing list, but I haven’t felt the need for public discussions on my projects yet.
Sidenote on git send-email
People who already know about this will probably be thinking “Shouldn’t you use git send-email instead of sending patch files? Isn’t that better?”. In theory, it is better, since it makes it easier to quote your patches when reviewing them.
However, in order to send someone a patch via send-email, they need to be able to save your message as a file. This is a lot more that I have to teach people that I want to send patches to – and I don’t even know how to do that with webmail or mobile apps, which most people use. Attachments, on the other hand, are something everyone understands, and “run git am” is something the sort of person using Git should be able to figure out.
On the other hand, if we’re talking about people like me who already know how to use it (or are willing to learn), I agree that git send-email is the best way to do this, and is how you should do it.