Introduction

I recently published an article How to import your company's private repository from Bitbucket into GitHub, and it was occasioned by the fact that GitHub's free plan is attractive than that of Bitbucket's. GitHub provides a free plan for unlimited private repositories and unlimited collaborators wheres Bitbucket's free plan is limited to 5 collaborators. In fact, Bitbucket's collaborator limit is not per repository but per account (See Atlassian discussion).

In this article, we provide an easy walkthrough, for beginners, on how to start using Git and GitHub for code collaboration, together with GitHub's Gist. (Gist allows you to to share code snippets easily). For demonstration, we will use simple HTML files.

Understanding Git is critical because it is a core component of DevOps.

What you will learn

  • Creating GitHub account, GitHub organization and GitHub repository
  • Cloning a repository
  • Git basic commands
  • Ignoring files in Git
  • Git branching concepts
  • What is Git Bash and why you will need it in Windows OS
  • Conflict resolution in files
  • Running Git commands from within Visual Studio Code (VS Code)
  • Git branching workflow for big projects
  • Tracking issues in GitHub
  • Sharing code snippets using GitHub's

Prerequisites

This tutorial does not need a lot of knowledge in computing. It is easy and can be understood by beginners. However, it can also be used by software engineers and computer science teachers.

All you need is a computer with Windows OS, Visual Studio Code editor and some knowledge of basic HTML.

Let's do it!

Creating a GitHub account

For you to use GitHub, you need to create an account. You can create an account to hold your repositories, or if you are creating a repository for an organization (such as a startup), GitHub allows one to create an organization, which will hold repositories. I will show you the latter.

So let us create an account for some fictitious company.

Use the following steps:

Step 1: Visit Github.com and create an account. You need a username, an email and a password.

Step 2: Create an organization and an empty repository. Refer to step 1 and step 2 in, the article How to import your company's private repository from Bitbucket into GitHub, on how to create an organization and an empty repository.

When you are creating a repository do remember to:

  • Add a README file - This file contains information about other files in the repository. More often, you will put instructions on how to use the repository.
  • Add .gitignore - This is a plain text file where each line contains files and directories, which will not be tracked by Git system, i.e. to be ignored.
When creating an empty repository, you need to add .gitignore and README files.

At this point, you have a GitHub account, a GitHub organization and an empty repository. The screen recording below shows you how to reach your repository once you login to your account.

Installing Git and Git Bash

You should already know that GitHub is just a code repository. Git is the system, which does code version control. On the other hand, Git Bash is a feature in Git for Windows, which provides BASH emulation for running Git commands from the command line.

Actually, Git Bash makes Linux users 'feel at home' when using Windows. For windows users, who expect a Graphical User Interface (GUI), you will have access to Git GUI, though we will not be using it in this walk-through.  

Use the following steps:

Step 1: Download Git for Windows from here.

Step 2: Install the downloaded Git in your windows machine. It should be easy - just run the executable file and follow the instructions.  

Once you install Git, you have also installed Git Bash as well as shell integration. Shell integration ensures that when you right-click in any folder, you will be able to open Git command line. See below.

Cloning an empty Git repository

git clone command is primarily used to point to an existing repo and make a clone or copy of that repository in a new directory, at another location.

Use the YouTube video below to guide you on how to clone the repository we just created.

Cloning a git repository

You noticed that when you clone the repository, a folder with the name of the repository is created.

If you wanted to clone the repository into a new folder, say newproject, then it could be done as shown below.

git clone <repo here> newproject

When you clone a remote repository using git clone, a remote connection called origin is automatically created, which connects back to the cloned repository.

If you try to run git remote, it will show you origin.

Also notice (master), which is the default repo branch. We will discuss the concept of branching shortly.

Note that GitHub will replace 'master' with 'main' as the default branch name starting the month of October 2020. You can check out the news HERE.

Tracking more project files, learn more commands - git add, git commit, git push and git pull

Your project is growing, and you are doing the following;

  • You have started using a code editor such as VS Code
  • You need to track more files, which you have added to your project
  • You need to commit changes, which you have made in your project and then push them to the online repository (your other team members need them).).
  • You also need to update your local copy by pulling changes, which have been pushed by your other team members.

