Create your own version (branching, cloning, pulling)

Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. The main branch is the default branch. The content on this branch will be the most up to date version of the book. Therefore, new branches, which are made to add or fix some content in the book, are usually cloned from the main branch. This has many advantages compared to making the edits immediately in the main branch. Some advantages of working with branches are:

• Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are “hidden”. Your own branch helps to keep an overview of the changes made to the book.

• Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members’ changes. In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches.

This systematic workflow guarantees that editing the book goes smoothly.

The act of making a new branch from an existing one is called branching. Usually, you want to branch from the main branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the source branch.

Create your own version as …

… user type 3 …

… by directly creating your own version of the book (branching) or selecting an existing version in …

… GitLab

1. Navigate to the repository of your project. Under the project description, you should see a menu button with a “+” in it. Click this button, then click on “New branch”.

Fig. 3 Click the highlighted button to make a new branch.

2. A new page opens, on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, chapter-2 is a suitable name if we’re going to be working on Chapter 2 of our book. After you’ve made sure that the selected source branch is correct, click “Create branch”.

Fig. 4 We’re making a new branch called chapter-2 from the main branch.

3. You should be sent back to an overview page of your repository. In the branch selection menu, it should now say chapter-2 instead of main.

Fig. 5 The circled menu is the branch selection menu.

… GitHub

How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.

Fig. 6 Demonstration, video available here

1. Open the repository in which you want to work in. In the top bar you will see your current branch main and next to that there is a tab called Branches.

Fig. 7 Overview

2. Clicking on Branches will bring you to an overview of all the branches in the repository. Click on the green Create Branch button.

Fig. 8 Overview Branches

3. Finally, give your branch a name and specifiy the source branch.
   Tip: It makes sense to give the branch a name related to the content you will be creating or altering.

Fig. 9 New Branch

4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).

Fig. 10 Select New Branch

… user type 4 and 5 …

As user type 4 and 5, you make changes to the book locally on your computer rather than online on GitLab/GitHub. This allows you to create more complex and interactive sections to your book. Before you can start, there are a few preparatory steps you need to take.

In order to create your own version, you will first have to open the repository. Then, you will need to clone the repository to your computer. This procedure is called cloning.

If your repository is already cloned on your computer, you are almost ready to start editing the book. However, remember that you are most likely not the only person making changes to the book. To keep an overview of the changes made by you and your colleages, it is important that changes are first made in a ‘copy’ of the book and are then merged into the final version. This is done through branching! You can create your version of the book by creating a new version (branch) or you can continue the work in an existing version (checkout branch).

… when opening repository for first time…

(a) … by finding the repository url from …

… GitLab

1. Navigate to the repository of your book. Click on the blue button that says “Clone”, and copy the link under “Clone with SSH”.

Fig. 11 The cloning menu.

… GitHub

1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called <> Code.

Fig. 12 Overview

2. Clicking on the button will display the following screen. Make sure the option SSH is selected and copy the link.

Fig. 13 Clone using SSH

… GitHub through GitHub Desktop

1. Open the repository that you would like to clone. In the top bar on the right, you will a green button called <> Code.

Fig. 14 Overview

2. Clicking on the button will display the following screen. Click on Open with GitHub Desktop.

Fig. 15 Clone using SSH

3. The Browser should then automatically open GitHub Desktop. Customize the path to the location where you would like to save to files locally. Finally, click on Clone.

Fig. 16 Clone through GitHub Desktop

You have now directly cloned the repository, so you can skip the next step!

(b) … and opening (cloning) the local repository with …

… VS Code

1. Open a new VS Code window. You should be greeted with a welcome page. On this page, click “Clone Git Repository”. Alternatively, open the Source Control menu from the left side bar, and click on “Clone Repository”.

Fig. 17 The VS Code welcome screen.

2. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you’ve chosen a location, a final prompt will show up asking if you want to open the repository. Click on “Open”.

3. You now have a local copy of the repository.

… GitHub Desktop

1. You have previously copied the link of the repository you would like to clone from GitLab or GitHub. In GitHub Desktop, navigate to the top bar, click on File and then on Clone repository.

2. In the top bar click on URL.

