Git general workflow Jul 23 2018

The following is a basic git workflow that handles most users needs:

The big picture:

We will have the following branches on our repository:

Workflow:

Sprout a branch from master to work on your feature.

Make sure you are in master:

1
2
git checkout master
git pull origin master

Create your feature branch, with a very descriptive name. Let’s say we use a tracking system for our new features and we have the ID trello-007 and the feature is assigned to user rderik , a descriptive name could look like:

1
                new-dashboard-display/trello-007/rderik

That will give us at a glance a way to identify what code should be inside this branch, without having to check the code.

Build the branch:

1
git checkout -b new-dashboard-display/trello-007/rderik

We work on our features run our tests and see that everything is ready for testing on dev server.

How are we going to use our environments?

We need to decide how we are going to use our development, staging and production environments. This is specific to every case and everyone seems to have an opinion on what is the best way to do it, two common approaches I’ve seen are:

1. Every environment (server) runs only a specific branch

The development server is always tied up to the development branch, so if we need to push something to this server we need to merge our branch to the development branch. And the same with Staging and Production servers, they’ll be tied up to staging and production branches respectively.

2. Development and staging servers can be pointed to a different branch, but Production will only be pointed to the production branch.

I like this approach, this way we can easily test our feature branches on the different environments before merging them into master, and before merging into master we can clean up the commits and have a cleaner git log. So that is what we are going to go with.

We will go into our development server checkout our branch, run our tests and if everything works as we expect, do the same on Staging. After all the testing and quality assurances are meet we are ready to merge our changes into master.

Pull requests?

We will generate a pull request, this might feel like too much if you work on a small group or if you are the only developer but I think it is a good habit to get into and it gives us a history of the merges and it might come handy in the future if we are looking into when a bug was introduced, etc.

To generate a pull request, you should have pushed your branch to the upstream server (this means we need to push our code to GitHub, Gitlab, bitbucket repository not just have it on local). When we already have our branch upstream we can create the pull request via command line or using the web interface of our remote git server. The general workflow would look like this:

Push our code to the remote server:

1
git push https://git-provider.com/project master:new-dashboard-display/trello-007/rderik

Generate the pull request:

1
git request-pull master https://git-provider.com/project master:new-dashboard-display/trello-007/rderik

Doing it via the web interface is easier, just click “new pull request”, or something similar, and the pull request will be created. Now your teammates will be notified that there is a new pull request and it’ll be ready for review and discussion.

Squash our commits?

Once everything is ready to merge I would suggest squashing all the branch commits to only one commit so the merge into master looks as if the feature was introduced in one commit. When we are developing is a good practice to commit often and iterate over the commits, let’s say we committed our progress every day and it took us two weeks to develop the new feature, the branch we are working on will be constructed of some 10 commits (working only 5 days a week committing only once a day) and if we merge our branch as it is into master it will pollute our git log. That is the main reason we should squash our commits, some people dislike this approach because we are changing history but having a clean history will make tracking bugs and making sense of who worked on what and when new features were introduced to our codebase.

rebase

So let's rebase, on our branch (make sure we are on our branch git checkout new-dashboard-display/trello-007/rderik) we are going to tell git to rebase using master as our “base”

1
git rebase -i master

This will open our editor with a list of commits, we can change the action to take for each commit, we are going to use squash, save and we will be prompted to write the new commit message (Git, very intelligently, will include all the comments for each of the previous commits), write a descriptive commit message including what was modified and more importantly why. Git will show what was added, deleted and modified but it can’t show why is up to us to do that, so write a good commit message that six months down the road you, or someone else, will be able to understand.

Finally, the pull request

We now push the branch back to the server:

1
git push https://git-provider.com/project master:new-dashboard-display/trello-007/rderik

And now we can merge it via the web interface. Or do it via the command line, this is how we could go about it on the command line:

1
2
3
git checkout master
git merge new-dashboard-display/trello-007/rderik
git push https://git-provider.com/project master

Cleanup

Now you can delete the branch to have a clean local repository and not drown on stale branches.

1
git branch -d new-dashboard-display/trello-007/rderik

If you do it via the web interface, you’ll have to follow some other steps to sync your branches to the remote repositories branches. You can see my post on Cleanup after pull request


We’ll hope that is helpful and let me know if you have any questions.



<!-- vim-markdown-toc Redcarpet -->

Ps.

You might be wondering:

What about the staging branch and the development branch? What are they used for?

Well, they are only used to keep a pointer to a commit that we want to mark as development or as staging, but they are in no other way different than a feature branch, we are just using them to keep track of what we think a development version of our application looks like, and the same with staging. We could, for example, use those branches to keep a specific state of our application that can be tested by the QA team or to show to our beta user, etc.


** If you want to check what else I'm currently doing be sure to follow me on twitter @rderik or subscribe to the newsletter. If you want to send me a direct message you can send it to derik@rderik.com.