GitHub Tutorial For Developers | How To Use GitHub

This GitHub Tutorial Explains What is GitHub and How to Create a Repository, Branch & Pull Request. It includes Branch Protection Rules & Conflict Resolution:

What Is GitHub?

GitHub is a cloud service that helps developers store and manage their source code as well as track and control all the changes to the source code.

In simple terms, GitHub is meant for developers wherein they can manage the project, host the source code and review them too. We will explore all of these in this series.

GitHub Tutorial for Developers

List Of Tutorials In This GitHub Series:

Tutorial #1: GitHub Tutorial For Developers | How To Use GitHub [This Tutorial]
Tutorial #2: GitHub Projects, Teams, Fork & Wiki For Documenting Projects
Tutorial #3: Advanced Git Commands And GitHub Integration Tutorial
Tutorial #4: GitHub REST API Tutorial – REST API Support In GitHub
Tutorial #5: GitHub Desktop Tutorial – Collaborate With GitHub From Your Desktop
Tutorial #6: TortoiseGit Tutorial – How To Use TortoiseGit For Version Control


What Is Git?

Git is an Open Source version control system where the entire source code is available on the developer’s machine. Git is also a Client and Distributed Version Control System (DVCS) where you can do branching and merging.

Getting Started With GitHub

To get started with GitHub, we will perform the following steps.

  • Create a Repository to organize projects.
  • Create a Branch
  • Make changes to the file and commit.
  • Create a Pull Request to merge contents.
  • Protect Branch

In the second part of the series, we will also look at the other features of GitHub like Creating Organization, Teams, Issues, Milestones, Forks, Releases and Wikis.

Create A GitHub Repository

A GitHub Repository contains the project’s artifacts such as source code, documents, images, etc. We will create and use a demo repository to perform all the above steps.

Login to Github.com and Create a New Repository. Click on the New button.

GitHub Login Screen

Add the below repo details as shown and click on Create repository. Set access to either Private or Public. It’s better to set it to public as few features are dependent on this access.

Create Repository

Note: The user who creates the repository is the owner of the GitHub Repository.

The Repository is created with a README file.

GitHub Repository with README file

Adding Collaborators to the GitHub Repository

We would want the team to work on this repository. For this, we will have to invite the collaborators to work on the repository. To add collaborators, go to the main page of the Repository and click on the Settings icon.

Click on Collaborators on the left pane and add the collaborators who have Github account. An invite would be sent and the collaborators would need to accept the invitation.

Adding Collaborators

Collaborators are added as shown below. Later, in this tutorial, we will see how the Collaborators will be added as the reviewer for the pull request created to merge the code.

Collaborators are added

Performing a Basic Commit

Open the README file and perform a basic commit. Click on the Edit icon to start modifying the file.

Performing a basic Commit

Edit File

Modify the file, add a comment and click on Commit.

Commit Changes

The file is committed (changes saved) to the Github Repository.

File is committed

Few operations to create folder and files inside the Repository will be seen.

To create the folder and a file within: Click on the Create new file button at the Repository level. Type the name of the directory followed by / and the name of the file as shown below.

Create New File

Edit New File

Click on Commit at the bottom. The folder and file are created as shown. Thus, the files and folders are created on the master branch which is the main integration branch and mostly where the software releases can be built.

Click on Commit

The developers normally work on the task assigned to them on a separate branch and merge the changes to the master branch. For Example, branches can be created for feature development or resolving bugs or working on enhancements, etc. Thus, by creating a branch the work is isolated without disturbing the other branches.

In the next step, we can look at how the branches can be created and pull requests be defined to review and merge the code into the master branch.

Moving A File

To move a file to another folder do the following steps. For Example, to move the file rules.txt to a doc folder. Click on the file.

Move a file

Click on the icon to edit the file.

Edit Icon

Add the path doc/ before the file rules.txt. Click on Commit Changes.

Add the path

The path is now updated.

Path is updated

