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.
Starting work with git
One of the first steps that you need to do when starting working on something is branch out of your main branch, if you do not know which one it is, most likely is called
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.
$ 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
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.
- 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
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.
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.
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)
<!--- 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.