lundi 8 août 2016

Git : Don't underuse the tool

Most of the time, there's a tendency to use Git like the good old SVN, without spending enough time to read the documentation (and yet very well-resourced). This is why we miss some valuable features that make git so magical. In this article I will discuss two important features. The first, Git commit messages, that gives your history the value of a good documentation, and the second, Git alias, that makes the usage of the tool simpler by saving you from typing long and complex commands.



Well comment your commits

It's almost recognised that comments in source code are useless. The code is enough to express the intention of the developer. We can find lot of legitimate points against code comments :

  • The code is designed to be changed, and the comment may not follow theses changes. (A comment that doesn't reflect the current state of the code, by not telling what the code is doing, can become unproductive.) 
  • The need of commenting reflects the lack of expressiveness of the code. 
  • A code should be like a joke, it doesn't need to be explained. 

But in practice, we may need to share information, as close as possible to the source code, without being able to express the idea through the code. Peter Hilton explained very well in his blog kind of questions code can't give any answer :
  • Why is this code here?
  • What is it for?
  • Why is the functionality implemented this way?
  • Why is that the functionality?
  • When shouldn’t you use this code?
"Ancient Japanese mercenaries are known for staying on task and writing concise git commit messages."
Git commit messages, since they are linked to the evolution of the code, can be a better place to communicate this kind of information. We can go further than writing simple messages that give no specific information on the details of a commit. What we can explain for example :
  • How the code has evolved
  • What brings us in a given state
  • Why this choice instead of another choice …

In Angularjs project here's the convention they use for their commit messages :
 <type>(<scope>): <subject>
<BLANK LINE>
 <body>
<BLANK LINE>
<footer>

type : could be feature, refactoring, documentation, fix, …

scope : could be anything specifying place of the commit change. (module, layer, project, … ) 
subject : contains description of the change
body : contains the motivation for the change
footer : contains the references of the commit (Jira, User Stories, Issues, …)


The first step, if you want to write useful commit messages, would be to configure the default text editor for Git. If you are a Vim user you can follow either of the steps below :
  • Type git config --global core.editor "vim" in your terminal
  • Add in ~/.gitconfig : editor = "vim" under [core] field
  • Set the GIT_EDITOR environment variable: export GIT_EDITOR=vim

Once we type the command git commit (without “-m”), the terminal opens the default editor we have already configured (Vim, pico) to write a comment.Here's an example of comment I wrote months ago. It doesn't follow the Angular's project convention, but it gives me enough details so I can find out easily what I was doing at this time.

Refactoring: Create service folder for project's services (service1, service2, …)
  • Move acceptance-volume, Cassandra, ... in the root folder
  • Move service1 and service2 under service folder
  • Update files path in Makefile and compose files
There is a nice article here if you want to have further reading on commit messages.

Type less with alias

It's part of a developer's normal reflexes to find shortcuts or to write shell script when it comes to use complex and repetitive tasks. With git the solution lies in the use of alias. The configuration is done in the ~/.gitconfig file, below the [alias] section. After several years of use of git, some of these alias become part of everyday practices.

git st for git status
git ci for git commit
git br for git branch
git co for git checkout

Other alias can be used, for less obvious use cases, to have nice outputs :
>> git ls
7c86c6f Create includes files [Yakhya Dabo]
9d80d4d Remove docker-compose rm command [Yakhya Dabo]
cd13a3c Display the versions of services [Yakhya Dabo]
e3981b7 Remove *RELEASE_VERSION [Yakhya Dabo]

>> git ll
7c86c6f Create includes files [Yakhya Dabo]
2 16 Makefile
10 0 dockerfiles/service1/makefile-include.mk
10 0 dockerfiles/service2/makefile-include.mk
0 9 properties.mk

9d80d4d Remove docker-compose rm command [Yakhya Dabo]
0 3 Makefile

cd13a3c Display the versions of services [Yakhya Dabo]
40 39 Makefile

e3981b7 Remove *RELEASE_VERSION [Yakhya Dabo]
14 17 Makefile 2 2 properties.mk …

>> git lds
7c86c6f 2016-02-10 Create includes files [Yakhya Dabo]
9d80d4d 2016-02-10 Remove docker-compose rm command [Yakhya Dabo]
cd13a3c 2016-02-10 Display the versions of services [Yakhya Dabo]
e3981b7 2016-02-10 Remove *RELEASE_VERSION [Yakhya Dabo]

>> git ld
7c86c6f 23 hours ago Create includes files [Yakhya Dabo]
9d80d4d 24 hours ago Remove docker-compose rm command [Yakhya Dabo]
cd13a3c 25 hours ago Display the versions of services [Yakhya Dabo]
e3981b7 26 hours ago Remove *RELEASE_VERSION [Yakhya Dabo]

Here are few alias I have in my .configfile
For further reading go here.