3. Simply paste the link, specify the working directory (location where you would like to save the folder locally) and click on ‘Clone’.

4. You now have a local copy of the repository.

You have now cloned the repository to your computer and you can start branching.
Have a look at the other section!

… when working in previously opened repository…

(a) by creating my own version (branching) or select an existing version (checkout branch) …

Although it is possible to create new branches in VS Code or GitHub Desktop directly, creating new branches on the remote repository (on GitLab or GitHub) is better for collaborating because the new branch becomes immediately visible to everyone working in the repository as opposed to becoming visible after being pushed/published to the remote repository.

… in GitLab

1. Navigate to the repository of your project. Under the project description, you should see a menu button with a “+” in it. Click this button, then click on “New branch”.

Fig. 18 Click the highlighted button to make a new branch.

2. A new page opens, on which you can specify the name of your branch and the source branch. Try to think of a good name for your branch. For example, chapter-2 is a suitable name if we’re going to be working on Chapter 2 of our book. After you’ve made sure that the selected source branch is correct, click “Create branch”.

Fig. 19 We’re making a new branch called chapter-2 from the main branch.

3. You should be sent back to an overview page of your repository. In the branch selection menu, it should now say chapter-2 instead of main.

Fig. 20 The circled menu is the branch selection menu.

… GitHub

How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.

Fig. 21 Demonstration, video available here

1. Open the repository in which you want to work in. In the top bar you will see your current branch main and next to that there is a tab called Branches.

Fig. 22 Overview

2. Clicking on Branches will bring you to an overview of all the branches in the repository. Click on the green Create Branch button.

Fig. 23 Overview Branches

3. Finally, give your branch a name and specifiy the source branch.
   Tip: It makes sense to give the branch a name related to the content you will be creating or altering.

Fig. 24 New Branch

4. You will find your new branch in the drop down menu as seen on the figure below. You can then select your new branch and start working in it (new version) but you can also work in any other branch if you are helping out a colleague with their chapter for example (existing version).

Fig. 25 Select New Branch

(b) and updating my local repository (checking out and pulling) …

… with Git in VS Code

1. Open own version (checking out)

If you want to work in an existing branch you need to check out our new branch in VS Code. Checking out means that we’re changing our working branch (i.e., the one to which we will be committing our changes) from one to the other.

In VS Code, open the branch menu from the bottom left (see Fig. 26). You’ll be be greeted with a menu that looks like the one in Fig. 27. In this menu, we get an overview of the branches of our repository. Notice that our new branch chapter-2 appears as origin/chapter-2, and has a cloud icon in front of it. This means that the branch only exists on the remote repository.

Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of main (in our case chapter-2).

Fig. 26 Location of the branch menu.

Fig. 27 The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch.

2. Update your local repository

Since you are working in a repository with multiple colleagues, it is good practice to make sure your local repository is up to date. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repository. Therefore, you first need to pull all the changes from the remote repository to your local repository. Simply click the Icon with the two arrows.

Fig. 28 name: Pull_VS

Location of the branch menu.

… with GitHub Desktop

1. Open own version (checking out)

The next step is to check out our new branch in GitHub Desktop. Checking out means that we’re changing our working branch (i.e., the one to which we will be committing our changes) from one to the other.

In GitHub Desktop, the top bar has a menu called Current Branch. By clicking on it you can see all the branches you created on the remote repository.

Fig. 29 Branches overview

2. Check out the branch by simply clicking on it. The following window will pop up.

Fig. 30 Leave changes

Leave your changes (stashed) on your working branch, in this case I was working in the branch called collaboration git.

3. Check that the branch is indeed checked out by looking at the branch menu at the the top left again; the current branch should say the name.

4. Update your repository

Since you are working in a repository with multiple colleagues, it is good practice to make sure your local repository is up to date. This is especially important when you want to work in an existing branch. In that case you want to make sure that the existing branch shows in your local repository. Therefore, you first need to pull all the changes from the remote repository to your local repository.

This synchronizes the remote repository with your local repository on your computer. Click on Fetch in the top bar. Then on the same place, click on ‘Pull’.

Now that you have created and checked out your new branch, you can start making and committing changes.