rebooting 2013… half a year of change

Posted: March 4th, 2013 | Author: | Filed under: Personal | No Comments »
Tan Son Nhat airport - Sunset

Tan Son Nhat airport – Sunset

If there’s one photo to describe my whereabout the past half year would be the one above: juggling between Singapore and Ho Chi Minh.

A lot has happened since July 2012. It’s been a short yet life-altering couple of months for me and everyone else involved. No one was even close to predicting anything that is in motion today, and certainly no one was sure of anything would happen yet we did, once again, trusted our gut and went ahead.

Looking back just mere 3 years ago around March 2010, I’m still sitting in school, no clue what to do with the graduating thesis; despite the fact that I then already had my name as co-founder of what now has became a hundreds-strong corporation. So I took a break after graduation and find a full time developer job at Anideo. Up until late 2012, I was still happily pushing code and polishing a killer app while receiving a decent pay-check that is still a dream to many today. All that came to a stop abruptly for several foreseeable and unfortunate reasons including my boredom of a day job.

Fast forward just a month or two, after weeks of being in a trough and direction-less, I found myself hesitantly taking up the post of managing entirely new company on it own. Officially, that was shy of 5 months ago. Being an engineering spirit person, I have never had the need to run a company but this time I knew there’s no other choice. Today, the team is still small, and that didn’t seem to affect the fact that we have been and are still achieving some rather incredible numbers; we have just had a nice office that we truly call ours; great team dynamics; comfortable working environment…

I certainly had to make lots of decisions, the kind that you can’t learn or read from books. A lot of times it was based purely on instinct and putting everything as a bet, knowing that only time could judge. I had no management training, just a vast pool of technical expertise and that will continue to be the base of my foundation for the time to come. What I also have is the fact that I have failed several times and saw people failed even more miserably before they could start anything.

Obviously I’m no expert but I realised there must be something about the way I (want to) do things that people find interesting and inspiring, for that reason this rebooting entry will signify the focus shift of my blog, from technical development to a more managerial-sharing focused perspective. Mostly the context will be of Singapore and Vietnam startup scene, learnings through the eye of a first-time engineer-turn-manager person, occasionally some complains about shortage of devs, and hopefully some small contribution to the open source community when I’m bored.

I’m sure if you have come to like my previous writing style, you’ll love the next part even more. Subscribe to receive future posts using the form on the right side here.

Damn it, i’ll opensource, just buy me coffee instead

Posted: June 7th, 2012 | Author: | Filed under: Development, iOS | 8 Comments »

I started writing a custom control for iOS since about a week ago. The initial idea was that it’s going to be part of a bigger application that I will be working on and it’s going to be a versatile and reusable component that could potentially save countless number of hours for other developers as well.

I decided to write it from scratch because there aren’t quite anything out there could do the job, although the task it serves is quite a common one: select multiple items from a long list – a generic selector/picker control. I found this, this and this, however they are rather outdated and written for a specific purpose of selecting people (phone or email).

So as I was writing it, it gets more and more complicated with several configuration options that I need in my project. That’s why it also became clearer and clearer to me that there is a need for such generic UI control. I can already imagine it being used in many app ideas that I have in my mind.

Closer to completion, I am very certain that I’m going to sell this component for a small fee, at least compensate for the time I’ve spent. Plus I’ve already written a commercial component that is doing not too badly.

The last bits of the package was the documentation, licensing and pricing. As I did some research to pick the correct license and some calculations to get the pricing, it suddenly struck me that the process of developing custom controls has instilled an idea: to commercialize every UI components that I will develop. Not a good way to think about iOS development.

Fast forward to an hour later, I found myself rewriting the About page and pushing the code to a public Github repo. So damn it, I’ll just opensource and just let people take the code, improve it and probably pay whatever amount they think it deserves.

Here is the component and here’s the commit if you are curious. Check it out let me know what you think in the comment below. Would it have been a good-selling component if I were to sell? How much would you pay then?

