1 What is a branch?

A branch lets you develop code, fix a problem, or test an idea without affecting the original project. A branch is created from an existing branch, usually from the main branch of the project. Note that main branch was previously named master branch, but removed because of the reference to slavery. Because of this change you might find references to the old name when looking for help elsewhere.

You can work on a branch, bravely develop code that works or does not work and it does not break the code on the main branch. Basically, you can experiment on your own.

If the idea did not work or you have another idea, the branch can be deleted and nobody ever needs to know about it. Make a new branch and start all over again. None of this will affect the original project.

If you are working on your own project, and happy with the new code, or the idea is tested and working, you can merge the branch you are working on with the main branch.

1.1 The workflow

To understand the workflow, let’s see how Kingsley is using branches (see Figure 1.1).

Kingsley owns a GitHub repo. He clones the repo to his computer (1). To develop code, he create a new branch (2) and makes commits (3). Then he merges the new branch with the main branch locally on his computer (4). Finally, he pushes these changes to his remote repo on GitHub (5). Kingsley then continue the workflow (2-5).

Figure 1.1: Workflow using branches

Let’s have a look how to create, use and delete branches.

1.2 Make a new branch in RStudio

In RStudio, click on the New Branch button in the Git tab. Next to this button it will say on which branch you are. In this case it is main, which is the default branch.

Give the branch a short and informative name (no spaces) and click Create.

You are now in the newly created branch.

If you want to switch back to the main branch or another branch, click again on the box in the top corner to switch. Note that you cannot switch to another branch if you have uncommitted changes. They need to be committed first.

1.3 Code, commit and push to origin in RStudio

Now is the time to work in a new or edit an existing file on the project. You can work the way it is described in the ?? How to work with GitHub tutorial. Write or edit code, test it, commit regularly and add a useful commit message.

Once you are done with the task it is time to merge your new branch into the main branch.

First you need to go to the main branch. For this go to the Terminal and type:

git checkout main

To merge the new branch into the main branch type:

git merge my_branch

For the example we had above, where the name of the new branch was community_analysis it would be:

git merge community_analysis

The last step is to push these changes from the new branch to GitHub. For this, go to the git tab in RStudio and push the green arrow.

RStudio also tells you that your branch is 2 commits ahead of the main branch, which means that you have made 2 commits on this new branch.

1.4 Delete branches

Once you have created a couple of branches, it will become difficult to track which branch you are still working on and which are old. Generally, you want to delete a branch when you are done with it.

To delete a branch locally type:

git branch -d community_analysis

To delete the branch remotely, type:

git push origin --delete community_analysis

1.5 Trouble shooting

Check configurations in the Terminal

You might want to check the configurations of your repository. In the Terminal you can check the origin of your repo, which is from where you push and pull. And it will show you if your origin is wrong.

Go to the Terminal tab and type repo type:

git remote -v

The output will look like this:

origin  git@github.com:kingsleyshacklebolt/magic_dragons.git (pull)
origin  git@github.com:kingsleyshacklebolt/magic_dragons.git (push)

Handle a merge conflict

A merge conflict can occur when you are changing the same line in one file differently, for example using two different branches.

The goal is to avoid such conflicts and a good strategy for this is to commit often, work in small steps, push and pull regular. Merge conflicts can be avoided if you use separate branches for each file that you are creating or editing.

But merge conflicts cannot always be avoided. If it should happen you will get notified in the Terminal when you are trying to merge the new branch with the main branch. The message will look like this

CONFLICT (content): Merge conflict in R/dragon_analysis.R

First, do not panic. This message simply tells you that you cannot do the merge and there is a merge in the “dragon_analysis.R” file.

Go the the file with the merge conflict, which will look like this:

### Dragon analysis ###

library("broom")

# Import data
source("R/import_dragon_data.R")


# Run model

<<<<<< HEAD:dragon_analysis 
mod <- lm(body_size ~ body_length, data = dragon)
======
  mod <- lm(body_size ~ body_length * temperature, data = dragon)
>>>>>>> issue-5:dragon_analysis 

tidy(mod)

In this file the merge conflict starts with <<<<<< HEAD:dragon_analysis indicating the name of the file. Then the two different versions of the code are shown, and separated by ======. Finally, >>>>>>> issue-5:dragon_analysis indicates the end of the merge conflict.

To resolve the conflict, you have to edit this section and remove the conflicting parts. Basically, choose one of the versions or combine them. Also remove the conflict markers <<<<<<, ====== and >>>>>>.

### Dragon analysis ###

library("broom")

# Import data
source("R/import_dragon_data.R")


# Run model
mod <- lm(body_size ~ body_length * temperature, data = dragon)

tidy(mod)

Save the file, commit, switch to the main branch, merge and push to GitHub.

Easy peasy!

What’s next

For collaborating with others on the same project read the chapter on Collaborating with forks

Contributors

Aud H. Halbritter
Richard J. Telford

Working with branches