The Git and SourceTree beginner's guide to contributing to open-source projects in GitHub - Part 3 - Working with SourceTree

By now you have learned the essential concepts you need to start using Git (part 1) and have done some forking and branching in GitHub (part 2)

Let’s move on to serious stuff with SourceTree.

Posted by Nour Akalay on December 18, 2019 - Updated on October 8, 2020.

Installing SourceTree

If you haven’t already, download SourceTree and install it.

To install SourceTree you need a (free) BitBucket account. BitBucket is a GitHub competitor from Atlassian, also makers of SourceTree.

If you’re going to start using Git, it’s a good idea to have a BitBucket account since, unlike GitHub, they offer private repositories with their free accounts. In Github, you get only public repositories on the free plan.

While installing SourceTree, provide your BitBucket credentials and, when asked, select Git and not Mercurial (another versioning system) unless you want to give it a try.

Getting SourceTree set up

Before we start it is worth noting that SourceTree is different on Mac and Windows. I am not sure to what extent since I don’t have a Mac, but I believe the essentials are still pretty much the same.

Once SourceTree is installed we need to add your GitHub account to it. There are several ways of doing that and we’re going to use the easiest: connection over HTTPS.

First make sure that, in your browser, you are logged in to your GitHub account. That will save us an extra step.

In SourceTree, using the top menu navigate to Tools ⇒ Options.

In the popup that opens, select the “Authentication” tab and click on the “Add” button.

In the second popup that opens set:

• Hosting Service to “GitHub”
• Preferred Protocol to “HTTPS”
• Authentication to “OAuth”

In case you’re wondering, the “Basic” authentication type uses your account’s username and password and has been deprecated by GitHub so it will stop working soon. It’s also not that secure.

Then click on the “Refresh OAuth Token.”

A window will open and load in your browser. As soon as it says you are connected or it simply stops loading, you should be good to go.

When your account is successfully connected you will see it indicated in SourceTree and your username will appear in the Username field.

Click OK and you will see your account added to the list—with your avatar if any—on the previous popup.

Et Voila! Congratulations, you’re all set-up to work and interact with any repository hosted in your GitHub account.

Let’s get local

In part 2 of this guide, we already forked the original Concrete5 repository to your account. We now want to clone your fork to your local environment (a.k.a. your computer)

The easiest is to do it all from SourceTree. Using the top menu navigate to File ⇒ Clone / New…

A new window will appear titled “Clone” but we’re going to go the easier way and click on the “Remote” tab instead.

Once you click on the “Remote” tab you will see a list of your accounts. Click on the account you have just added and you’ll see a list of repositories hosted under that account.

I now that search box looks mighty handy but in my experience it’s terrible. You type a keyword and it only shows you some of the repos matching the keyword. No idea why.

Anyway, click on the “Clone” link, to the right of your chosen repository, and you’ll be taken back to the “Clone” tab with all the fields already filled for you.

In the first field, the GitHub repository URL is set correctly.

The second field is the path to your local repository’s folder. Select any folder you want. I put mine under my localhost server.

Below the path is the name you want to give your local repository. It doesn’t have to be the same as the remote repository.

Finally, if you followed part 2 of this guide and already created a branch in GitHub, you should select it in the “Checkout branch”  list under “Advanced Options.”

When you’re all set, click the “Clone” button at the bottom.

And that’s it for cloning. You now have all the content of your remote repository copied to your local folder for you to work with.

It is a bit overwhelming and it looks like this:

Branching and selecting a branch

Unless you had already created a branch in GitHub and selected it when cloning, you now should (must) create a new branch to work on.

In any case, it’s a good skill to have so let’s learn to do it in SourceTree too.

We’ll also learn to select an existing branch.

Have a look at your left-hand navigation bar.

Under the “BRANCHES” label you see currently existing branches in your local environment and the active branch (bold with a little circle next to it) clearly selected.

Under the “REMOTES” and “origin” labels you see branches that exist in your remote repository.

First, let’s see how to create a new branch from an existing one.

You can branch from any of the remote or local branches.

You can do that by clicking on either:

• the “Branch” button in the top toolbar
• the “Checkout” option from the dropdown menu that appears when you click on an existing branch

Which you decide to use depends on what you’re trying to do.

• The “Branch” button in the top toolbar is used to branch from the currently active branch.
• The “Checkout” option from the dropdown menu is used to branch from any other branch, local or remote.

Branching from the active branch

In the screenshot above my active (and only local branch) is “Develop”. According to Concrete5's contributing guidelines, that’s the branch I should use so branching from it makes sense.