KNMultiItemSelector – A multi-item selector/picker

Posted: June 7th, 2012 | Author: | Filed under: Custom UI, iOS | No Comments »

KNMultiItemSelector is a versatile drop in multiple items selector for iOS projects. It works with both iPhone and iPad for several usage scenarios. See features and screenshots below.

It is best use for selecting several items in a long list of hundreds or thousands of items such as contact list of Facebook friend list.


  • Multiple items selector with simple NSArray
  • Subclass of UIViewController
  • Enable/Disable table index
  • Enable/Disable search control
  • Enable/Disable recent items
  • Optional image with out-of-box caching
  • Facebook friends selector demo project

Basic Demo & Facebook Friends Selector Demo

iPhone and iPad screenshots

Source & Usage examples

You can get the full source-code from Github:

Visit Documentation to see how it is used and other configuration options

Boilerplate Facebook application for iPhone

Posted: May 13th, 2012 | Author: | Filed under: Custom UI, iOS | No Comments »

For the past few weeks, I have been checking out a website called Binpress. Which is the commercial alternative to CocoaControls. The site is still new but it already has several components in it and not limited to just iOS stuff. They still have a lot of kinks in the publishing process, however, I find that the quality of components here are slightly better than those in CocoaControls, perhaps because the authors spent more time to polish up a paid package. However, I have to say this only applies to Obj-C components, the other languages are still behind CodeCanyon. Their commission is fixed at 30% though, much better than CodeCanyon which takes frickin 50%-70% of the sales!!!

So I published two open-source components of mine as a trial about a week ago. They are the KNPathTableViewController and KNSemiModal.

So I also decided to try writing a commercial component that could be huge time-saver for iOS beginners. Given that there are a lot of companies in which the web developers now have to take up iOS programming to serve the changing need, I can see that there are a lot of developers struggling with getting a quick ready-to-use application template to start with. A template which they can just open up and instantly have Facebook connect and WYSIWYG welcome pages.

For a beginner, it is a daunting task having to know how to build and import libraries needed. With this application you don’t have to worry about those and just get your app running right away. This application is meant to help you get started your iPhone app quickly with Facebook login handling built right in and more importantly having an onboarding/welcome UI that you can modify easily with Interface Builder.

So here it is: Boilerplate Facebook application for iPhone on Binpress
Head over there and you’ll find all the details about screenshots and even a demo video!


Posted: May 10th, 2012 | Author: | Filed under: iOS, UX | 6 Comments »

