Hacker News Reader

There's a few advantages to doing things this way.

If you ever want to git-bisect your code-base to track down when you introduced a bug then you'll be very thankful that every commit is functional and passes your test-suite (apart from the tests relevant to new features on a topic branch of course). Having to hop forwards and backwards from each git-bisect point looking for a functional commit is a huge waste of time.

Breaking your changes into clean commits with proper explanatory commit messages also makes it much easier for people working on the code in the future to work out the intent of various parts of the code.

Think of a messy commit history as a form of technical debt: Sure it's quicker to just move forward with development, but if you have a history that breaks things down into clean commits with well written explanatory commit messages then you're making life much, much easier for whoever has to debug that code in the future. Odds are that that person is going to be you & by the time you come back to the code you've have forgotten all about it and be forced to spelunk through the commit history in order to work out what on earth you were doing. Think of it as a service to your future self :)

"If you ever want to git-bisect your code-base to track down when you introduced a bug then you'll be very thankful that every commit is functional and passes your test-suite"

I agree that this property is very useful, but I disagree that it it is necessarily implied by the workflow as described in the article. By using "git add -p", he is constructing a tree that probably never actually existed during development - hence there is no guarantee that it works and passes the tests.

I strongly agree with you that a clean logical progression of commits is a good thing (especially for code review). However, making sure that each stage works and passes the tests takes extra discipline.

The author runs his tests after his partial commits. He does this by stashing the remaining changes, testing the newly-committed code, and then continuing to make partial commits. Here's the example in the article:

        % git stash
        % make test
        ...
        OK
        % git stash pop

Also keep in mind that the initial tree contains WIP commits that are unlikely to work or pass tests, so reordering commits can hardly make things worse.

I care very little about the cleanliness of my history. I mean, I care that it's not horrendous, but a bunch of extra merge commits or a few random fix-up commits don't make me think twice. However, I've found a the tools for maintaining clean history to be extremely useful for getting real work done.

My typical workflow with Git is one of incrementally appending commits to a branch, and then using git rebase --interactive to bubble sort commits by impact.

For example, let's say I am working on a feature and I stumble across an unrelated bug that's easy to fix. I fix it. Then I commit just that fix. And then I go about my day. Sometimes, my fix may depend on a small refactor or ancillary change that's not finished. So I make the change anyway, and commit it, completely broken. After finishing the ancillary dependency, I use rebase to reorder the commits so that I can test the change in absence of the bug fix, and then again with it applied.

I've had feature branches grow up to 20 or 30 commits, where 10+ of them are totally borked or otherwise need to be re-ordered. By the time I've made sense of it all, I send it out to my team as 2 or 3 pull requests with 1 to 5 commits each. In the process, I look at my code diff over, and over, and over again. I find lots of bugs by inspection this way. I enjoy writing code this way.

This way my code can be reviewed as a series of logical transformations. It's much easier to review this way. I really appreciate it when my co-workers send me clean patches to review, so I respond in kind.

In summary: It's not about a clean history (although that's a nice side effect). It's about using Git as a tool to help you and your team reason about changes.

I agree that in many cases this meticulous approach is overkill. But what it demonstrates nicely is, as the man says, 'Git means never having to say "If only I'd realized sooner."'

