My Git workflow for inuit.css
This is a bit of an unusual article from me, it doesn’t mention OOCSS once! It’s about Git…
I’ve been putting massive effort into learning a lot more about Git lately; I’ve been using it at work for over a year now, but only ever the more basic bits;
push. I’m now finally starting to feel like I ‘get’ Git; I don’t just go through the motions of ‘first I type this then I type this’, I actually get what and why I’m doing things, and it feels awesome.
As such, the way I work on inuit.css is (just) starting to change massively. I’m writing up my workflow, not to sound all preachy about how awesome I am at Git because—believe me—I know nothing. I’m writing it up in the hope that people can share improvements, modifications, alterations, disagreements or anything like that to keep me on this roll.
The stuff I’ve learned thus far is thanks in no small part to the people I work with, to mention a notable few; James Barwell, Nick Payne and Craig Andrews. There are likely more that I’ve forgotten, but these are the guys I pester the most!
New work, new branch
One thing I’m starting to stick to now is that all work happens in a topic branch. Nothing should get done in
master at all,
master should always be stable, clean, and theoretically ready for a release at any given moment. As such, any new feature, or a fix, or anything, happens in its own topic branch. For the sake of this writeup let’s imagine that I am adding some responsive features in a branch called
Firstly, I make sure my local copy of
master is fully up to date with remote. After
pulling to ensure everything is good, I create my topic branch off of
$ git checkout -b feature/responsive && git push -u
There are two things happening here, firstly I check out a branch called
feature/responsive (that didn’t yet exist). This is what
git checkout -b feature/responsive does.
Next, I want to set
feature/responsive to track a remote branch of the same name, this is the
git push -u (
&& is just an operator, and allows me to chain commands). This second command just means that I can run
git push and
git pull as just that. Without setting up remote tracking, I would have to run
git push origin feature/responsive and
git pull origin feature/responsive every time; far from ideal.
Now I have a local branch set up called
feature/responsive, that tracks a remote branch of the same name, and I’m ready to work in it.
Git to work
Now I start doing all my work in this branch. If it’s to do with responsive stuff, this is where it goes. One rule I try and stick by is ‘commit early and commit often’. After every discrete chunk of work, commit; this might mean committing ‘Add media query mixin’, ‘Set up grid system media queries’, ‘Add grid states to media queries’. These are very granular, logical commits. Committing is fast and easy, it’s better to commit too often than not often enough.
Committing is usually as simple as:
$ git commit -am "$COMMIT_MESSAGE"
For any commits that need files adding to Git, or need adding individually, I just break this out to:
$ git add $FILES_TO_ADD $ git commit -m "$COMMIT_MESSAGE"
If I get too carried away, and do more-than-one-logical-commit’s-worth-of-work in a single file, I can run
git add -p $PATH_TO_FILE in order to add ‘hunks’ of changes from one file, rather than the whole file itself. This is a pretty awesome feature, but one I’ve not used that much yet.
Completing the feature
It is worth noting that most features, like this one, can be quantified and deemed ‘complete’, but a branch like
misc-typo-fixes will have a potentially infinite lifespan and cannot usually be considered ‘done’. Depending on this, the next parts of my workflow may differ. If the feature does have finite scope—and can be deemed ‘done’—then once I’m happy with it, I
diff it against
$ git diff master feature/responsive
This allows me to review any changes visually, check my work, and hopefully spot anything that needs spotting. If this final check goes well (and inuit.css still compiles, and nothing breaks) then I’m almost ready for merging it into
This next thing, so I’m told, massively divides the Git community. It’s like IDs for Git users or something… I find rebasing, when used properly, incredibly useful. There are some people who loathe it—and will never use it—and that’s cool. I don’t know enough to have too strong an opinion, but I like using it. As with most things, with great power comes great responsibility…
feature/responsive is a private, development only, non-production branch, I can rebase it. Rebasing basically allows you to, among other things, reword, reorder and squash commits. This is the important bit; it fiddles with your Git history, and this is why people dislike it. Once you have pushed and/or shared a branch, you should see it as having missed the boat, and you cannot rebase. Rewriting Git history on a shared branch is dangerous territory. Anyway…
As I mentioned earlier, I like to commit a lot. Frequent commits, committing as I think, not taking great care over them, writing them for my train of thought as opposed to for anyone else to make sense of. As such, it’s not unusual to end up with a commit history like this:
- Add media query mixin
- Add missing semi colon
- Put MQs into use in grids file
- Fix typo
- Add comments explaining stuff
Looking at these commits, it’s pretty slapdash. That’s cool though, I committed as I worked, this is an accurate representation of what I did, however there are a few things to note:
- In a team environment—where people have to merge your work for you—they’re seeing a lot of pointless commits. It’s more for them to read and review (note, the actual commit messages, not so much the code in them).
- The typo and trailing semi-colon commits kinda make me look a bit stupid.
- There will be no desire to ever roll back to a stage in the commit history where the code didn’t have that semi-colon, so being able to roll back to that point seems silly.
- If we’re being totally honest, these could all be summed up in one as ‘Add responsive grid system’.
What we do now is:
$ git rebase master -i
What this does is replays those commits against
master and interactively (
-i) allows us to modify them. Running that command might leave you looking at something a little like this:
pick 64073f0 Add media query mixin pick 4ebe438 Add missing semi colon pick 987d093 Put MQs into use in grids file pick 324f2a2 Fix typo pick df0321b Add comments explaining stuff pick 1ed9323 Whitespace
pick can be replaced with a number of things, but the most common ones I use are
r, for reword (we want to edit the commit message) and
s, for squash (we want to squash that commit into the previous one).
What we want to do here is squash all of those commits into one nice one, something like ‘Add responsive grid system’. We need to modify the above to look like this:
pick 64073f0 Add media query mixin s 4ebe438 Add missing semi colon s 987d093 Put MQs into use in grids file s 324f2a2 Fix typo s df0321b Add comments explaining stuff s 1ed9323 Whitespace
Now we can continue on our way and squash all those commits into the top one (that we automatically get the chance to reword by default).
Now if we were to run a
git log on
feature/responsive, instead of the six nasty commits, we get one shiny new one, that is much more friendly.
Please use discretion when rebasing; only rebase if you really feel you need to, and only squash into as many commits as makes sense, no less. If you end up with ten commits and you feel that you need to keep all ten then by all means, please do so. Only rebase if and when necessary and/or appropriate.
Back to master
Now we have all our work completed and our commits nicely tidied up, we need to get
feature/responsive back into
master, ready for release.
To do this, simply check out
$ git checkout master
And then merge
$ git merge feature/responsive --no-ff
This simply merges our topic branch back into
master and forces a merge commit (massive thanks to Nick for this one). Git will, if it can, merge branches using fast forward, which basically means that it will create a ‘seamless’ merge. Merging without
--no-ff will just add the commits from
feature/responsive onto the end of
master as though
feature/responsive never existed; it fast forwards
master to be at the same point as
git log has no mention or idea of any other branches and might look like:
- Add normalize.css
- Add responsive grid system
To leave a neater paper trail, and show where everything came from, merging with
--no-ff would make our
git log look like this:
- Add normalize.css
- Merge branch 'feature/normalize'
- Add responsive grid system
- Merge branch 'feature/responsive'
--no-ff basically just gives us a merge commit and a nicer paper trail.
Good to go
Once that’s all done, I’m ready to push this feature live:
$ git push
And now I want to tag that latest commit with a version number, so I run:
$ git tag v$VERSION_NUMBER && git push --tags
This tags the latest commit and then pushes the tags to my remote.
Now I have a nice commit history, with merge commits, and a new tag that points to that particular snapshot of the project.
That, in a nutshell, is my Git workflow now for inuit.css. I’m still taking baby steps with Git, but I am loving it, and I’m learning more and more each day from a lot of awesome people.
If anyone has any suggestions as to how I might improve or streamline my workflow I’d be really grateful to hear them; along with Vim, I’m finding Git a lot of fun right now! I’d also really like to hear more pro-/anti-rebase opinions and definitely any glaring errors or mistakes with anything I’m doing.