Proceed as follows:

Step 1 - Download and install VS Code editor in you machine. Installing VS Code is straight forward in Windows OS.  

Step 2 - Add some HTML files in your project repository. You can copy and paste some HTML code into your files. You can name the files the way you want.

Step 3 - Add a folder/directory and a file in your project, tobeignore. We will use this to demonstrate how to specify files to be ignored (not tracked by git) in the .gitignore file.

Step 4 - Launch VS code and open your project folder in VS code. VS code should already show you the files, which are not being tracked.

The YouTube video below will show you step by step on how to use git add (stage changes in readiness for commit), git status, git commit, git push and git pull.

Note that the first time you run the git commit command, you will be asked to identify yourself (git will give you a clue). So you will run the following then re-run git commit;-

git config user.email <your email here>
#Then
git config user.name <your name here>

How do you create a branch in git and checkout?

You remember, we mentioned about master branch when a repository is created, which represents the official project history.

What is a git branch?

A branch is an independent development route, which can later be connected back to the main branch.  

We use git branch command to create, list, rename and delete branches.

When do we use branches in git?

  • When adding a small or big feature  
  • When testing some logic and do not want bad code to appear in the master branch.
  • To separate releases
  • When fixing bugs or assigned issues etc.

How do I check branches available in my git repository?  

git branch

There are 2 branches, heading3 and master. Master branch is the working branch, see the asterisk, *

How do I create a branch in git?

git branch heading3

We have created a branch called heading3.

How do I switch from one git branch to another?

git checkout heading3

We switched to heading3 branch. So if we run git branch, you will see an asterisk on heading3.

How do we merge changes of a git branch in/to another?

Once you make changes in a branch, say heading3, stage and commit them, you may want to merge these changes so that another branch, say master, can contain changes made in heading3.

Checkout to master as shown

git checkout master

Then merge heading3 changes to the master branch as shown

git merge heading3

At this point, you can push the new changes to your remote repository.

git push origin master

How do I delete a git branch?

git branch -d heading3

Git branching use case 1

Now that we have learnt some commands, we can handle a use case.

Suppose in our test4ppp app; we need to add a small feature. So you decide to create a branch, develop the feature on the branch, then merge the feature to the master branch. You do not need other developers to access the branch, so you delete it!

This YouTube video will guide you through.

Git branching use case 2

Suppose that from our Use case 1, the branch we created needs to be accessed by other developers in your team and has to be pushed to the remote repository for review.

This YouTube video will guide you through.

Git workflows and git branching practices

I am sure you have heard about terms such as master and develop branches, hot fixes, issue/bug fixes, release or feature branches and git tagging.

When working on big projects, which takes a long time and involve many developers, it is advisable to define a strict branching model or design centered around project release.

Most developers do not like regulations, but one thing we are sure of is that no team will be successful in producing quality software if it does not follow a solid git workflow.

Vincent Driessen extensively discusses git workflow concept in his post A successful Git branching model, where he elaborates on a git-flow he has used in his projects and was very successful. This flow is basically a good use of the git branching or branch types.

You could also checkout this on Gitflow — Branch Guide to understand more on the benefits of Git workflow and the use of git-flow extension. You could further cement your understanding of Git workflows by looking at an article, A Step-by-Step Guide to the RubyGarage Git and Release Management Workflow, which elaborates on the relationship between the above terms and Production server, Staging Server and Development server.

Now that you have used git branches, we can try to understand what the above terms mean as used in git workflows.  

The branch types we will cover are

  • Master
  • Release
  • Hot fix
  • Develop
  • Feature
  • Issue/bug fix

Also, see how the branch types are related in the diagram below

A successful Git branching model (Source: Driessen, 2010)
  1. Master branch

This branch holds the latest version of fully working code, which is the current code in production - simply, it only tracks released code only. You can see that the only merges to master come from release and hotfixes branches.

Note that GitHub will replace 'master' with 'main' as the default branch name starting the month of October 2020. You can check out the news HERE.

2. Develop branch

This branch is created from the master branch - it complements the default master branch. It is the integration branch for features.  

3. Feature branch