Creating A GitHub Branch

Go to the main page of the Repository and type to create a feature branch as shown. Click on Create branch.

Create branch feature

We are now in the feature branch. The files are the same. We will now make some changes to the files in the feature branch and create a pull request to review the changes and merge the code into the master branch.

feature branch

Make changes to the files in the feature branch.

Open the Java file in the Src folder and add some code and commit the change.

Make changes to files in feature branch

Create A GitHub Pull Request

In the previous section, we created a branch feature and made some changes to a file. The changes are not in the master branch. For this, we need to create a Pull Request by which the user is proposing certain changes to be reviewed and merged into the master branch.

Creating Pull Request will show the differences between the source and target branch and will be required to resolve conflicts if any.

Click on Compare & Pull Request on the main page of the repository.

Compare & pull request

You can see that the changes across both branches can be merged. Click on Create Pull Request.

Open a pull request

Click on Merge Pull Request and Confirm to complete the merge.

Merge Pull Request

Changes are successfully merged into the master branch. Our first Pull request is successfully completed.

Pull request successfully merged

Assign Reviewers With Pull Requests And Code Review

Github has a good feature of using a CODEOWNERS file wherein we can select the people responsible for the source code in the repository. Repository owners can create this file and any users defined in the file are requested by default for the review during pull request creation.

To use this feature, you must use the GitHub Pro version or make the Repository Public.

In the root of the repository, create this file in the following format and commit the file.

* @username or @orgname or @teamname

* primarily means all the files in the repo. You can also specify specific extensions like *.java or *.js etc. The users defined in the file will be sent a request for review automatically. With the CODEOWNERS file defined, there is no need to explicitly add reviewers manually and has a bit more flexibility to choose which files to be reviewed.

CODEOWNERS file

Back in the feature branch make a small change to the Java file and create a Pull Request. In the Pull Request screen assign a reviewer on the right-hand side. Click on Create Pull Request.

Pull request screen

You can see in the above screen that the reviewers can be assigned manually but the reviewers are defined in the CODEOWNERS file who will automatically get a request to review the code changes.

Review Requested

Anyway, for now, let’s login as the reviewer and approve the changes. Log in as the user vniranjan2512 to approve the changes.

There is a request to Approve/Reject the changes, under Pull Request.

Request to Approve - Reject the changes

Click on the Pull Request and Add your review.

Add your review

You can click on the + sign and add review comments for the line of code Added/Modified/Deleted, on the screen that comes up.

Click on the +sign

Click on Start a Review.

Start a Review

Click on Finish your Review. Approve as shown and Submit Review.

Finish your Review

Back as the original user who raised a pull request, you can add a comment and resolve or close the conversation.

Add a Comment and Resolve or Close

The Merge pull request can now be completed.

Changes Approved

The changes are successfully merged into the master branch post the review and merging the pull request.

So, to summarize at this stage, we have seen that developers work on the feature branch and then raise a Pull Request to merge the changes to the master branch. The above was a scenario where conflicts were not there. In the next section, we will see the ways to resolve conflicts manually if the files are changed in multiple branches.

Resolving Conflicts

It is possible that the same files in multiple branches would be changed. In this case, there would be conflicts and has to be resolved through the Pull Request raised.

For Example, make changes to the Java file in both the master and feature branches and raise a pull request.

The pull request message shown is that the changes cannot be automatically merged. Hence the conflicts have to be resolved. Proceed to create a Pull Request.

Changes cannot be automatically merged

Once the Pull Request is raised, the conflicts will need to be resolved by clicking on the Resolve conflicts button.

Resolve Conflicts

Remove the markings that are essentially resolving conflicts manually and click on Mark as resolved and Commit merge.

Mark as resolved and Commit merge.

The final view of the file after markings are removed.

File after markings are removed

Merge pull request can be completed. The master and feature branches will now be identical.

Master and Feature branch are identical

