Git commits for collaboration
This post is a note to self and an explanation for present and future team members and collaborators. YMMV.
The goal is twofold: to ensure a useful history of project changes with explanations for what and mostly why things changed the way they did, and to make merging the change into the main project - with everything that entails (testing, building, deploying) - as easy as possible for the people doing that.
The process outlined below simplifies the merge process (for the maintainer) by limiting us to one commit that can be cleanly merged into the main project.
There are two remote repos, yours and the main project repo. Since this
is the Acme Corp's repo and I'm going to name it
You have a local feature branch, called
you've been working on code. The only changes right now in this branch
are commits you've made specific to your feature.
acme/master branch of the main project repo represents code that is in
acme/master branch has been getting updates since you created your
original feature branch.
People like it when you make their lives easier for them, even if that means a bit of extra work for you right now!
Step 1: updating from the main repo
Make sure you have the main repo referenced locally.
git remote add acme email@example.com:acme/serious-software.git
Next I'll make sure I have a copy of everything they've been working on.
git fetch acme
And since I've left my master branch alone since I cloned their repository, I'm going to update it.
git checkout master git merge acme/master
Again, note the strong asumption that my preexisting master branch
had only commits present in
acme/master. This would have resulted in a
merge commit otherwise - most likely. The master branch should mirror
the main remote master branch, which means never commiting directly to
it or merging to it from a local branch - and as a safeguard, never
doing that even if you know the outcome will be as expected by pulling
Clean patch commits
Let's look at what clean patch commits mean before proceeding.
The goal of the patch commit - or pull request commit - is to be readable, to explain to the maintainer what happened and most importantly why, and to code archeologists, too. You'll often find yourself trying to track down a change in some code, either related to a bug or to explain why something is the way it is, and quality commits and commit messages help this a lot.
commit 1bb539d83916c7a34d714ba87f4e2a8782f132dc Author: c0d3r <firstname.lastname@example.org> Date: Fri Aug 14 13:05:52 2015 -0400 update commit 3560993da4f024bf2d3babc7a765af86ab884282 Author: c0d3r <email@example.com> Date: Fri Aug 14 12:26:46 2015 -0400 new thing in class commit 84f1fe2bfd7f34d2a35a969a547b3e7db53e5d2e Author: c0d3r <firstname.lastname@example.org> Date: Fri Aug 14 12:22:56 2015 -0400 fixed
Wat. This is not helping anyone.
commit 1bb539d83916c7a34d714ba87f4e2a8782f132dc Author: c0d3r <email@example.com> Date: Fri Aug 14 13:05:52 2015 -0400 Updates financial model class calculation order Refactored the primary calculation method into several less stateful methods which calculate components individually. The interface is the same to respect existing code, but this makes testing easier and will make scheduled feature updates much simpler. [#123123123]
There, one explantory commit. We'll see below what makes that particular commit message better.
Step 2: crafting a clean patch commit
So we want to create a single commit from the numerous feature branch commits. There are two methods for doing this.
We want this to be clean with regard to
acme/master, so having updated
master branch to mirror
acme/master, we'll just create a
new branch from
git checkout -b feature-patch
Now we'll merge the feature changes in using the
git merge my-cool-new-feature --squash
You may encounter merge conflicts here, so now you'll need to fix these.
This won't drop us into the commit message editor right away like normal, so we'll have to explicitly issue the commit command.
Then you'll be presented with something like this in your editor:
Squashed commit of the following commit 1bb539d83916c7a34d714ba87f4e2a8782f132dc Author: c0d3r <firstname.lastname@example.org> Date: Fri Aug 14 13:05:52 2015 -0400 update commit 3560993da4f024bf2d3babc7a765af86ab884282 Author: c0d3r <email@example.com> Date: Fri Aug 14 12:26:46 2015 -0400 new thing in class commit 84f1fe2bfd7f34d2a35a969a547b3e7db53e5d2e Author: c0d3r <firstname.lastname@example.org> Date: Fri Aug 14 12:22:56 2015 -0400 fixed
At the very least you should change the commit title (the first line of around 50 characters), but in most cases just replace the whole message with your own helpful message.
Instead, create your patch branch from your feature branch:
git checkout my-cool-new-feature git checkout -b feature-patch
Then rebase against the master branch:
git rebase master
You may encounter conflicts in the rebase process, so you'll need to address these. There's a thorough explanation in the Git book online, but a short answer is as follows:
- When prompted with a conflict, you should see which files have
git statuswill also show you this; they are the files that are not staged.
- Open the unstaged files with conflicts and fix the conflicts! If
you're not familiar with what changes to expect from the main repo,
doing this manually is important to ensure you're not arbitrarily
overwriting changes that should be included. Alternatively you can
git checkoutwith the
--theirsflags, but keep in mind that when rebasing these are inverted from what you expect them to refer to when merging.
- Stage the files you've changed with
git add <fixed-file-name>. Be careful about this! Either wait until you've fixed all of the files or explicitly add files by name after they've been fixed.
git diffshould not show any differences before you stage a file.
- Continue rebasing, using
git rebase --continue.
- If there was only one file listed, Git may complain after a
continuecommand that there were no changed. Just run
git rebase --skipat this point.
This will have the effect of taking your feature branch commits and
putting them at the end of the git log, after all of the new
acme/master commits, regardless of when they were made.
Next we'll rebase again! But this time interactively, in order to squash and cleanup our commits.
git rebase --interactive HEAD~4
This will open our editor displaying the last 4 commits. I chose 4 here
because there are 3 in my fictional feature branch and I want to see the
last commit from
acme/master for reference.
Each is listed with 3 columns, 'pick' in one, a short version of the commit SHA in another, and then the commit title. For the bottom two entries - the lastest - I'm going to change 'pick' to 'f', short for fixup, which will squash the commits into the one above, and then in the second commit - the first in my feature branch - I'm going to change 'pick to 'r', short for reword, to change my commit message.
When I'm done rewording the commit message I'll be dropped back to the
command line with a patch branch that we know will merge cleanly (absent
further conflicting changes added to
acme/master before it's merged
and a patch that only shows the changes that need to be applied.
Step 3: write a helpful commit message
We already wrote the commit message, so let's back up a bit. Commit message expectations and content will vary somewhat from project to project, but there's a general style that ought be followed. Tim Pope more than adequately explains in full. Here's his model commit message:
Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent
I prefer a more present tense for the message, the "Fixes bug" example, because that answers the question, "What does this commit do?" and because I don't like using too many generated commit messages.
Commit messages are for other people, your future self included. They are wayfaring points for future travelers, not bathroom graffiti for how you feel about the world. If you fucking hate this stupid shit then fucking open Twitter, not your commit editor.
And if the commit references something like a bug ticket or even a project conversation, by all means make reference to that in the commit. Many of these will have a convention of their own based on system integrations, but otherwise including the URL with an explanation of the reference will almost certainly prove helpful.
Step 4: merge request!
That's it! Now it's time for a pull request. Push your patch branch and issue the request from that branch. If you wrote a good commit message you should not need to add much more explaining your pull request beyond the commit message.
Using a GUI Git client will probably be a problem. I've found them to be confusing beyond handling basic commits and merges. The confusion you may see using the command line is less because of the command line itself and more because you're being exposed to the changes you actually have to make to the repository.
There's no special need to reduce everything down to just 1 commit. Often several commits will be better, but only when they're logically reduced. Let's say you have 12 small commits including a couple of commits interspersed where you couldn't help yourself from reformatting some nearby code (probably don't do this though, right?), some test updates throughout, and then feature code updates. Using an interactive rebase you can reorder these and then squash them down into a reformatting commit, a tests update commit, and then a feature code commit.
Whether this is necessary or valuable is going to be depend on the situation. Working with inherited code I often find the need to reformat the entire file before really working on it, and that I maintain as a distinct commit so it doesn't obfuscate the changes I'm making to the codebase.
I wrote this with the rebasing order of first rebase from master and
then interactively rebase your feature branch, but it probably makes
more sense to interactively rebase and squash your feature branch first,
and then rebase against
acme/master. The reason is conflicts. With
fewer commits, you'll have to deal with conflicts fewer times - although
it doesn't fix the conflicts! - and you may clean up changes in your own
code which has the effect of at least simplifying the conflicts.
Originally published 2015-08-27