Maintaining feature branches and submitting patches with Git

I have developed a particular Git workflow for maintaining PostgreSQL feature branches and submitting patches to the pgsql-hackers mailing list and commit fests. Perhaps it’s also useful to others.

This workflow is useful for features that take a long time to develop, will be submitted for review several times, and will require a significant amount of changes over time. In simpler cases, it’s probably too much overhead.

You start as usual with a new feature branch off master

git checkout -b reindex-concurrently master

and code away. Make as many commits as you like for every change you make. Never rebase this branch. Push it somewhere else regularly for backup.

When it’s time to submit your feature for the first time, first merge in the current master branch, fix any conflicts, run all the tests:

git checkout master
git pull
make world
make check-world
git checkout reindex-concurrently
git merge master
# possibly conflict resolution
make world
make check-world

(The actual commands are something like make world -j4 -k and make check-world -Otarget -j4, but I’ll leave out those options in this post for simplicity.)

(Why run the build and tests on the master branch before merging? That ensures that if the build or tests fail later in your branch, it’s because of your code and not because a bad situation in master or a system problem. It happens.)

Now your code is good to go. But you can’t submit it like that, you need to squash it to a single patch. But you don’t want to mess up your development history by overwriting your feature branch. I create what I call a separate “submission” branch for this, like so:

git checkout -b _submission/reindex-concurrently-v1 master

The naming here is just so that this shows up sorted separately in my git branch list. Then

git merge --squash reindex-concurrently

This effectively makes a copy of your feature branch as a single staged commit but doesn’t commit it yet. Now commit it:

git commit

At the first go-round, you should now write a commit message for your feature patch. Then create a patch file:

git format-patch -v1 master --base master

The --base option is useful because it records in your patch what master was when you created the patch. If a reviewer encounters a conflict when applying the patch, they can then apply the patch on the recorded base commit instead. Obviously, you’ll eventually want to fix the conflict with a new patch version, but the reviewing can continue in the meantime.

Then you continue hacking on your feature branch and want to send the next version. First, update master again and check that it’s good:

git checkout master
git pull
make world
make check-world

Then merge it into your feature branch:

git checkout reindex-concurrently
git merge master
# possibly conflict resolution
make world
make check-world

Then make a new submission branch:

git checkout -b _submission/reindex-concurrently-v2 master

Again stage a squashed commit:

git merge --squash reindex-concurrently

Now when you commit you can copy the commit message from the previous patch version:

git commit -C _submission/reindex-concurrently-v1 -e --reset-author

The option -C takes the commit message from the given commit. The option -e allows you to edit the commit message, so you can enhance and refine it for each new version. --reset-author is necessary to update the commit’s author timestamp. Otherwise it keeps using the timestamp of the previous version’s commit.

And again create the patch file with a new version:

git format-patch -v2 master --base master

The advantage of this workflow is that on the one hand you can keep the feature branch evolving without messing with rebases, and on the other hand you can create squashed commits for submission while not having to retype or copy-and-paste commit messages, and you keep a record of what you submitted inside the git system.