Patchette🔗

Patchette is a tool for managing patches.

Wot?🔗

Patches. To software. Patchette manages them.

What do we mean by "patches"?

• Well, actually, git commits, in practice.
• (But we're going to store them as patch files, instead of directly in a repo. For reasons. Keep reading.)

What do we mean by "manage"?

• We want to store the patches.
• We want to help update them...
  • either because the upstream has changes and the patches need to change as a result too,
  • or because the development work continues
• And most of all we want that to result in the ability to track the evolution of the patches over time.

Some existing and familiar tooling already does a decent job at some of those things -- indeed, git and git-rebase are already fundamentally storing patches and helping update them! -- but things don't handle that last bit: tracking the evolution.

The Bigger Picture🔗

Software is developed in "repos" and there's often an "upstream" (where publication is Someone Else), and then work is done in our personal "forks" or "clones".

Sometimes our clones of a repo diverge briefly: we make a change, commit it in our clone, offer it to the upstream (whether by "push" or by email attachment or anything in between), and then if all is good and cool, upstream accepts it as-is.

Patchette generally isn't relevant, then.

But that's the "happy path". That's... not usually how things go.

Sometimes it's a longer-term situationship.

relationships to upstreams🔗

"The upstream" in software can be a term that's loaded with a lot of diplomatic nuance. Patchette doesn't have any opinion about that, of course (how could we?), but we would say that there's roughly three kinds of practical relationships that a set of patches can have vs an upstream:

• patching locally, with NO intent to upstream ("malleable software");
• patching locally, WITH intent to upstream (but even with intent to upstream, there's always the implicit reality that it's gonna take a bit, and so we might want to track changes-to-the-changes during that period);
• or, no longer patching, but still want to have an archival record of the previously used patches available for historical reference.

The observation that Patchette is based on is that in all three of these stories, there can be a substantial passage of time, and during which your patches may evolve (or even be dropped)...

And if you aren't tracking the changes to your patches, then every "evolve" is actually a loss of information.

(And we think that's bad.)

changes to changes are meaningful🔗

When patches change, that's often worth tracking.

• Did upstream fix something? (Or partially fix something? Or maybe break something else?) The patch repo is a place to observe it and to chronicle it.
• Did a patch get simpler because of a partial fix? Or more complicated? The patch repo is a place to observe it and to chronicle it.
• Did a patch remain needed, but just move? The patch repo is a place to observe it, etc.

Maybe some of these things make your own private development processes go easier and more sure-footedly forward. Maybe some of the reviewability this gives you can actuall turn into good information to talk with the upstream about, for mutual benefit. You'll never know until you start having the information to work with.

Patchette's Solution🔗

tl;dr:

• the main/subject repo stays totally normal.
• Patchette makes a separate repo for patches.
• When you track a branch from the main/subject repo with Patchette:
  • the branch gets mapped into a folder in the patches repo,
  • and every commit gets mapped to a file in that folder,
  • and a little metadata file describes where the patches were meant to apply.

And that's it. But that little bit of information enables a lot of things.

your development workflow🔗

... doesn't have to change.

Actual development still happens in the subject repo. You still use git branches. Normal git tools like rebase still get to do their work; any workflow you have using it still applies, entirely.

Every time you run Patchette, it'll just update the patches repo with a snapshot of all the branches that you told Patchette to track.

It's purely value-add.

Patchette doesn't demand any particular structure of your commits, nor insert anything into them, either. If you someday take the patches you've managed with Patchette and decide you actually do want to upstream them, then you just... take the branch, and push it. Nothing special. No fanfare needed. Patchette never put anything into your commits that you'd need or want to redact. They're just... your commits.

you get to see the changes to the changes🔗

The patches repo is something you can now use regular "git diff" on.

you can describe the changes to the changes in the patches repo commit messages🔗

... if you want.

Or make all your patches repo commit messages "asdf". I'm not your boss.

you can recreate the branches from the patches🔗

If you have a patches repo, you can then delete the subject repo entirely, clone it again from upstream (who's not carrying any of your patches or branches!), and then use Patchette to recreate branches exactly like you had them before, just from what's saved in the patches repo.

Is this any easier than just keeping the full clone around, with your branches in it? Eh, it depends. Maybe not! But maybe yes:

• If the full clone is huge and you don't wanna keep it on hand all the time, then this capability can be handy!
• It does most certainly mean you can push the patches repo somewhere, and it's small!
• Operationally, it's easy to describe "repo XYZ is a mirror from a remote" and "repo XYZ-patches is authoritative".

do any of these things matter?🔗

lol, well. YMMV. But IYKYK.

(Your mileage may vary. But if you know, you know.)

Sometimes.

Sometimes the evolution to your patches will be trivial. Sometimes you'll do some updates and "rebased on upstream main" is all the more description you really need. Often, even.

But then there's The Other Times.

There's times where upstreaming something takes weeks, or months, and dozens of rounds of changes.

There's times where you're doing the "malleable software" thing, and you're not upstreaming things on purpose, so you're carrying patches for months or for years, while the upstream keeps evolving.

In those cases? Yeah. You're probably going to want to start reviewing the changes-to-the-changes sometimes. You're probably going to want to start leaving comments on how and why your patches had to adapt around upstream changes.

That's when you're going to start being happy you have Patchette to help with that.

really? another repo?🔗

Yep.

It makes sense for logical isolation.

But also it's very practical, in that the patch repo doesn't grow any faster than your actual patches and changes to them do.

does Patchette have to operate a whole repo all by itself?🔗

Nah. It's a default behavior.

But if you want to keep your patches in a repo that's also used for other stuff?

(Like, let's say similar to the way Arch does packaging repos? mhmm?)

Yeah, sure. Totally fine. Go for it.

Y u no...🔗

y u no just git rebase🔗

Git's rebase flow is a well known answer for how to keep some changes up to date with an upstream. And git itself effectively can be said to just store a series of patches. (I mean, it's not implemented like that, internally, but, semantically, we could say it works like that.)

That's cool, but Patchette is for when you need more. Patchette is for when you want to track changes to the changes.

Git rebase immediately forgets the previous diffs if it succeeds. This is true no matter how massively you may have rewritten them during the rebase. (Yes, there's a thing called the git-reflog, too. But that's temporary. And more for "oh shit"-undo reactions than meant as a tracking system.)

Patchette actually tracks the diffs, so it can easily track and show their evolution.

Patchette still actually lets you use git-rebase for evolving the changes. Git rebase is just fine at that! We don't have any reason to reinvent that wheel. Patchette is just for the rest of what we want.

y u no use mercurial!!!🔗

Yeah, mercurial had a feature for tracking evolution of changes like this, didn't it.

Huh. Weird. Hey, ya'll think maybe... mercurial had some good ideas? Hm!

Contributing🔗

Run make setup once after cloning: it activates the git hooks. Run make to see all commands. Before committing anything, run make all. There should be no warning messages.

License🔗

If I've really got to pick? Fine.

SPDX-License-Identifier: Apache-2.0 OR MIT

Or?

BSD0.

I really don't care anymore. Use it and be free.