Bitbucket Setup and Usage Guide
Please ensure you have read and completed the Git and SourceTree Guide before completing this tutorial.
Jump to step:
- Background: Bitbucket vs Github
- Background: Offsite Git Repositories
- Creating a New Bitbucket Remote Repository
- Configuring a Remote Repository
- Pushing Repositories
- Pulling Repositories
When it comes to remote (i.e. not on your PC) Git repositories, there are two main options: GitHub and Bitbucket. Both platforms provide similar functionality, but with different licensing models. GitHub is traditionally an open source project platform, where projects such as IPL’s OPTI Toolbox is hosted for free. In contrast, Bitbucket provides users with free private (i.e. closed-source) repositories, which is why we started using it. We now subscribe to Bitbucket to allow increased team member count, thus this is our preferred offsite Git platform.
The main advantage of an offsite Git repository is that it provides a central repository where team members can collaborate on a project. While technically this repository could be any one team member’s repository, network administration makes it difficult to allow pushing and pulling between individual computers. Therefore, for all your projects, the remote repository is chosen as a Bitbucket hosted private repository, providing both offsite redundancy, as well as an ‘always on’ central repository.
Note: Normally you will be working on an existing repository, or if you are creating a repository, it will be created under an IPL project.
To create a new repository within Bitbucket, click on the “Repositories” button
then click on “Create Repository”:
Complete all the fields indicated below, ensuring they match your project parameters, then click create.
You will note that the new Bitbucket repository you just created is empty. In order to synchronize it with your local Git repository, we need to tell SourceTree this remote repository exists, its address, and then push it to the remote Bitbucket repository.
Within Bitbucket, in your new repository on the Overview page, you will see “Command line” and underneath “I have an existing project”. Click on this to expand a code box, where an address of this repository is shown. Highlight and copy the address (not the entire set of commands), as highlighted below for the example Bitbucket repository:
Now open up SourceTree, and bring up the repository we created in Section 4. Click on Repository->Repository Settings, as per the below figure:
Under Remotes, click Add:
Under Remote Details, enter the Bitbucket Repository name into “Remote Name”, and paste the address copied from Bitbucket into “URL / Path”:
SourceTree will automatically populate the Host Root URL, and your username from the URL you pasted. Click OK in both windows to complete the remote linking:
Once the previous steps have been completed, the remote repository is linked and you will not need to complete them again for this repository:
Pushing a repository (“push”) is when you want to synchronize all the commits and code changes located in your local repository, with another (likely remote) repository. A push operation infers your repository is the master copy, and the remote will be updated to match your master copy (one-way synchronization).
To push the changes from the local repository to the Bitbucket remote repository, Click Push:
SourceTree will ask which branches you wish to push to the remote repository. For this example we will push both branches, which would be a typical workflow. Select push for both, and click Push:
The push operation takes a few seconds to authorize with Bitbucket, then upload the files/changes. Once complete, refresh the Bitbucket repository page, click “Commits”, and you should see the same sequence of commits as in your local repository:
Alternatively, you can push your commit(s) to the remote repository by ticking the box at the bottom of the commit message:
This is the suggested method of pushing to a remote repository. Note only push on the last commit if multiple commits are added together, to minimize upload time.
Pulling is the opposite operation from pushing, where instead of your local repository being the master, the remote repository is the master. A Pull operation is used to synchronize your local repository with the remote repository, where perhaps other team members have committed to it, and you want to use their changes on your PC/in your development environment.
To simulate the effect of the remote repository being updated by a team member, we will add a read me file to the repository via Bitbucket, which we will then commit on the remote repository.
Click “Create a README” within the “Overview” tab of Bitbucket, and click Save once the default read me document has been generated (or change if you like, this is just an example). This will automatically commit the change to the remote Bitbucket repository within the master branch:
This source change is now recorded in the remote repository, but not on your local repository. In order to synchronize the changes, we will “Pull” the remote repository to your local one.
Within SourceTree, you should see a “1” next to Pull, as well as a down arrow (download) next to the master branch under the repository list. If not, click Repository->Refresh Remote Status:
This “1” indicates your local repository is one commit behind the remote repository. Click Pull:
Confirm you are pulling from the correct repository and branch, then click OK. You will now see the latest commit from Bitbucket in your commit list.
For further reading on Bitbucket, including a whole host of features not discussed here, visit: https://support.atlassian.com/help/#/