Skip to content

Introduction to GitHub - Part 2

Branches and Merging

In GitHub you are able to create a parallel version of the project, this is called a branch. In this branch, you can implement changes to the files in the repository without affecting the original files. This concept is visualised below, each letter represents a commit. The commits A and B belong to the master branch (sometimes also called main), and C → E belong to the branch "branch".

       C---D---E branch
      /
 A---B master

To create a new branch, within your repository run the command:

Format

git branch {name_of_branch}
git checkout {name_of_branch}
The first command creates the branch, and the second switches from your current branch to the new branch. Alternatively, both can be achieved using: 
git checkout -b {name_of_branch}

Let's make some changes in our new branch, make a new file called hello.py with the following code:

hello.py

print("Hello World!")
print("I made a branch")

Stage the change and commit it using Commitizen. When you are happy with your newly developed code, you will want to return to your master branch. But if you do so, you will see that hello.py is not there. Change branch using git checkout main and verify this yourself.

Merging

As you have seen changes that you make on a branch stay in that branch, but eventually you will want to migrate the changes to your master branch. To do this we have to merge the changes, visually, this looks like the figure below.

       A---B---C branch
      /         \
 D---E---F---G---H master

With the master branch checked out, the command to merge branches is:

Format

% git merge {name_of_branch}

So go ahead and merge "branch" into master. You should now see your hello.py file in the master branch! Now that we no longer need the branch "branch", the last thing left to do is to delete the branch. To do this, simply run:

Format

% git branch -d {name_of_branch}

Branch Etiquette

The method for creating branches that we just went through, while functional, is not the correct way to make a new branch within the CHIME collaboration as it doesn't follow our branch etiquette. All branches must be created from an issue, if there is no issue for the changes that you'd like to implement, create one.

Please follow the steps below to create a branch in your repository using the branch etiquette.

  1. Create an issue or feature request:
    Within your repository, navigate to the Issues tab. From here, start a new issue by pressing the green button in the top right. Here, describe the feature/issue that you are working on and give it a clear and concise title. On the right side, use these sections to assign the task to yourself, apply the relevant labels, and link to a project - such as the current sprint.

    If an issue already exists, then just simply assign the issue to yourself.

    branch-etiquette-1

  2. Branch the repository from the issue:
    All of the changes to the repository should be done on a branch. The branch can be created by navigating to the issue and clicking "Create a branch" located on the right under Development. Then press "Create branch" within the prompt. You can now fetch and checkout the branch from your local machine by using the displayed commands.

    branch-etiquette-2

  3. Request a merge with main via pull request:
    Once you have finished working on the issue and your work is ready to be released. You can push your local changes to the branch on GitHub, then make a pull request. To make the pull request, click on the "Pull requests" within the repository, then select "New pull request". Next select the branch you wish to merge. Once finished comparing changes, click "Create pull request" and complete the pull request form detailing the changes that you've made. If you recently pushed changes to GitHub there should be a "Compare & pull request" button above "New pull request", which you can click to go directly to the pull request form. Once the form is completed, you can assign a reviewer on the right side before creating the pull request.

    branch-etiquette-3

    Do not merge the pull request yourself!

    Allow another member of the repository to review your pull request and merge with main.

  4. Delete the branch:
    Once your changes have been merged with the main branch of the repository, please delete the branch in order to keep the repository clean. This can be done from your pull request, at the bottom of the pull request page is a "Delete branch" button.

    branch-etiquette-4

Forking a repository

Forking a repository is a similar concept to branching, except that you create a new master branch within your fork. A fork is an exact copy of a repository that you will own under your account. The repository is still linked to the original, although, the fork can't be pushed by anyone other than the owner.

How to fork a repository

  1. To fork a repository, navigate to the repository that you wish to fork on GitHub.

  2. Click 'Fork' near the top of the repository.

    github_fork1

  3. If you wish to change the name of the forked repository, you can do so here. Otherwise, the repository will inherit the name and description of the original repository. You can choose the owner of the repository, either your personal account or any organisations that you are a part of.

    github_fork2

Next step

You now know everything that you need to know to use GitHub to collaboratively write code. It is especially important to make changes to main only through branches and pull requests. The branch etiquette helps others to understand what changes they will find inside each branch and which branches are related to which issues. In the next step, you will learn about Visual Studio Code.