5. Git basics

Cloning a repo

The following assumes you have Git and VS Code installed.

From your terminal, CD in to your repos directory and run git clone <<repo url>>
For example: git clone https://github.com/nocticdr/github-basics

Note 1: If you are given an https DevOps link, you might be required to authenticate. If you are given an SSH DevOps link, make sure you have the key pairs and have uploaded your public key to your DevOps account as explained here

Note 2: When you do git clone, the directory is automatically initialised as a git directory. You don't need to run git init.

Working with branches

When you go in a Git directory, by default you are in the master branch., where direct commits are not allowed. Hence, if you want to make any change, you should create a branch from the master branch. Run git checkout -b branch-name to create a new branch and checkout from the existing branch to the new branch. After your changes are committed to your branch, you can then create a pull request. A pull request is just a way to notify the admin of a project (and request for approval) that a feature has been completed and is ready to be merged with the master code.

Let's assuming you have made some changes to a markdown file called readme.

TIP: Use git status to track the state of the working directory

1. Run git add readme.MD to tell Git to add the specific file to a staging area. (Use git add . if you want to add all files in the directory).

1. Run `git commit -m "your comment" to commit your changes with a comment. It's recommended to commit changes regularly to ensure you do not lose your changes - commit early and commit often!

1. Tell git which remote location to export your commits to, by using the git push command.

When you create a branch, you have to tell git where to save any future changes made to this branch. The first time you run git push, git will ask you to confirm the remote branch you want to associate with your local branch called branch-name. For this, run git push --set-upstream origin branch-name. For subsequent changes to this branch, git push will be enough.

Assuming there are no conflicts and you can authenticate to the remote directory, you should have successfully completed your first push.

Creating a pull request

Before raising any PR please make sure to run tests.sh while on qnet-core directory. For example:

~/repos/qnet-core: ./tests.sh

If there are any errors found, it's highly likely these will fail your PR, so you should fix them before raising the PR. Once you have successfully ran git push, head to the DevOps project portal and click on the "Create a pull request" button.

A new page will appear where you will get to view the details of your PR. Click on the files tab to ensure that you are comfortable with the changes being pushed to master and that there are no unrecognised changes also being pushed.

If you are satisfied, go back to the overview tab and complete the fields as required. Ensure you write clear notes of your changes so that the approver can understand what you are trying to do. Click Create to create the PR. If you see any merge conflicts, review them and fix before creating the PR again.

If there are no errors when creating the PR, it will be sent for approval and the approver will receive an email notification. You can also copy the PR URL from the address bar and send it to the approver if you want to follow up separately. After the PR has been approved, you will need to click Complete to execute the merge to master and you will see "Merging pull request".

After the merge is completed, you can head back to your terminal, do a git checkout master or gcm and then do a git pull to get your changes imported to your local master branch.