You can still see in the above screen that the Review is requested but not mandated. In the next section, we will see about the Branch protection rules wherein the owner of the repository can mandatorily request for a review and also protect the master branch from committing directly to it but only through a pull request.

Branch Protection Rules

In the previous sections, we saw about Github Pull Requests and also requesting for reviews that were not mandated or optional. In typical project scenarios code, the reviews are a must and a part of the development process.

Let’s see how to enforce this.

In github.com this feature can be set only for public repositories or using the Github pro version. On the main page of the Repository go to Settings and click on the Branches category on the left.

Branches category

Click on Add rule under the Branch protection rules. The rule added requests for mandatory pull request reviews from the code owners before merging for the master branch.

This will also ensure that the master branch is protected and no direct commits can be done on this branch and can only be committed through the Pull Requests after a thorough review. This setting is set by the repository owner.

A Great Feature indeed !!!

Branch Protection rules

Click on Create once done. To test this scenario, make a change to a file in the feature branch and create a pull request.

The following screen shows that a review is mandatorily required by the code owners.

Review is mandatorily required

Post the review from the Code Owners the pull request can be merged.

As a collaborator of the repository, if you do changes to any of the files, due to the protected branches’ rules created, you will not be able to commit directly to the master branch but only through a Pull Request after creating a branch as shown below.

Protected branches

Transferring A Repository To Another User Account

Normally, a personal user repository has a single owner and all others are collaborators. So, in a sense that you cannot have multiple owners in a user account repository. But the ownership can be transferred to another user account. When done the original repository owner automatically becomes collaborators in the new user account repository.

The new owner can then start administering the artifact’s, issues, pull requests, projects, releases, and settings.

Normally when commands like ‘git clone’ or ‘git push’ are performed in the local repository the commands will redirect to the new repository. But when you run the ‘git remote -v’ command it will still show the original repository URL. To avoid confusion to change to the new remote URL post the transfer of the repository using ‘git remote set-url’ command.

To transfer a repository, go to the Settings tab of the repository and under Options ? Danger Zone click on Transfer

Danger Zone

Enter the repository name and the new user account to whom the ownership must be transferred.

Transfer repository

Click on I understand, transfer this repository

You should see a message that the repository is transferred to the new owner.

Repository is transferred to the new owner

A mail will be sent to the original repository owner to approve the transfer. Once the transfer is approved the repository will be transferred to the new owner and the original repository owner will be added as a collaborator.

Original repository owner is added as a collaborator.

Now set the new repository URL in the machine where the old repository was cloned. The following commands have to be set in all machines where the old repository was cloned.

Command to clone old repository

All pull requests, issues, wiki will be transferred. Issue assignments will remain intact.

Some Useful Git Commands

There are some of the basic Git commands to be configured initially on your local machine once the Git client is installed on your Linux or Windows machine. Developers work locally, without connection to the repository on GitHub, on the full copy of the source code available on GitHub and synchronize with it.

Firstly, set your user name and email address to ensure that all commits you do use this information.

git config –global user.name “UserName”
git config –global user.email “myemail@myemail.com”

When you need to add a message during commits, you can also configure the editor needed for the same.

git config –global core.editor notepad

Get a list of all the configuration values set.

git config –list

Sometimes organizations have proxy servers for connecting to the internet. In that case, you will need to specify a proxy server and port number to access all the repositories on GitHub.

git config –global http.proxyhttp://Username:Password@proxyserver:port

Clone or make a local copy of the Repository. Get the clone URL of the repository in GitHub and run the git command.

Clone with Https

Git Clone

Conclusion

In this tutorial, we have seen how a developer can start working on GitHub, right from Creating a GitHub Repository, Branch, Pull Request, Protecting a branch and some basic Git commands.

In our upcoming tutorial, we will see the other features of GitHub mainly on how to create organizations, teams, fork a repository, create issues, milestones and associating with pull requests, wiki’s and their uses and few other advanced Git commands that will be useful to the developers.

NEXT Tutorial