Next up: Learn Sourcetree with Bitbucket

As our new Bitbucket space station administrator, you need to be organized. When you make files for your space station, you’ll want to keep them in one place and shareable with teammates, no matter where they are in the universe. With Bitbucket, that means adding everything to a repository. Let’s create one!

Initially, the repository you create in Bitbucket is going to be empty without any code in it. That's okay because you will start adding some files to it soon. This Bitbucket repository will be the central repository for your files, which means that others can access that repository if you give them permission. You will also copy a version of that repository to your local system—that way you can update it from one repo, then transfer those changes to the other.

Do the following to create your repository:

1. From Bitbucket, click  the  +  icon in the global sidebar and select Repository. Bitbucket displays the Create a new repository page. Take some time to review the dialog's contents. With the exception of the Repository type, everything you enter on this page you can later change.
   

2. Enter BitbucketStationSupplies for the Name field. Bitbucket uses this Name in the URL of the repository. For example, if the user the_best has a repository called awesome_repo, the URL for that repository would be https://bitbucket.org/the_best/awesome_repo.

3. Keep the rest of the options as is unless you want to change them:

   • Access level —Leave the This is a private repository box checked. A private repository is only visible to you and those with access. If this box is unchecked, anyone can see your repository.

   • Include a README? —If you recently created your account, this defaults to a tutorial README. For the purposes of this tutorial, pick either of the Yes options, that way you'll start out with a file.

4. From Version control system, you can choose either Git or Mercurial. If you aren't sure which one to go with, keep Git as your option.

5. Click Create repository. Bitbucket creates your repository and displays its Source page.

Take some time to explore the repository you have just created. To view the shortcuts available, press the ? key on your keyboard.

Click + from the global sidebar for common actions for a repository. Scan through the links in the navigation sidebar to see what's behind each one, including the repository Settings where you'll update repository details and other settings. Click the Commits in the sidebar. If you included a README, you'll see one commit on that page.

Your repository is private and you have not invited anyone to the repository, so the only person who can create or edit the repository's content right now is you, the repository owner.

Now that you have a place to add and share your space station files, you need a way to get to it from your local system. To set that up, you want to copy the Bitbucket repository to your system. Sourcetree refers to copying a repository as "cloning" it. When you clone a repository, you create a connection between the Bitbucket server and your local system.

Use Sourcetree to clone your repository to your local system without using the command line.

1. As you use Bitbucket more, you will probably work in multiple repositories. For that reason, it's a good idea to create a directory to contain all those repositories. So start by creating a directory on your local system and call it repos.

2. From Bitbucket, go to your BitbucketStationSupplies repository.

3. Click the Clone button in the top right corner. Bitbucket displays the Clone this repository dialog. 

4. From the Clone this repository dialog, click Clone in Sourcetree.

5. From the Clone New dialog box, update the Destination Path to /repos/bitbucketstationsupplies. This destination path refers to the directory you just created with the folder for the repository. The Name field remains the same with the folder name of the repository. 

6. Click the Clone button.

Congratulations! You've cloned your repository to your local system.

With the repository on your local system, you can start making a list of all the supplies you need for your space station. To do so, let's create a file for your supplies.

As you work on this section, the images may look slightly different, depending on whether you are working with a Git or Mercurial repository.

1. Double-click the bitbucketstationsupplies repository in Sourcetree and notice that there is nothing to commit from your local repository to the remote repository.
   

2. Use a text editor to add the following three lines:
   space ice
cream nerf
darts telescope light shield

3. Save the file as supplies.txt to the bitbucketstationsupplies directory on your local system. The supplies.txt file now appears in Sourcetree since you created it in your local repository.
   

4. Now is the point where you prepare a snapshot of the changes before committing them to the official history. From the options menu of the supplies.txt file, select Stage file (for a Git repository) or Add file (for a Mercurial repository).
   
   

5. Click the Commit button at the top to commit the file.

6. In the message box, enter "Initial commit."
   

7. Click the Commit button under the box. Your new file is now committed to the project history. 
   
   Up until this point, everything you have done is on your local system and is invisible to your Bitbucket repository until you push those changes to your remote Bitbucket repository.

8. From Sourcetree, click the Push button to push your committed changes. Pushing lets you move one or more commits to another repository, which serves as a convenient way to publish contributions.
   

9. From the dialog box that appears, your next step depends on whether you are using Git or Mercurial:

   • Git–Under the Push? column, select the main branch to indicate that you are pushing that branch to origin and click OK.
     

   • Mercurial–Everything is automatic, so all you have to do is click OK.

10. Go to your BitbucketStationSupplies repository in Bitbucket.

    • If you click Commits in the sidebar, you'll see your commit in the repository. Bitbucket combines all the things you just did into that commit and shows it to you.

    • If you click Source in the sidebar, you'll see your file in the repository, the supplies.txt file you just added.
      

Next on your list of space station administrator activities, you need to file out a request for new supplies. Let's set up a system for getting supplies to our Bitbucket space station. With just a bit more knowledge of Bitbucket and Sourcetree, we'll be supporting our space exploration for years to come!

To add your supply request file, do the following:

1. From your BitbucketStationSupplies in Bitbucket, click Source to open the source directory. Notice you only have one file, supplies.txt, in your directory.
   

   • A. Source page: Click the link to open this page.

   • B. Branch selection: Pick the branch you want to view. 

   • C. More options button: Click to open a menu with more options, such as 'Add file'.

   • D. Source file area: View the directory of files in Bitbucket. 