Let’s click on the “Branch” button and create our new branch from the popup that opens.

1. You can see the current branch from which you’re branching out.
2. You give your new branch a name.
3. You make sure you check the checkout box.
4. Just leave the rest as it is.
5. Click on the “Create Branch” button

And you’ll see your new branch appear on your list and be selected.

Branching from any other branch

Alternatively, let’s say you want to branch from a remote (or local) branch other than the active one.

Click on the branch with your mouse (right button on PC) and click on the “Checkout” option from the dropdown menu. The following popup appears:

1. To create a new branch make sure you are on the correct tab.
2. Select the branch to checkout so we can branch from it.
3. Give your new branch a name.
4. Uncheck the checkbox since our new branch should track a branch that doesn’t exist yet remotely.
5. Click “OK”

And you’ll see your new branch appear on your list and be selected.

Switching from one branch to another

Creating one branch out of another is all good and well but sometimes you simply want to switch to an existing branch.

If you remember the essential concepts we learned in part 1 of this guide, you know it means to “Checkout” a branch.

And that’s exactly what you did in the previous part when branching from an existing branch. You did a checkout followed by the creation of a new branch.

So you have two possibilities here:

1. To switch to a remote branch follow the steps explained above to branch from any branch. This will make a local branch out of a remote one and make it active.
2. To switch to another existing local branch, also click on the branch and select the “Checkout” option. This time however that’s all there is to it, the branch you selected will simply be made active.

Write your modifications and commit them

Before we go anywhere with this keep in mind that if you modify your code and decide to switch branch before committing your modifications, you will lose them.

Well in SourceTree it’s not totally true since it’s smart enough to warn you and offer to commit before switching. But in any case, committing before switching branch is a good habit to develop so just do it.

Now either browse your computer to get to your files and modify them or alternatively, from the top menu in SourceTree navigate to Actions ⇒ Show in Explorer and it will open the folder where the current repository is saved. And modify away!

Then come back to SourceTree.

Your toolbar’s “Commit” button shows you how many files were modified. Under the “WORKSPACE” label in the left-hand navigator, click on “File Status” to see the list of modified files.

Pro tip: sometimes SourceTree loses the plot a bit and doesn’t refresh the list. It’s rare but it happens. Just hit F5 on your keyboard to bring it back from the dead.

After clicking on “File Status” you now have a central space in SourceTree divided in 2: “Staged Files” and “Unstaged Files”

All your newly modified files are unstaged files.

You cannot commit unstaged files. You must first stage files you want to commit. That’s why the “Commit” button is disabled.

Go ahead, select the files you want to commit and stage them using the “Stage Selected” button or simply click on the “Stage All” button.

For now, do not check the “Push changes immediately to -” checkbox.

You’ll notice it doesn’t say where the commits will be pushed to. This is because, for now, the branch I am working on was created locally and doesn’t exist remotely.

The corresponding remote branch will be created when I push my commits to the remote repository.

If you click on any file, it shows you the modifications in the right-hand space. In red what was deleted and in green what was added.

Once you staged your files the “Commit” button is enabled. You can write your commit message and commit.

And that’s it. Your files’ modifications are saved.

If at this point you decide to switch to a different branch and come back to this one later you’ll find everything as you left it.

How about you try it? Switch to a different branch and look at your files in your editor of choice. Then switch back and check again. It’s like magic!

Please, note that you can have as many commits as you need before moving on to the next step.

Time to push to remote

The last step, as far as our local repo is concerned, is to push the code to our remote repository.

In my case, it will also create a new branch in my remote repository to mirror the one I checked out locally.

This is pretty simple:

1. Make sure the branch you intend to push is still the checked out one.
2. Make sure you committed everything you want to push remotely.
3. Click on the “Push” button in the top toolbar.

A new popup will open.

First, check that it’s pushing to the correct remote repository.

Then check the box at the left of the branch you want to push and make sure you track it.

In my case, the “Remote branch” field is empty since I am not pushing to an existing remote branch but creating a new one. Otherwise, the proper remote branch would be automatically selected (as it is for the develop branch below) or I would select it myself.

Finally, click the “Push” button and that’s it, your local branch was mirrored in your remote repository and your local code modifications have all been pushed there.

What’s next

We’re done with SourceTree for now. That was a long one but we’re not done just yet.

It’s time to go back to GitHub and send a pull request to the original Concrete5 repository.

In part 4—and last—of this guide, we’ll open a pull request and fix any issue if required.