Quite often when using version control (Git, GitLab) you will need to create a new branch where you can develop in isolation from other developers / the master branch. Below are the basic branch-related commands to help you get started.

When to Create a Branch

You should create a branch that encapsulates a single train of thought that depends on your workflow. If, for example, you are creating a product which has a list of features you can create a new branch per feature. This would allow your various team members to work on the same project on different features without overwriting each others work should the various features happen to utilize some common files.

Given the above, you may still have some code collisions when you merge in which case GIT will alert you to that fact so that you can manage resolve the conflicts as needed.

Another scenario would be if you want to experiment with something without directly impacting the master branch. You could then create a new local branch and feel safe knowing that if what you’re doing doesn’t work you can easily return to the master branch to create yet another branch based on the master sot that you can pursue the issue in a different way.

For information on a workflow that utilizes branching view this article: A successful Git Branching Model.

Create and Checkout a New Branch

You can create and checkout a branch using a one-liner:

$ git checkout -b new-branch-name

Or use two separate commands:

$ git branch new-branch-name
$ git checkout new-branch-name

Branch names should follow a naming convention, such as:

  • Adding new features:
    • feature/user-login
    • feature/display-user-profile
  • Resolving bugs:
    • bugfix/resolve-form validation-issues
    • bugfix/fix-layout-issue-on-ios
  • Or better yet, if you are Scrumming then you should follow your stories and tasks:
    • story/login/create-login-service
    • story/login/integrate-login-service-w-frontend
    • story/login/layout-login-page
    • story/list-products/create-product-service
    • story/list-products/import-database
    • story/list-products/integrate-product-service-w-frontend
    • story/list-products/layout
    • etc…

The naming conventions allow us to more easily manage our branches.

View All Branches

To view all the branches in the repo that you have worked on issue the following command. The resulting list will place an asterisk in front of the currently checked out branch.

$ git branch

To View All Branches in the Repository

By default you will only see those branches that you have created. Other members of the team may have pushed branches that you don’t yet see in your copy of the repo.

Viewing Remote Branches

To view remote branches issue the following command:

$ git branch -a

The result of the above might look like:

$ git branch -a
* master
remotes/origin/HEAD
remotes/origin/master
remotes/origin/kangaroo
$

The "remotes" are the branches that are part of the remote repo that you do not yet have a local tracking branch for.

To Create a Local Tracking Branch from a Remote Branch

Using the above example, if you want to work on the “kangaroo” branch you need to create a local tracking branch:

$ git checkout -b kangaroo origin/kangaroo

A message will appear letting you know that you were successful.

You are now in your local “kangaroo” branch. Issue $git branch to see that you are indeed in the “kangaroo” branch:

$ git branch
* kangaroo
master
$

Checkout a Branch

$ git checkout name-of-branch

After checking out a branch it is a good practice to do…

$ git pull

…to ensure that you have the latest version of the files especially if other members of your team are committing to the same branch.

When to Merge Your Branch Back Into the Master Branch

While working in your new branch you can commit as often as you like. You may even push your branch back up to Git should you need a copy there as well – which would allow other team members to download your latest committed/pushed work so that they can contribute.

Its ok though to work locally without pushing your branch to the repository. When you are done with your edits, have tested everything and feel that the changes are ready to be merged back into the master branch you can do the merge yourself or you will have to create a merge request. For the latter you will definitely need to push your branch to the repo.

To merge a branch into master assuming your working branch is called “my-working-branch”:

$ git checkout master
$ git pull
$ git merge my-working-branch
$ git push

As you can see above the first thing to do before merging your branch is to “pull” the latest copy of the master branch.

What if the Master Branch is Updated and I Need Those Updates in My Working Branch?

If you find that while you work other team members have updated the master branch and that the those changes would be beneficial to have within your own branch you can do the following from within your branch:

$ git rebase master

This will “rewind” the edits you made to your branch back to the point where the branch is at parity with master, then the master updates are applied and then Git “plays” your changes back on top of the updated master.