When you begin a feature, you create a branch off the develop branch, and once the feature is done, you merge back to develop.

4. Release branch

Now that you have completed a number of features and are ready for a release, create a release branch off the develop branch. Because this is a release, create a suitable environment for testing purposes (it could be a testing server). If you discover bugs/issues while testing your release code, address it out immediately and merge any changes (bug fixes) back to develop branch (see greyed lines). When the code has been tested and is working okay, two things happen

  • Merge back to develop
  • Merge to master with a release tag

5. Hotfixes branch

If an issue is detected on master (e.g. a severe bug), a hotfix branch is created off the master branch. Once the hotfix is complete, it is merged to both develop and master branches.

6. Bugfix/issue

As mentioned earlier, if some issues were detected in a release branch while testing, you may want to use small branches to fix the issues. Such branches are merged back the release branch. More often, issues are assigned to developers, who may want to use bug fix branches.

Branch Naming conventions

As a team, once you agree on your workflow, you may need to agree on how to name your branches.

The table below shows a way you may do this. Note that this is not a standard!

Branch type Naming convention Example
Master master master
Develop develop develop
feature feature/feature-name feature/forget-password
release release/release number release/1.0
Hotfixes hotfix/issue name hotfix/connect-to-mongo-db

git Tagging

The purpose of tagging is usually to take note of specific points in the repository history as being important. It is mostly used to mark release points

As discussed above, let's say a release has been tested and has been merged to develop and you want to merge to master, you would normally proceed as follows;-

Checkout to master

git checkout master

Merge release to master

git merge release/1.0

//release/1.0 is name of release branch

Tag the release for future reference

$ git tag -a 1.0

//OR you could do it it with a message

git tag -a 1.0 -m “version 1.0 rolled out!”

You can list all tags by running;-

git tag

You can checkout to a tag just the way you do to a branch. This will allow you to see the status of your source code at a point when that tag was created.

This also puts your repository in a detached HEAD state, which means you can play around with the code in a tag branch without affecting your real code.

#Checkout to a particular tag
git checkout 1.0

#The first time you checkout to a tag, you may this message ...............................
...............................

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
................................
................................

Here comes an interesting point

How do you push git tags to the remote repository in GitHub?

Well, tags do not get pushed automatically when you push your main branch. You have to do it explicitly.

To push all tags, run the following command;-

git push origin --tags

Now when you check your GitHub repository, you will see all the tags with .zip and .tar.gz files holding your source code.

Viewing your tags in your GitHub account

git feature and release Branches Workflow and cheat sheet

We assume that you have a repository in place with master branch in place

One developer to create an empty develop branch locally and push it to the server

git branch develop
git push -u origin develop
git checkout develop

Create a new feature branch called long-paragraph.

git checkout -b feature/long-paragraph 

#Could be done a: create a branch and then checkout to the branch i.e 
git branch feature/long-paragraph
git checkout feature/long-paragraph

Do work on the feature normally

#back to develop branch
git checkout develop
#merge feature to develop
git merge feature/long-paragraph

Do more features and merge them to develop branch

#All features are merged to develop, next push changes to develop branch in server
git push origin develop

With enough features, it is time for a release.

#create a release off the develop branch
git checkout -b release/1.0

Do your testing and you may find issues/bugs, fix them (directly or by creating issues branches).

#Merge release to master and tag
git checkout master
git merge release/1.0
git tag -a 1.0 #You can add some messages by using -m option. 
git push origin master
#You can push tags as well
git push origin --tags
#Merge release to develop
git checkout develop
git merge release/1.0
git push origin develop

The following YouTube video will walk you through Git workflows using a real example.

A simple git and GitHub workflow

git hot fix branch workflow and cheat sheet

So you discover a bug in the production code (master branch). Lets say, the long-paragraph needed to have less text.

We will create a hotfix/1.0.1 for it.

git checkout master
git checkout -b hotfix/1.0.1

Fix the bug and commit changes.

git add *
git commit -m 'long paragragh severe bug fixed'

Merge to master and develop branches. Remember to tag when you merge to master.

git checkout master
git merge hotfix/1.0.1
git tag -a v1.0.1
git push origin master
git push origin v1.0.1
git checkout develop
git merge hotfix/1.0.1
git push origin develop

