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.
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
Tutorial #7: GitHub Advanced Security – A Complete Guide With Examples
Tutorial #8: What are GitHub Packages: Code and Packages in One Place
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.
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.
Note: The user who creates the repository is the owner of the GitHub Repository.
The Repository is created with a 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.
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.
Recommended Reading => Explore All About Project Planning with GitHub Projects
Performing a Basic Commit
Open the README file and perform a basic commit. Click on the Edit icon to start modifying the file.
Modify the file, add a comment and click on Commit.
The file is committed (changes saved) to the Github Repository.
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.
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.
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.
Click on the icon to edit the file.
Add the path doc/ before the file rules.txt. Click on Commit Changes.
The path is now 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.
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.
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.
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.
You can see that the changes across both branches can be merged. Click on Create Pull Request.
Click on Merge Pull Request and Confirm to complete the merge.
Changes are successfully merged into the master branch. Our first Pull request is successfully completed.
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.
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.
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.
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.
Click on the Pull Request and 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 Start a Review.
Click on Finish your Review. Approve as shown and Submit Review.
Back as the original user who raised a pull request, you can add a comment and resolve or close the conversation.
The Merge pull request can now be completed.
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.
Further Reading => GitHub Advanced Security
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.
Once the Pull Request is raised, the conflicts will need to be resolved by clicking on the Resolve conflicts button.
Remove the markings that are essentially resolving conflicts manually and click on Mark as resolved and Commit merge.
The final view of the file after markings are removed.
Merge pull request can be completed. The master and feature branches will now be 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.
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 !!!
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.
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.
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
Enter the repository name and the new user account to whom the ownership must be transferred.
Click on I understand, transfer this repository
You should see a message that the 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.
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.
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.
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.