Git Workflow

Personal Git workflow and practices that I follow when using Git

If you are in the software industry you most likely have already experienced some kind of interaction with Git.

There are a lot of sites that describe how to use Git and I will not try to cover that, but I will focus on the how to use Git in your day to day work and show you my personal workflow with Git. What are some of my git commands and some of the git aliases that I use, who knows maybe they will help you some day.

Getting started

One of the first steps that you need to do when you start working on something is branch out of your main branch, if you do not know which one it is, most likely is called master.

To name the branch is the tricky part because what should it that be?

Personally, I like to categorize my PR’s in

  • features: for when I adding new functionality to the project.

  • bugs: for when I am fixing something

  • docs: for when I am adding some wiki or updating some documentation, the only reason why I choose to have them separate is to allow easier context when searching for them.

Give your branch a meaningful name that describes the intention of the branch. That was when you list your branches it is easier to understand what that branch was about.

Some aliases / references

Some git aliases that would make git commands a bit smaller.

Keep in mind that if for example, you have a ZSH shell you might already have more than enough.

$ cat ~/.gitconfig
[core]
  ....
[alias]
  lllog = log --decorate --color --pretty=format:'%Cred%H%Creset %Cgreen(%aN)%Creset %C(bold blue)%s%Creset'
  lg = log --all --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'\n--abbrev-commit --date=relative
  lo=log --oneline --decorate
  me = log --oneline --decorate --author="alexandros@xxxxx"
  st = status
  g = grep --break --heading --line-number
  br = branch -vv
.... 

Creating the branch

To start off is as simple as choosing the name and in which of the above categories your branch fit it.

for example:

$ git checkout -b bug/fix-it-now

Hint: Create a branch even if you are the only maintainer of what project you are doing. One reason for that could be that you have already started working on X and not there is a bug on master and needs to be addressed quickly. You just checkout master branch Y fix it and then continue using branch X

Committing

This can easily be a single post about how to properly commit.

If you want to learn more about how to do it, I would recommend this post from back 2014 awesome!

I would recommend setting up VIM as your editor and automatically making it split the lines and highlight when the commit subject is large.

Commiting rules:

  • Commit often
  • Commit small, do not commit many lines together, try to keep them contained and small as very small units of work.
  • Group commits a single file together, this will help to review.
  • If porting stuff from another place, then migrate first the base file, commit, then add another commit to the changes

The above rules DO NOT apply to every scenario, they just cover most of the cases

Use the commands git add -p to stage selectivly part of a file and git commit -v to see what changes you are commiting.

Reviewing your work

When you have a fair number of commits it’s about time to start self-reviewing.

Why should you do a self-review, well first it’s faster and it would help not to waste your co-workers time.

Start by listing all the changes you have made so far.

$ git log --oneline master...HEAD

Will give you all the commits which are reachable from the current commit (HEAD) but not found in master.

What you should expect to see?

It should be able to understand the list of changes your intention. If for example, you add a new feature what steps did you take in order to add this? For example

05b7bde1 Add documentation changes for field zzz 
4d363381 Add usage of the new field
8685f775 Add testing coverage around field zzz
093d27af Add processing of field zzz to model config
5261e59a Add reading of field zzz
f07c1301 Add new field zzz in configuration

If that is not what you see, its ok we can fix that, just re-order and rename your branches.

The order in which we read the git logs is from bottom to top, bottom is the first commit and then we move upwards to the last commit

If you are not sure about a particular commit just see that commits the only diff. Here comes in handy the advice for small commits, so if you see the diff it will be contextual easy for you to remember and re-iterate on that

Viewing a particular SHA-1 diff

$ git show 4tre3dff

Preparing your code for reviews

Now that you have your commits in place we should start thinking about the reviewer, this is the person that will spend a Z amount of time trying to understand what you have done, so let’s spend some time helping him out on that.

Rebase

This is the tool that we are going to use most of the time in order to make our work of preparation easier. If you want to learn more please read this

We start by initiating the rebase process

$ git rebase --interactive origin/master

Assuming you have the EDITOR set to vim then the vim editor will open showing somethign like

pick 52d39fg Edit old feature
pick 5sfg223 Edit old feature
pick 77hyaae Adds new feature
# Rebase 2cf755d..77hyaae onto 2cf755d (9 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit

Now using your VimFu you can move commits up and down, Important to note here is that if you have followed the suggestion from above, the ordering of commits would work regardless of it.

Meaning the order in which you apply the commits is irrelevant.

This is important because it makes the rebase easier.

Ordering commits

Now that you can move commits up and down, its time to order them in a way that it would make sense for the reviewer to understand what you are doing.

For example, this is apparently wrong

093d27af Add processing of field zzz to model config
05b7bde1 Add documentation changes for field zzz 
f07c1301 Add new field zzz in configuration
5261e59a Add reading of field zzz
8685f775 Add testing coverage around field zzz
4d363381 Add usage of the new field

Why? because when I read the log entries it does not correspond to what it should be and the implementation order does not correlate with that, you cannot start but adding the usage of the new field and then add tests and set up the code to read for that field.

Creating a Pull Request (PR)

Now it time to file a change request for your work in the upstream project (in Github terms a pull request)

PR Template

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->

## How Has This Been Tested?
<!--- Please describe in detail how you tested your changes. -->

## Screenshots (if appropriate):

(Fixes: | Relates: | PartOf:) #xxxx 

What to include

When creating a PR, you should not make any assumptions about the reviewer knowing deeply the area you are covering.

If you touch more than 1 part of the code then you should include reviewing instructions, say Alex please view these changes.

The description for a fix should not be too long, just describing the problem and what they did to fix it, but for a new feature it should describe the problem, how we addressed it, what changes we added and why.

This might seem extream but in big distributed teams it would help others understand what you have done, why you did it, and leave a trail of information for the new people that join the team to understand.

Alexandros Sapranidis

Software engineer, keen on wearing many hat, current Senior Software Engineer @Elastic cloud

Athens, Greece http://sapranidis.gr