(My free set of personal namecards from
This post is a guest post written for Inspired Magazine on the same topic of understanding user experience.

What is UX?

UX stands for User eXperience. A little more comprehensive would be: the entire interaction that starts even before your user uses your product until long after.

I don’t remember when I began to hear the term UX, but definitely not when Windows eXPerience was introduced. I’m pretty sure all the hype about having great UX just started within the last two years. Before that, everything I knew about making websites emphasized mostly on good UI. But now, it’s simply not enough. What ever you do, it has to have great UX.

What I think UX really is

To me, every little details make up the entire experience and not just what you see. Putting that into a website/app context it would mean tons of things: how your users got to know about your site? is it easy to download your app or get to your site? is it a simple series of actions to start using your service? do you have a way to guide and help the user in the beginning? are your buttons at where the users expect it should be? do the buttons have the glow effect when you touch them? What if their network has problem, how do you tell them? How many clicks before they would get to do what they want to do? What if the user need to contact you? do you have support service? etc… the list is endless.

UX is about the entire experience, UX is about satisfying the needs of your users, make them feel comfortable using your service. While UI is simply the visuals.

I recently attended a seminar by Ben Hamey from Bonono and in his slides, the exact words are “User experience is anthropology, psychology, usability, research, behaviour, graphic design”. I couldn’t agree more.


Great UI does not mean great UX
Bad UI does not mean bad UX

The full-flash hotel sites or wedding planner sites are usually designed by actual artists, and that’s why they are very cachy, interesting. But what puts me off most of the time is the slow loading time, frequent crashes and because the navigations are so unconventional that I don’t even know where to click to get information. It’s easier to give up and find another site than to spend time figuring out.

On the other hand, sites like Craiglists, HackerNews have very poor text-based UI, but they have excellent UX because they do exactly what the users expect them to do, fast!.

Craiglist is simply a place to find and sell used things, as long as I can post my old TV or buy a used bike, I’m happy with it. I don’t care if it is a pure text action link or a fancy button. I just want to get over it quickly.

Some might strongly disagree with me that a site with bad UI can’t have great UX. Well, a few millions users per day couldn’t be wrong. People just love getting things done easily and quickly. You might want to do that in style, but it’s just you, not the other millions.

And ofcourse there are full of examples of bad UX. I found this interesting recent article that describe exactly what I wanted to say about the state of business software: What’s the waiter doing with the computer screen?.

How I learnt UX

When I first got my iPhone 3G, it was simply wow at first sight of the UI. However, only until a few months later I started to realize the passion to make great software and stop making crappy websites. There wasn’t much resources on the Internet about UX back then and even I didn’t quite fully understand the term itself like I defined in this post.

So I tried and failed, at the beginning it was mostly the desire to create nice UI, but that wasn’t enough, there was always something missing in the works I’ve created. I was too focused on a single page at a time and didn’t see the big picture. I downloaded tons of apps on the phone. Some good, and a lot of bad apps. I started to pay attentions to extremely small details on the screen.

Then one day, I spent 15 minutes just to examine transition of the header when “Back” button is pressed and that’s when everything kicked in. I started to see that it’s not about any single element of the design or the whole design, it’s about how things are connected together and those tiny invisible links matter more than the entire UI.

From that day, whenever I hear about a new app, I search for it, look at the website, then the copywriting and design/navigation of the website, then download the app, try to make it fail, try to stop the registration process half way and resume, try to break the best case scenarios or closing the app while it’s doing some heavy processing, etc… I began to spot a very distinct pattern between a great app and a normal or bad app. The best apps handle all those disruptions extremely well and I can always pick up from whatever I did (wrong).

The truth is that it takes a lot of effort to create such a seamless experience and it’s not something developers especially the beginners want to be doing. Implementing great custom UI is hard enough, creating a seamless transition between actions requires solid but flexible architecture.

To sum it up, if you want to learn how to create great UX, begin downloading apps and inspect them with a microscope today!

If you like my stuff, do checkout the iOS custom UI components that I wrote by checking the links on the right side bar. Perhaps that would save you some time when developing your killer app.

Semi-modal view with better context

Posted: May 4th, 2012 | Author: | Filed under: Custom UI, Development, iOS, UX | 7 Comments »

For a long time, since beginning of iPhone programming, the modal view has not had any major innovation. A quick search on cocoacontrol for “modal” returns 3 types of modal view:
– Fullscreen cover-up modal view
– Centered-popup type
– Date selector modal

The context problem

Out of the 3 types, the date selector is the only type that keeps the user aware of the current context that he is in (date for which field). By contrast, the other types of modal view practically cover up the entire screen and none or little context is visible. These implementations have been sufficient so far and sometimes the developers just have to include some context within the modal itself by setting the view’s title or include some kind of static labels.

But what if we could do better by adopting the same interaction by the date selector component? What if we need to somehow keep most of the context visible while presenting user with supplementary controls for adjusting behaviors of the context?

The Park Guides app by National Geography

The beautiful Park Guides app (iTunes link) launched just recently in Apr 2012 did an excellent job in solving the context problem.

So instead of the usual fullscreen modal view/popup view/UIActionSheet, the app shows a semi-modal view on top of the current view similar to the date selector component. However, the most interesting feature of this app is the way the current context is kept visible using a nice subtle animation. Instead of simply dim the view in the background like UIActionSheet, the entire view is scale down to about 80% and pushed back like a stack, creating a unique wow effect and at the same time, more of the background view is visible to the user. This is a great new way to interact with iPhone components.

It’s best to view the effect in a video clip here (1.3MB, .mov)

When it works, when it wouldn’t

Arguably this fancy implementation may not work in all cases. If you have a long Settings modal view in your app, it is not suitable. Or if you have a modal screen with text input, it wouldn’t work at all.

Nevertheless in many of the use cases it will be excellent addition to your app. Say for example you have a long Settings screen and different Tabs in your app, you might want to consider breaking down all the settings into different places where they are being used there and then.

Another use case showed in Park Guides app is providing extra content to the current view with a modal image (2nd screenshot above), adding more context while facilitate information-hiding.


In an attempt to learn CATranforms3D for the first time and replicate the same experience, I’ve created a custom Category add-on for UIViewController that makes presenting such a custom view easy.

Here’s the post explaining the library : KNSemiModal Category for iOS

Or you can go directly to the source file on Github here UIViewController+KNSemiModal

KNSemiModal Category for iOS

Posted: May 4th, 2012 | Author: | Filed under: iOS | 8 Comments »

UIViewController+KNSemiModal Category

UIViewController+KNSemiModal is an effort to make a replica of semi-modal view with pushed-back stacked animation found in the beautiful Park Guides by National Geographic app. You can see this original semi-modal view below.

The pictures don’t really describe enough the cool factor of the implementation. You can download a short video I recorded to see the effect : demo video (1.3MB, .mov)

Why I do this?

Please read my discussion in a separate blog post. I highlighted some issues with the current implementations of the modal view and how I think it can be better

Drop-in installation

This library (ARC) is designed as a Category to UIViewController so you don’t have to subclass and you can simply drop in any project and it will just work!

Copy 2 category files UIViewController+KNSemiModal to your project and add this import line at the top of your current ViewController file

#import "UIViewController+KNSemiModal.h"

You can prepare your UIView * myView with all the controls and subviews that you need before presenting it with

[self presentSemiModalView:myView]

Another convenient method is presenting a separate ViewController class by calling

[self presentSemiViewController:myOtherViewController]

However, note that this myOtherViewController need to be retained manually by assigning it to a @property or ivar.


  • Landscape support.
  • Maybe iPad support, it will be quite different though.
  • Fake ivar with Associative References to retain ViewController
  • Subclass branch (anyone can spare the time?)

Source code

UI responsiveness: OSX vs. Windows, iOS vs. Android

Posted: March 30th, 2012 | Author: | Filed under: iOS, UX | 76 Comments »

I started using Apple products since 2007, when I started college. I used all my savings to order a custom 15″ Macbook Pro mid 2007 model with glossy screen (back then it was default to matte). And I then adopted iPhone trend beginning with iPhone 3G. Before that I had been a long time Windows user, starting all the way from 3.1 til XP. On the mobile side, I tried all kinds of smartphones including S40,S60,WM6.0,WM6.5,WinCE, even Linux phone.

For a very long time before the Mac and iPhone, I have never had the feeling of “this is it” for any laptop or phone that I owned. But once I embraced Apple product, it just felt right. And I always find it’s hard to explain or convince someone with simply “just right” reasoning.

A few weeks ago, I came across a post on Engadget and that really helped me to put all the pieces together and explain this phenomenon. The video in the article shows a vast difference in the user experience between a 100ms and 1ms lag time. That sparked everything else in my mind for this post.

Windows vs Mac OSX, the keys

Coming from a long history with Windows, I was very surprised to see how fast OSX was. Not in term of very demanding task but in term of extremely simple and common daily tasks such as opening a folder, file, copy, moving stuff around the screen. My very first impression was that the interface never freezes on Mac. Compare that with the infamous ‘cloned dialogs‘ bug on Windows.

So I did a bit of research, trying to understand why. Turned out the problem is much deeper than I thought: Fundamentally, Windows is meant to run on as many combinations of hardware as possible, while Mac was only meant for Apple hardware. I’m not an OS-engineer but my guess is that the number of abstraction layers in Windows has to be a lot more than in Mac. Because of that the overhead is a lot more for simple tasks like user input. And so that could have lead to more processing cycles.

Until today, having to switch daily between Win and Mac on the same machine running SSD, I still feel the lags of immediate responses in Windows UI. I’m a power user, doing stuff mainly with shortcuts and seldom with mouse. Many of the times the OS couldn’t keep up with quick window switching, key presses and sometimes typing ‘stucked’ for a few seconds and then the letters just spit out all at once. It doesn’t mean these don’t happen in OSX, they do, but much less frequent and the ‘freezes’ are much shorter. That brings me to the next point.

I do think that this is extremely important because on Windows, I always have that feeling “what I typed did not seem to be registered” and makes the whole OS seems to be unreliable although it is not. However, on OSX, I don’t have this same feeling of uncertainty, instead, I have a great feeling that no matter how fast I typed or used the shortcuts, they are always executed correctly. This is partly why I always felt ‘just right’ working on Mac.

iOS vs Android, the touches

iOS was built with all the principles of OSX and back in 2007 when the original iPhone was launch it created such a long-lasting wow impression for any one coming in touch with it. While Android was introduced not really long after but the initial impression was not as successful.

There are many reasons to that but personally I would love to credit that success to how responsive the UI on the device was compare to others at its time. As I mentioned, I was early adopter for many mobile platforms and the common (bad) trait of all of them was the huge delay of the interface, from the time you touch the screen to the time something happens.

Despite being a now-dead-slow device, the original iPhone has two extremely important features that are still very fast compare to today’s standards: touch response and responsive scrolling. The device immediately shows something, either a change of color or a glow effect when you touch the screen; and continuous dragging on the screen maintains the same pixel position relative to the finger. Both of these were poorly implemented in other mobile platforms and I would say in the early Android 1.x platforms as well.

That’s why I think Apple nailed it and started the mobile device revolution that are easy to use and great to the touch.

My UX principle: show something, anything

Among many UX principles that I derived from years of using Apple products, there is one that is directly related to this post and it’s not very hard to do: Show something, anything!

What that means is for any user interaction event, on web or mobile or desktop app, you need to show a change in interface. Anything. As long as it gives the instant feedback to the user that their action has been acknowledged and the system is processing the request.

This is even more essential in mobile app or handling network requests because they are always slow. Changing button color, showing an animated indicator, faking partial result list, … are all interface tricks that gives the impression of a fast application.

In one of my applications (Denso), I did use a lot of these tweaks to make the app feels a lot more snappier. Being an internet app, it has to make many network requests to different servers, no matter how fast the device could get, network latency is always a tough issue to handle.

Windows 8 could be something

I’m not bias against Windows or any OSes, I’m just stating my observations as a power user.

In fact, the Microsoft prototype video above was very impressive, not only that, just a day before this post, another Microsoft video became trending : Microsoft explains why Windows 8 touchscreens will be better. It is definitely a great showcase and I think Microsoft, with Windows 8 coming soon, is getting somewhere this time.

Also, Windows Phone 7 is a big step up for Microsoft’s mobile platform. I was very impressed with the responses of UI on the Lumia 800. I have not been using WP device extensively but I think finally MS got it right to the touches.

Dear business people, an iOS app actually takes a lot of work!

Posted: January 31st, 2012 | Author: | Filed under: Development, iOS | 233 Comments »

The big question: How much does an iPhone app cost?

This is a very common question that I’m asked by a lot of my business-oriented friends and non-tech savvy clients. Without fail, every single time I gave my initial estimation before even locking down the specs, I received that shocked expression because of the unexpected (high) quotation.

Yet, none of my quotations has even came close to the range being discussed in this StackOverflow thread, in which the development cost of Twitterific app is discussed. Despite the fact that the original question was asked in 2008 and the best answer (by one of the Twitterific developers) was in 2010, it is still accurate today in Jan 2012 and I can foresee that it will still be true atleast until the end of 2012.

So, with the hype of businesses wanting to have an iOS app continues into 2012, I thought it would make a good post trying to explain why the cost is high by breaking down the steps and variables involved. I hope it will benefit both the non-iOS developers and business people who need to make decisions or just want to understand the process. The ideas in this post are not restricted to just iOS, they are also applicable to other mobile platforms (Android, Windows Mobile, maybe Blackberry) to a large extent.

Checklist: Getting ready for the iPhone app

The process is not a simple one and I usually guide/educate the client through all the considerations using the following steps:

FIRST: One of the most shocking discovery I have after speaking to several clients is that they have no idea about the big infrastructure picture needed for an iPhone application. Because of that they always assume iPhone app is only an app, they expect me to quote them the price for making everything possible within an app without regard to issues such as: do they have a supporting server that the iPhone speaks to, where do they store users’ data (I’m using layman terms here). The first time I met such a client I was furious, however, later on I came to a realization that because the client-server network concept has boiled in my blood since I started programming, I took it for granted that everyone knows. But I was wrong, business-type person doesn’t care and they might not have the technical common-sense you expect.

So to non-tech savvy readers: You need to have a server to store your data if you are looking to do an app that has some kind of authentication/login, or some kind of customization that you want to change it yourself at any time, or even involving simplest form of receiving information from the user (again, i’m using very simple language here).

SECOND: Because of the fact that you need a server, you need to have a way for the iPhone to communicate with the server, sending data to and receiving data from this server. There is no standard way, there is no plug-and-play way to do it, everything has to be customized. This is analogous to creating your own set of language: you don’t want others to understand what you are speaking with your server but two ends need to understand one another.

This is called creating a set of API endpoints (or simply APIs) for your application. These APIs must be in existence before you can proceed to make the iPhone app. Why? Because you need to define the language, before you can communicate! That brings me to the next step, how to create these APIs.

THIRD: Do not take this step lightly, APIs should be viewed as important as 50% of the entire solution. Making APIs is almost like making a full website. You need to first define your data models, the business rules, what are the input parameters of your business logics, how do the data models interact with each other when an event happens. To put it very simply, the outcome is a fully functional website but the pages do not show graphical results, they show only text: an example successful authentication page only contains a single word YES.

The iPhone then makes requests to these pre-determined endpoints (login page) with the pre-determined format of inputs (user+password) then interprets the result that these pages return (YES/NO). The app doesn’t magically register and login the user by itself.

There are *a lot* of variables to be considered in this phrase such as how to pick the server, how to select the language that will be written in, where to host your data to minimise communication delays, etc. I won’t get into details because if you don’t know, you should ask your tech-cofounder or let the developer decide.

FOURTH: Either you need to have this set of APIs ready, well documented by your in-house team to give to your iPhone developer or prepare to pay more than just for the iPhone app. Depends on the developer that you engage, he might or might not have the skills needed to do what you need. If he does, I suggest you to let him do both because then he knows exactly what APIs to call and what is needed to be done to make the app works.

In the case that you already have APIs, you should expect to let the iPhone developer speak freely with your back-end team beside giving him the documentations; because most of the time, he will need to request more work (more APIs) to be done to support the mobile application.

Now, the iPhone part

Phew, that’s a lot just to get ready for your iOS app but now you can start thinking about the iPhone app itself. In general, everything about iOS is very restrictive. You almost have to define 100% of the scope and lock in the design before the developer can start to code, unlike making websites, developing an iOS app under contract has extremely little leeway for changes:

Design the interface: Whether you will use all standard interface components or customized components that will have to be decided right from the start. Because the architecture of the entire application itself depends on how you want your interface be, how the users should use the app. An example is the standard Tab Bar at the bottom, if you want colors icons instead of the blueish tint, the change in code is substantial!

Tightly integrated code: With websites, you can simply add one more page, then create a link to that page when you needed. However, you can’t do that with iOS app, everything has to be set in the beginning, any changes might result in significant other changes that you might not be able to understand why. The way iOS codes are structured is like a breadboard, everything is hard-wired, you still can change a few things here and there, but if you change the wrong wire, the whole board might stop working. Even extremely well structured code does not increase the flexibility by a lot. Adding an additional email button to ‘About’ screen might only be worth a few more lines of code, but adding a Facebook Like button on the same page is a different story, don’t expect that to be done in a few hours.

Converting an iPhone app to iPhone/iPad universal app: This is the worst ‘additional feature’ found in iPhone development contracts. Because an iPad app is not a frikin’ additional feature. The iPad app is always more complex than iPhone app, and most of the time requires entirely different interface and interaction mechanism. It’s like making an electric bicycle and then convert it to a fuel-powered motorcyle! They are very similar at what they do, but under the hood, the difference is immense.

Take the popular Facebook app (in 2012) as an example, the iPad and iPhone app look similar yet they are very different, the way in which a user interacts with stories is substantially different.
Not only that – the API requirements could also be different underneath: The Denso app, an app that I worked on (which is why I know), has some features exclusive only to the iPad that require additional data from server. Additionally, the iPhone and iPad have very distinct user experiences.

So are you ready to begin?

I hope after reading this, you can get a sense of what is needed for you or your company to develop a mobile app. Unless you are making an offline app (like a Calculator app!) that does not collect any data from users, you are not going to get the app made on the cheap side. After considering all the variables above, if you can’t justify contracting development, then the only other option is hiring full time developers to work in-house for the entire length of the project.

On the other hand, if you decide to go ahead and outsource, then I have one more thing to say: The red tape. If you work in a large corporation or regulated environment, your job is essential in helping the developer avoid the red tape along the way, maybe bend the rules a little. I have spoken to a few large clients and they were very skeptical when I asked to look at their APIs. Either they were not willing to open up as it would violate their policies, can’t blame them; or they have yet a properly defined policy for external data access; or even as bad as the brand guideline requires the app to have company logo on every single screen(!!!). In the end I didn’t work with those clients because I cannot imagine how long it would drag and how much trouble I will get into when I need to ask for additional API support.

P.S You need time, lots of it, so be patient.

If you like this post, please take some time to vote or place a comment on HackerNews and follow me on Twitter @ntluan or check out the app I mentioned earlier.

Visualized Git practices for team: branch, merge, rebase

Posted: January 28th, 2012 | Author: | Filed under: Development | Tags: , , , , , | 25 Comments »

The need for a simplified guide on git for teams

For the past few weeks, a few of my friends got started using git and github for their projects, some started afresh, some came from SVN background. Despite knowing all the basic commands (push, pull, checkout, merge) they found themselves confused in actually putting those together to best work for their teams.

I started using git about a year ago, but I only started to really get a sense of the best practices since a few months back while working simultaneously in a team of 3 on master branch of the Rails backend for Denso.

Even long-time git users found it hard to explain all the concepts to a beginner clearly especially on rebasing topic. The problem is that there are so many materials you can easily find on Google, *however*, they are mostly too advanced like this one, or usually in separate articles.
In other words, the resources I found on Google don’t tell you what the hell it is and how to apply it in in layman terms, they tell you how it works, how nodes are moved and stuff, which you honestly don’t care!

So, out of frustration of having to explain it again and again, I hope this post will help you visualizing the 3 very important concepts for your team and something you can copy & paste it to your next hire.

Note: This post is not meant for the absolute beginners, I’m assuming you have been working with git for some time: knowing how to create/clone a repo, commit changes, push, pull, create branch, switch branch, merge, adding/removing remote repos. If you are looking for a beginner git guide, I suggest this excellent summary from StackOverflow.

The github graph

Below is a sample of github’s graph, an excellent tool to visualize the team’s effort. I use it daily and seriously cannot live without it. This shows an example three-day period of commits.

Take your time, there’s nothing really new about this. I only added some annotations make it clear later on this post.

Learn git CLI by heart, stop using GUI

The first and most important practice of git is learn all the git commands by heart and use them, do not rely on GUI for git, because I tried some of the clients, even GitHub for Mac, and sometimes they introduce more junks than just your commits. It will get *extremely messy* when you need to do stuff like merging and branching.

I use CLI for all the git actions (push,pull,rebase,branch,checkout,merge) except git commit. For committing changes, I use GitX because I can selectively select the lines to be part of a single commit. Plus, I can see in realtime, the files affected without having to type git status all the time.

Branch out, merge often, keep in sync

The picture above shows that I’m working on my_branch branch. So one of the common question I’m asked is when should I branch out. There are pretty clear rules about keeping your codes in a separate branch from master branch:

  • You are about to make a major or disruptive change
  • You are about to make some changes that might not be used
  • You want to experiment on something that you are not sure it will work
  • When you are told to branch out, others might have something they need to do in master

After branching out, you should keep in-sync with the master branch, because eventually you need to merge it back to master. In order to avoid a huge complicated mess of conflicts when merging back, you should commit often, merge often. As a simple illustration, the picture below shows the same graph before but with different annotations.

Compare with this with previous diagram, you can see that at the begining of each working day, I pull the changes from master into my branch (merge). I do this often and sometimes solve a few minor conflicts along the way. At the end of 2nd day. I merge my branch back into master without a single conflict! Smooth like butter.

The syntax is simply:

git checkout my_branch // Just to make sure I'm on the right branch
git pull origin master // Read: pull the changes from origin/master into my current local branch my_branch

Another practice is rebasing the changes in master to your branch, however as you can see I’m striking this out because I found it extremely confusing, I do not use this method because it won’t show up as nice arrows on your github’s graph. You should just forget about I’m ever writing this after reading the next section

The mysterious & forever confusing ‘rebase’

This is my own definition, it’s not technically correct, but take it and it will make your life so much easier: (on current branch) git rebasing is taking all your local changes since the last push and put them ahead of other people’s changes regardless of the date you made the commit.

Base on that, git pull --rebase means pulling all the new changes made by others, then taking all my changes that are not yet pushed, and put them ahead of other people’s changes on the current branch.

So why am I striking out again, because I do not want you to remember this: It is not technically correct because rebasing can work across branches, but it is too confusing to be used that way. Just stick to the current branch

The picture above shows the effect of git rebasing when done correctly.
Below are the sequence I use everytime for rebasing:

git commit -am 'My changes'  // While i'm working on my machine
                             // <-- My colleague did a "git push" here
git pull --rebase            // So before I can push, i need to rebase
                             // Another syntax: git pull --rebase origin my_branch
git push                     // Now my changes are on top

The focus of this is the pull command, with additional --rebase parameter.
Before you wonder, yes, that is all you need to know about rebasing. Just one extra parameter. That’s it! Stop your mind from wandering because it is only that simple.

Perhaps you also wonder why people can’t explain it simply that way? Because git rebasing is indeed a lot more complicated, but for small team, I suggest that git rebasing to be used only on the current branch to avoid introducing extra commits as shown in the diagram above.


  1. Stop using GUI for git, seriously, it’s not that many commands
  2. Be safe, branch out, commit often, merge often
  3. Git rebase to be used on the current branch
  4. Replace git pull with git pull --rebase