Checkout this YouTube video for a real example.

A simple git hot fix workflow

How to handle git merge conflict

What are git conflicts and when do they happen.

Let's say in our home.html file, one developer modifies lines 4 and 5 and another developer modifies lines 10 and 11. Well, everything is okay because there is no common line in the modifications.

However, if both developers modified code in home.html and somehow they happen to modify the same line, say they both change line 7, then a conflict is said to have happened.

This YouTube video will make you understand more:

git conflicts can occur when you;

  • Pull from a remote repository
  • Merge a branch

When a git conflict happens, git will show you the 2 sections, from which you need to choose the correct one.  It is up to you to decide what to keep and what to discard.

For instance, if you encounter a merge from a branch, you will see something like this:-

How git shows you a conflict

What you see is 7 less than signs with HEAD, 7 equal signs and 7 greater than signs with name of branch feature_branch. There are 2 sections as follows  

  • The section between less than signs and equal signs - modification on the current branch.
  • The section between equal signs and greater than signs - modification from the incoming branch. If it was a pull, it denotes modification from the remote repository (probably made by another developer).

Resolving a conflict can take from just a minute to days. To avoid conflict resolutions taking a long time, it is advisable to commit, pull, push and merge more often.

In the following video, we demonstrate how you can handle a git branch merge conflict.

How to resolve a branch merge conflict

How to manage issues in GitHub

Most projects where there are many collaborators must have a way of tracking bugs. This is what GitHub issues do. You use issues to track anything, which is wrong with your source code or anything that can be improved in your project.

Issues and improvements can be spotted by the team, which is building the application, or the application users could discover it.

When you navigate to a repository, you can easily see the issues tab.

When you click the 'New Issue' button, you get to open an issue.

When you create a new issue, there are important pieces of information you will need to pay attention to as marked (using crosses) in the screen short below.

Notice that the assignee of an issue will use the git workflow we have already discussed above. The assignee could use Hot fix branch type if the issue is a bug discovered in code in production,  feature branch type if it is an enhancement or bug branch type if a bug was discovered while testing release branch.  

The following video explains how to use GitHub issues practically.

Understanding GitHub Issues

In addition to the video, there is GitHub Guide on Mastering Issues, which you can checkout to cement your understanding on this topic.  

How to share code snippets using GitHub's gist

So, what is GitHub Gist, and what is the difference between GitHub Gist and GitHub repositories?

Well, we can say that GitHub Gist is a service within GitHub, which allows easier sharing of code snippets and files. You will mostly use gists when sharing code techniques or functions, which are not complete applications.

If you view this article How to set up a Node/Express JS project with Sequelize-CLI, you will notice that some code files are shared from GitHub. At the bottom section, you will see a label 'hosted with ❤ by GitHub'.

GitHub gist is accessible as a subdomain on github.com (gist.github.com). Once you login to GitHub, you will have access to gist.

Once you create a gist, you will have access to a URL or a script, which you can share on web pages.

Finally, in the following video, we will demonstrate on how to create and share a gist.

Sharing code snippets using GitHub gist

Conclusion

In this post, we have provided a comprehensive walk through on how to start using git and GitHub for beginners. We also looked at a significant part, which is a git workflow software engineers can adopt in an organization to ease team collaboration.

We also looked at GitHub gist as a way of sharing code snippets instead of copying and pasting.  

Although we did not touch on the primary concepts of DevOps, understanding git is the starting point.  

There are 3 important parts, which we did not cover, but are very important - we plan to cover them in future posts.

  • How to use pull requests (PRs) and when to use them.
  • How to contribute to other people's projects in GitHub or open-source projects.
  • How to safely rename master Branch on GitHub to main - You may have heard that GitHub will be renaming the default master branch to main branch as part of their initiative to remove references to slavery by using more inclusive terms. See the news HERE.

I hope you enjoyed this article. Please leave your questions in the comments section below.

You've successfully subscribed to Decoded For Devs
Welcome back! You've successfully signed in.
Great! You've successfully signed up.
Your link has expired
Success! Your account is fully activated, you now have access to all content.