2. From the Source page, click the More options button in the top right corner and select Add file from the menu. The More options button only appears after you have added at least one file to the repository. A page for creating the new file opens, as shown in the following image.
   

   • A. Branch with new file: Change if you want to add file to a different branch.

   • B. New file area: Add content for your new file here.

3. Enter supplyrequest in the filename field.

4. Select HTML from the Syntax mode list.  

5. Add the following HTML code to the text area: 

   We are requesting additional supplies. Please send us the following:

   
   
   
   
   • space ice cream
   
   
   • nerf darts
   
   
   • telescope light shield
   
   

6. Click Commit. The Commit message field appears with the message: supplyrequest created online with Bitbucket.

7. Click Commit under the message field.

You now have a new file in Bitbucket!  You are taken to a page with details of the commit,  where you can see the change you just made: 

If you want to see a list of the commits you've made so far, click Commits in the sidebar.

Now we need to get that supply request form onto your local system. The process is pretty straight forward, basically just the reverse of the push you used to get the supplies.txt file into Bitbucket.

To pull the file into your local repository, do the following:

1. Open your repository in Sourcetree, and click the Pull button.
   
   A popup appears to indicate that you are merging the file from Bitbucket to your local repository.
   

2. Click OK from this box. Sourcetree updates with a description of the merged file.
   

3. Navigate to your repository folder on your local system and you'll see the file you just added.

Fantastic! Now, you have finished the basic DVCS workflow (clone, add, commit, push, and pull) between Bitbucket and your local system.

After looking through the Intergalactic Mall Magazine, you see a pair of speakers that you really want for the space station. They are big enough to produce a good amount of sound and soft enough that the lack of gravity won't cause them to crash. The only problem is that they pretty pricey, and you need approval before you can officially add them to your list of supplies.

In the meantime, create a feature branch so that you can update the supply to your request list while you wait. Then when you have approval, you just merge the requests file from the feature branch into the main branch.

Branches are most powerful when you're working on a team. You can work on your own part of a project from your own branch, pull updates from Bitbucket, and then merge all your work into the main branch when it's ready. Our documentation includes more explanation of why you would want to use branches.

Let's create a branch so that you can list the speakers in your supply requests file. Even though branches work differently between Git and Mercurial, you create them in a similar way from Sourcetree.

1. From Sourcetree, click the Branch button.
   
2. Depending on whether you have a Git or Mercurial repository, you see a different popup for creating a new branch. From the New Branch or Create a new branch field, enter wish-list for the name of your branch.
   
   

3. Click Create Branch or OK.

4.  From Sourcetree, click the Show in Finder button. The directory on your system opens.

5. From the directory folder, open the supplyrequest file with a text editor.

6. Making a change to the file by adding the following item to the list of supplies: 
   

7. anti-gravity speakers

8. Save the file.

9. Open the view in Sourcetree and notice that your repository now has uncommitted changes.
   
   From here, everything you do is the same as you did when you added the supplyrequest file and initially committed it.

10. If you have a Git repository, make supplyrequest.txt ready to commit by selecting Stage file from the options menu.
    

11. Click the Commit button at the top to commit the file.

12. In the message box, enter "Adding an item for my wish list."

13. Click the Commit button under the box. From Sourcetree, you see that the file has been updated on the wish-list branch.
    

Your speakers were approved! Now it's time to update the main supply list with your wish-list item.

1. First, you want to switch back to the main branch. From the left-side menu items in Sourcetree, hover your mouse over the right side of the Branches label so that the word Show appears.
   
2. When Show appears, click it. Under the Branches heading, you will see the two branches for this repository, the main branch, and the wish-list branch. The main branch for a Git repository is called main. The main branch for a Mercurial repository is called default.
   

3. Double-click the feature branch (in this case wish-list) to switch to that branch.

4. Click the Merge button.
   

5. From the popup that appears, make sure the commit on your wish-list branch is highlighted. You are indicating that you want to add the commit from this branch to the main branch.
   

6. If you have a Git repository, check this option at the bottom: Create a commit even if merge resolved via fast-forward.
   

7. Click OK. You have updated the supplyrequest file in your main branch with your wish-list item. Sourcetree will look slightly different based on whether you have a Git or Mercurial repository.
   

8. If you have a Git repository, you are done. If you have a Mercurial repository, you will notice that you need to commit your changes. Click the Commit button at the top. The commit message defaults to a description with "Merge." Keep this message and go ahead and click Commit.

1. From Sourcetree, click the Push button to push your committed changes.

2. From the dialog box that appears, click the OK button to push changes to your local repository.

3. Click the Overview page of your Bitbucket repository, and notice you can see your push in the Recent Activity stream.

4. Click Commits and you can see the commit you made on your local system. Notice that the change keeps the same commit code that it had on your local system.
   

5. Click Source, then click the supplyrequest file. You can see the last change to the file has the commit code you just pushed.

6. Click the file history list to see the committed changes for this file, as shown in the following image.

That was intense! Maybe. Depends on how it compares to launching into space. Now that you know a lot more about Bitbucket, you are now prepared to run your space station's activities a lot better. Now, take a break and go do some star gazing.

Want to learn more about Bitbucket and Sourcetree? You can take on the challenge of updating a teammate's repository.