{"id":32,"date":"2017-11-05T12:58:57","date_gmt":"2017-11-05T01:58:57","guid":{"rendered":"https:\/\/content.developerjack.com\/?p=32"},"modified":"2018-03-12T20:03:23","modified_gmt":"2018-03-12T09:03:23","slug":"purposeful-first-commit","status":"publish","type":"post","link":"https:\/\/developerjack.com\/blog\/2017\/purposeful-first-commit\/","title":{"rendered":"Purposeful first commit"},"content":{"rendered":"\n

\u201cInitial commit\u201d is so uninspiring yet we\u2019ve all committed it somewhere!<\/p>\n\n\n\n

I\u2019ve recently found myself creating a noticeable handful of repositories for various projects and it got me thinking: whats in a first commit? It\u2019s the commit that hangs around like a bad smell for years after you make it. It appears in github in that placeholder .gitignore, or in that tiny file that never gets changed. So why think about it?<\/p>\n\n\n\n

To me, a first commit helps define what the project intent is. Why are you committing this code? What do you aim to achieve?<\/p>\n\n\n\n

This morning I went exploring – whats in a first commit?<\/p>\n\n\n\n

How to find the initial commit.<\/h2>\n\n\n\n

First things first, there can be multiple first commits (well, when it comes to git anyway). For example if you\u00a0git checkout --orphan<\/code>\u00a0you create a ref with no parents. You can also get multiple parentless trees if you merge together repositories – git\u2019s own repository is a great example of this with 7 odd initial commits.<\/p>\n\n\n\n

For the purposes of this little experiment I went looking for the most logical first commit using this handy command:<\/p>\n\n\n\n

$ git rev-list --max-parents=0 HEAD --format=medium -v\n<\/code><\/pre>\n\n\n\n
This gives me enough information to make an educated guess on the first commit. If I want more I can just run\u00a0git show REF<\/code>.<\/p>\n\n\n\n
What\u2019s in an commit?<\/h2>\n\n\n\n
Every commit made should be\u00a0useful<\/em>\u00a0and detail both what and why a change is made. A message \u201cadded X dependency\u201d isn\u2019t as helpful as \u201cX is used for Y\u201d.<\/p>\n\n\n\n
Take\u00a0Chris Beams\u2019 \u201cHow to write a commit message\u201d<\/a>\u00a0for example. His 7th point highlights a great example of focusing on \u201cwhat\u201d and \u201cwhy\u201d rather than \u201chow\u201d you\u2019ve achieved something. The \u201chow\u201d goes in comments alongside your code.<\/p>\n\n\n\n
Better first commits<\/h2>\n\n\n\n
Given that each commit should describe the change it makes, it logically follows that each first-commit should set the stage for what the repository is all about.<\/p>\n\n\n\n
Perhaps the best example of this is Linus\u2019 first commit when building git.<\/p>\n\n\n\n
commit e83c5163316f89bfbde7d9ab23ca2e25604af290\nAuthor: Linus Torvalds <torvalds@ppc970.osdl.org>\nDate:   Thu Apr 7 15:13:13 2005 -0700\n\n    Initial revision of "git", the information manager from hell\n<\/code><\/pre>\n\n\n\n
Git has since lived up to its vision\u2026 no?<\/p>\n\n\n\n
Alas, surprisingly very few projects do this.<\/p>\n\n\n\n
Committing in open source<\/h2>\n\n\n\n
I started to explore language repo\u2019s including\u00a0PHP<\/strong>,\u00a0ruby<\/strong>,\u00a0Go<\/strong>\u00a0and\u00a0node<\/strong>; all conveniently found on github.<\/p>\n\n\n\n
PHP<\/strong>\u00a0has 4 initial commits, the earliest in 1999 when migrating from cvs to svn. The project later migrated to git and retained its SVN commit history.<\/p>\n\n\n\n
$ php git:(master) git rev-list --max-parents=0 HEAD --format=medium -v\ncommit 43509370272898f7a346de7e2f4c8a012d00f621\nAuthor: Bob Weinand <bobwei9@hotmail.com>\nDate:   Fri Dec 20 14:27:51 2013 +0100\n\n    Merge branch 'master' of sapi\/phpdbg into PHP-5.6\n    Including phpdbg.\n\ncommit dac2297b1062975f5d9ac417dbea518c5823b8a6\nAuthor: Joe Watkins <joe.watkins@live.co.uk>\nDate:   Sat Nov 9 14:34:16 2013 -0800\n\n    Initial commit\n\ncommit 528006a3b49fd45d6b2803c7b7843b2e7d6929d6\nAuthor: Dmitry Stogov <dmitry@zend.com>\nDate:   Wed Feb 13 16:26:47 2013 +0400\n\n    Open Source Release\n\ncommit f70a4db647886f65a3e24249351d2c8abc0cdfb3\nAuthor: SVN Migration <svn@php.net>\nDate:   Wed Apr 7 18:10:10 1999 +0000\n\n    Standard project directories initialized by cvs2svn.\n<\/code><\/pre>\n\n\n\n
\u201cInitial commit\u201d popped up again as the foundations of the phpdbg project which was accepted\u00a0unanimously<\/a>\u00a0into the core\u00a0PHP<\/strong>\u00a0project.<\/p>\n\n\n\n
Go<\/strong>\u00a0has an odd first commit with a author & committer date that at first impressions is completely off.<\/p>\n\n\n\n
$ go git:(master) git rev-list --max-parents=0 HEAD --format=medium -v\ncommit 7d7c6a97f815e9279d08cfaea7d5efb5e90695a8\nAuthor: Brian Kernighan <bwk>\nDate:   Tue Jul 18 19:05:45 1972 -0500\n\n    hello, world\n\n    R=ken\n    DELTA=7  (7 added, 0 deleted, 0 changed)\n<\/code><\/pre>\n\n\n\n
This is however part of a beautiful nod to\u00a0Go<\/strong>\u2019s origins in C.<\/p>\n\n\n\n
$ go git:(master) git log --reverse --format="%h %aI %s" | head -n5\n7d7c6a97f8 1972-07-18T19:05:45-05:00 hello, world\n0bb0b61d6a 1974-01-20T01:02:03-04:00 convert to C\n0744ac9691 1988-04-01T02:02:04-05:00 convert to Draft-Proposed ANSI C\nd82b11e4a4 1988-04-01T02:03:04-05:00 last-minute fix: convert to ANSI C\n18c5b488a3 2008-03-02T20:47:34-08:00 Go spec starting point.\n<\/code><\/pre>\n\n\n\n
Ruby<\/strong>\u00a0shared a similar origin commit to PHP as it was brought across from cvs to svn (and its remained in svn).<\/p>\n\n\n\n
$ ruby git:(trunk) git rev-list --max-parents=0 HEAD --format=medium -v\ncommit 392296c12de9d7f9be03a8205250ba0844cb9d38\nAuthor: (no author) <(no author)@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>\nDate:   Fri Jan 16 12:13:05 1998 +0000\n\n    New repository initialized by cvs2svn.\n\n    git-svn-id: svn+ssh:\/\/ci.ruby-lang.org\/ruby\/trunk@1 b2dd03c8-39d4-4d8f-98ff-823fe69b080e\n<\/code><\/pre>\n\n\n\n
Node<\/strong>, however, was founded on dependencies. The irony of which is not lost on me.<\/p>\n\n\n\n
node git:(master) git rev-list --max-parents=0 HEAD --format=medium -v\ncommit 9d7895c567e8f38abfff35da1b6d6d6a0a06f9aa\nAuthor: Ryan <ry@tinyclouds.org>\nDate:   Mon Feb 16 01:02:00 2009 +0100\n\n    add dependencies\n\n$ node git:(9d7895c567) cat .gitmodules\n<\/code><\/pre>\n\n\n
[submodule “deps\/oi”]<\/p>\n\n\n\n
\n    path = deps\/oi url = git:\/\/github.com\/ry\/liboi.git\n<\/p>\n\n\n
[submodule “deps\/ebb”]<\/p>\n\n\n\n
\n    path = deps\/ebb url = git:\/\/github.com\/ry\/libebb.git\n<\/p>\n\n\n\n
Swift<\/strong>\u00a0has a nod to its origins in SVN but it appears we have two missing commits of history given that this commit started from R3<\/p>\n\n\n\n
swift git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit 18844bc65229786b96b89a9fc7739c0fc897905e\nAuthor: Chris Lattner <clattner@apple.com>\nDate:   Sat Jul 17 23:50:59 2010 +0000\n\n    initial swift test\n\n\n    Swift SVN r3\n<\/code><\/pre>\n\n\n\n
\u201cInitial Commit\u201d<\/h2>\n\n\n\n
Beyond these language examples, almost all tools, frameworks, libraries etc. that I explored had a \u201cinitial commit\u201d of some kind. All of which were unhelpful.<\/p>\n\n\n\n
At least\u00a0laravel<\/strong>\u00a0named itself\u2026<\/p>\n\n\n\n
$ laravel git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit a188d62105532fcf2a2839309fb71b862d904612\nAuthor: Taylor Otwell <taylorotwell@gmail.com>\nDate:   Wed Jun 8 23:45:08 2011 -0500\n\n    initial commit of laravel!\n<\/code><\/pre>\n\n\n\n
A first commit however should detail what you intend to achieve by committing code. What a project is (or isn\u2019t) is an important foundation on which any project is based.<\/p>\n\n\n\n
Take for example\u00a0Bootstrap<\/strong>. Prior to being released as an open source project it was known as Twitter Blueprint. There\u2019s a nod to that in one of bootstrap\u2019s initial commits.<\/p>\n\n\n\n
$ bootstrap git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit 4bb7653f67b60fcf464d6c30e2ebe1b87d2dbc31\nAuthor: Jacob Thornton <jacobthornton@gmail.com>\nDate:   Tue Jan 31 17:35:23 2012 -0800\n\n    move examples into docs...\n\ncommit eb81782cdbdc68aaebe4fa561b5fbb73ef866611\nAuthor: Mark Otto <markdotto@gmail.com>\nDate:   Wed Apr 27 13:53:51 2011 -0700\n\n    Porting over all Blueprint styles to new Baseline repo\n<\/code><\/pre>\n\n\n\n
Other frameworks including\u00a0jquery<\/strong>,\u00a0laravel<\/strong>,\u00a0vue<\/strong>\u00a0and\u00a0jekyll<\/strong>\u00a0all had more or less useless initial commits. Entertainingly, jekyll did thoughtfully include a README.txt\u2026 that was an unmodified template. Some digging into Vue\u2019s initial\u00a0package.json<\/code>\u00a0included the description \u201cLighter-weight Vue on virtual dom\u201d which I guess is something.<\/p>\n\n\n\n
$ jquery git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit 8a4a1edf047f2c272f663866eb7b5fcd644d65b3\nAuthor: John Resig <jeresig@gmail.com>\nDate:   Wed Mar 22 03:33:07 2006 +0000\n\n    Inital Import.\n<\/code><\/pre>\n\n\n\n
$ laravel git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit a188d62105532fcf2a2839309fb71b862d904612\nAuthor: Taylor Otwell <taylorotwell@gmail.com>\nDate:   Wed Jun 8 23:45:08 2011 -0500\n\n    initial commit of laravel!\n<\/code><\/pre>\n\n\n\n
$ vue git:(dev) git rev-list --max-parents=0 HEAD --format=medium\ncommit a879ec06ef9504db8df2a19aac0d07609fe36131\nAuthor: Evan You <yyx990803@gmail.com>\nDate:   Sun Apr 10 22:47:28 2016 -0400\n\n    init\n<\/code><\/pre>\n\n\n\n
$ jekyll git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit d189e05d236769c1e5594af9db4d6eacb86fc16e\nAuthor: Tom Preston-Werner <tom@mojombo.com>\nDate:   Sun Oct 19 19:07:26 2008 -0700\n\n    first commit\n<\/code><\/pre>\n\n\n\n
A better first commit<\/h2>\n\n\n\n
An initial commit should stand out as a descriptor of the project. Why are you committing this code? What do you aim to achieve.<\/p>\n\n\n\n
To that end I ensure that my initial commits contain almost no changes and almost all message. I may add a very basic\u00a0.gitignore<\/code>\u00a0file or a rudimentary\u00a0README.md<\/code>\u00a0at most.<\/p>\n\n\n\n
Take\u00a0endpointer<\/a><\/strong>\u00a0for example; here\u2019s the first commit I ever made to the project:<\/p>\n\n\n\n
$ endpointer git:(master) \u2717 git rev-list --max-parents=0 HEAD --format=medium\ncommit 60daa711ce0e46425c000702fd0d58134454bcbd\nAuthor: Jack <jack@developerjack.com>\nDate:   Sun Aug 20 14:39:18 2017 +1000\n\n    Endpointer transforms OpenAPI specifications into endpoint documentation.\n\n$ endpointer git:(master) \u2717 git ls-tree --name-only -r 60daa711c\n.gitignore\n\n<\/code><\/pre>\n\n\n\n
My most recent tool in the\u00a0endpointer<\/strong>\u00a0project is\u00a0mario<\/a><\/strong>\u00a0and has a similarly helpful initial commit (from earlier today).<\/p>\n\n\n\n
mario git:(master) git rev-list --max-parents=0 HEAD --format=medium\ncommit dd5813bba7980d571e68573ba0330819f3b390ce\nAuthor: Jack <jack@developerjack.com>\nDate:   Sun Nov 5 11:05:01 2017 +1100\n\n    Mario is yet another package management tool for documentation.\n    It works well with endpointer and static site content.\n<\/code><\/pre>\n\n\n\n
So for your next project or repository, think about what you want to achieve and set the stage for the next big open source project!<\/p>\n","protected":false},"excerpt":{"rendered":"
\u201cInitial commit\u201d is so uninspiring yet we\u2019ve all committed it somewhere! I\u2019ve recently found myself creating a noticeable handful of repositories for various projects and it got me thinking: whats in a first commit? It\u2019s the commit that hangs around like a bad smell for years after you make it. It appears in github in […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[4,6],"class_list":["post-32","post","type-post","status-publish","format-standard","hentry","category-blog","tag-open-source","tag-projects"],"_links":{"self":[{"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/posts\/32","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/comments?post=32"}],"version-history":[{"count":0,"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/posts\/32\/revisions"}],"wp:attachment":[{"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/media?parent=32"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/categories?post=32"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developerjack.com\/wp-json\/wp\/v2\/tags?post=32"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}