When you do need your commit history to be as neat as possible, git gives you plenty of tools to make it happen. Imagine the nightmare a task like this would be with Subversion. (I haven't used Hg a lot so can't say how it compares in this regard--I'd be curious to know.)

Here are some of the situations I run into on a regular basis at my current company, which is Perforce based, where I wish we were git based instead. This would be as true in Subversion. They might be maybe less true in Mercurial or Bzr, I'm not as familiar with those ones.

* I am hacking on some bit of code, so I set up a Perforce branch. While I'm at it I notice some ugliness and want to refactor it. I could make a new Perforce branch and put it there and then do some horrible merging apparatus but it's complicated and they live forever and it takes me out of the flow state, so I just make a commit. It is now very difficult to extract that commit from its context so that I could apply it independently.

* I make a mistake on a commit that is on a private Perforce branch, or maybe I did something out of order. The Perforce way is "you shouldn't have done that, then." and so my commit logs are full of "fix stupid typo" type commits that are basically just noise.

* I forget to add a file to Perforce and nothing tells me about it, ever, until we get to testing (or sometimes to production!) and Puppet won't run because it can't find some file <foo>. This is fixed with the 2012 betas and p4 status, but those require a server upgrade (because the p4 client is a thin wrapper around what the p4d server understands) and that isn't in the cards yet. This alone is enough to make me want to use git-p4 for everything.

* You can really tell that Perforce is built around a file system of RCS files sometimes. While it has atomic commits, many, many operations are based on individual file revisions (labelling, cherry picking, merging). This leads to the following:

* Cherry picking in Perforce is hard, because it's hard to get handle on the content of a changeset, as opposed to individual upticks in each of the files referenced. It can be done but it is a lot of effort, way more so than in git.

This is not the entirety of my complaints about Perforce, by any means, but they're the most visible UI limitations compared to what I'm used to from git.

Mercurial is more like Git than not. It differs in the way it stores revision history (Git stores files, Mercurial stores deltas, basically).

And branching is Mercurial isn't nearly as neatly implemented as it is in Git.

But it would seem to address the issues you listed here. For example, you can rollback a commit if you did the "stupid typo" mistake. And you have a lot of power to "change history" and modify the DAG anyway you wish.

In my opinion branching _used_ to not be as neatly implemented as it is in Git, but that is no longer the case.

A couple of versions ago a new feature was added into core mercurial, called "bookmarks". Mercurial bookmarks are the same as Git branches.

So now you can use the "git style branches" (i.e. bookmarks) in mercurial, or you can use the regular mercurial-style branches (which I personally prefer to git's anyway). In addition you can use "anonymous" branches, which AFAIK do not exist in git at all.

Anonymous branches are AFAICT the same thing as detached heads. They're discouraged in git, but they work fine.

I also hate the "forget to add a file" issue in Perforce.

How about trying to rename a file and change the class name at the same time? That always gives me trouble.

I've been streamlining my commit histories this way for several years now, and it's worth the effort.

I do it pretty much the same way the author does (only I use Emacs and Magit mostly). The reason I do it is because my work has to make sense to other people, and also to me six months later. So I think of my commit histories as stories that must tell people how my software got from point A to B, and tell them clearly.

The chronological history of how I wrote some batch of code is just the first draft of the story. It's messy. It contains WIP commits, false starts, backtracking, and all sorts of cruft that tells more about the noise of software development (and when I stopped for dinner) than about how the software logically moved from one sensible point to another.

Once I've got a chuck of work all figured out, all that noise has to go. It must be edited away before I publish the work upstream. Otherwise, I'm just weighing down everybody who has to understand the work later (including me).

I can't imagine applying a workflow like this without magit. It sounds like so much grunt work.

I also don't see the point. If I need to experiment, I'll create a branch, mess around there, and merge it back when I've figured things out and have everything working.

The workflow in the article seems like it's trying to be clever for the sake of being clever. I guess it works for him, but I think most people would find it too confusing to be practical.

Assume that while working on your branch you made a few commits which were not perfect (say you wanted to take a day off and you want a commit point to work from when you are back). This all good and fine, you come back get the code working on your branch, make a commit and merge it to the main branch. When one looks at the commit log in the main branch it would list all the commits you have made (even the ones on which the code was not in a good shape). But at the same time the latest commit on main is good and this not a big problem. But if you really want to keep the history in the main branch to look clean and show only good commits, then it is not the case.

Though I don't follow what the author practices, I don't think it is a practice that is done for sake of cleverness. There is a benefit in keeping the history clean in the main branch. My only wish is probably if git allowed one to achieve the same without so many hoops.

Wouldn't git merge --squash do this for you?

Thanks, I had never used the 'squash' option and was unaware of it. I think using 'squash' does helps to the history clean.

I'm a release engineer, and I couldn't agree more with the sentiment of this post. I have immense respect for mjd's work (His articles on Perl saved my bacon more than once - _Suffering with Buffering_ and _Coping with Scoping_ in particular) but this workflow just plain stinks and feels like building a house, then demolishing it and picking through the rubble to build a better house you're satisfied with, rather than (as git was designed to do) experimenting off to the side in a branch and only commiting Good Stuff to your 'for real' branch (master or otherwise.)

I find this to be over kill but I see the point.. as if you're always trying to make "good" commits you kind of lose the "get all the shit done" mentality as you have to separate everything in smaller ideas.. whereas it's faster sometime to really hack lots of thing and commit, and then at the end cleaning stuff.

this is a lot of work if you are OCD and print out your diffs to mark with a highlighter. A decent git gui like GitX on mac will let you do it with almost no effort at all.