Objective
Learn how to use pull requests for code review with Git by adding an inspirational quote to a teammate's repository.
Mission Brief
You've started getting the grasp of Git with a repository you own. But what if your team is off traveling the universe, and you want to be able to collaborate on the same repo? Complete this tutorial to learn the ropes of code review.
Topics covered:
- Forking a teammate's repository, creating a pull request, and contributing to a teammate's repository.
| Time | Audience | Prerequisites |
|---|
| 15 minutes | You have some experience using Bitbucket Cloud. If not, try out one of our beginner tutorials . | You have installed Git |
| | | You have a Bitbucket account |
About Forking
When you work with another user's public Bitbucket repository, typically you have read access to the code but not write access. This is where the concept of forking comes in. Here's how it works:
- Fork the repository to copy it to your own account.
- Clone the forked repository from Bitbucket to your local system.
- Make changes to the local repository.
- Push the changes to your forked repository on Bitbucket.
- Create a pull request from the original repository you forked to add the changes you made.
- Wait for the repository owner to accept or reject your changes.
If a repository owner accepts the pull request, Bitbucket merges your code changes into the original repository. It is recommended that you work with forks and pull requests, even if the repository owner gives you write access to a public repository. While a pull is part of the Git and Mercurial workflow, pull requests and forks are concepts used only by repository hosting services — like Bitbucket.
Fork a teammate's repository
Since everyone on your team is not in the Bitbucket space station all at the same time, one of your team members decided it would be a neat idea to gather some inspiring quotes that anyone can refer to, whether they are making plans for the new space station on Saturn's rings or adventuring out to a new solar system! Your teammate started up a repository with the thought that anyone can contribute and inspire. You decide that you have a quote you want to add.
In this example you'll fork a public repository belonging to a user called tutorials .
-
Depending on which DVCS tool you are using, use the search field in the top right corner of Bitbucket to find one of the following repositories:
-
From the repository you open, click Fork on the left side of the screen. The system displays the fork page.
-
Change the Name for example, to myteamquotes.
-
In the Description field, enter Inspiring quotes for my team.
-
Uncheck Inherit repository user/group permissions .
-
Press Fork repository .
Copy your fork and make a change to the repository
Have you figured out what piece of advice you want to share with your teammates yet? Let's get a copy of the forked repository to your local system so that you can add it.
I'm using Git!
Step 1. Clone your fork to your local system
-
From the Overview page of the forked repository in Bitbucket, click Clone on the left side. The system displays a pop-up clone dialog. By default, the clone dialog sets the protocol to HTTPS unless you have already set up SSH for Git.
-
From the pop-up clone dialog, copy the highlighted clone command.
-
From your terminal window, change the directory to your repositories
directory.
$ cd ~/repos
-
Paste the command you copied from Bitbucket onto the command line and press Return .
-
Enter your Bitbucket password when the terminal asks for it. This is the password you entered when you created your Bitbucket account. If you created an account by linking to Google or Facebook, use your password for that account. At this point, your terminal window should look similar to this:
$ cd ~/repos $ git clone https:
You now have the forked repository on your local system.
Step 2. Make a change to the repository source
This repository contains a website that has an editme.html file. This file lists inspirational quotes for your space teammates. Now, it is your turn to record an inspirational quote... or just a favorite quote. Do the following to contribute to this repository:
-
Use Google or some other search engine to locate your favorite quote.
-
Navigate to the directory folder containing your repository files (something like ~/repos/myteamquotes ).
-
Open the editme.html
file with a text editor.
-
Go ahead and add a quote of your choosing. You can add an image link to your quote if you like, just place it above the <blockquote> tag.
Here is a sample of what an addition will look like:
<!--
If you are not sure what to do, you can copy the example tags at the top of the file, paste them just below the last quote on the page, and modify them with your quote, as shown in the preceding example.
-
Save and close the file.
-
From your terminal window, change the directory to myteamquotes .
$ cd ~/repos/myteamquotes
-
Display the status of the repository with git status .
$ git status On branch master Your branch is up-to-date with
If you added an image file, you will see that file as well.
-
Add your changes locally with git add :
$ git add editme.html
-
Commit your changes locally with git commit :
$ git commit -m "Making a change" [master 83bc100] Making a change 1 file changed, 10 insertions(+), 5 deletions(-)
-
Enter git push to push the changes to your Bitbucket fork, and enter your password to finish pushing changes.
$ git push origin master Counting objects: 3, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) To https://emmap1@bitbucket.org/emmap1/myteamquotes.git 7479b42..83bc100 master -> master Branch master set up to track remote branch master from origin.
-
Log into your Bitbucket repository and notice you can see your push in the activity stream.
I'm using SourceTree!
Step 1. Clone your fork to your local system
-
From the Overview page of the forked repository in Bitbucket, click the Clone in SourceTree icon.
-
Click the Clone in SourceTree button from the popup that appears.
-
From the Clone New window, update the Destination Path to <local directory>/repos/myteamquotes/
. This destination path refers to the repos
directory you just previously created for repositories.
-
Click the Clone button.
Step 2. Make a change to the repository source
This repository contains a website that has an editme.html
file. This file lists inspirational quotes for your space teammates. Now, it is your turn to record an inspirational quote... or just a favorite quote. Do the following to contribute to this repository:
-
Use Google or some other search engine to locate your favorite quote.
-
From SourceTree, click the Show in Finder button.
-
Open the editme.html
file with a text editor.
-
Go ahead and add a quote of your choosing. You can add an image link to your quote if you like, just place it above the <blockquote> tag.
Here is a sample of what an addition will look like:
<!--
If you are not sure what to do, you can copy the example tags at the top of the file, paste them just below the last quote on the page, and modify them with your quote, as shown in the preceding example.
-
Save and close the file.
-
Open SourceTree and notice that your repository has Uncommitted changes .
-
Click the Commit button at the top to commit the file.
-
Enter the following commit message in the space provided: "Adding new quote."
-
Click the Commit button under the message box. When you switch back to the view, you see that the file has been committed but not pushed to the Bitbucket repository.
-
From SourceTree, click the Push button to push your committed changes.
-
From the dialog box that appears, click OK to push the commit to the repository.
-
Log into your Bitbucket repository and notice you can see your push in the activity stream.
Create a pull request
To aww and inspire your teammate's with words of wisdom, you can request your change to get added to the original repository. To do that, you create a pull request.
Step 1. Compare your fork to the original
While you were working on adding your quote, another teammate might have made updates to the original repository. At this point, you can check that and decide if you need to adjust your fork accordingly. Do the following to compare your changes with the repository:
-
Log into Bitbucket and navigate to your myteamquotes repository. Forked repositories have a special widget that lets you compare your fork work to the original.
-
Click the Compare link on the left side of the page. The Compare section has a specialized view that is available only in forked repositories.
-
Press the Compare button to compare your forked repository to the original repository.
-
If someone has made changes to the original repository since you forked it, you will see that your forked repository is one or more commits behind the original. If that is the case, to update your repository, click Sync now and then Sync on the popup that appears. If you want to see the differences between your current repository and the original repository, click the Diff tab to compare changes. If there are multiple commits, you see their cumulative changes by file in this section. Click the Side-by-side diff button to see changes displayed side-by-side. Or press the View file button to view the full file in Bitbucket.
-
Switch back to the Commits tab to see the list of commits pushed from your local repository to the fork in Bitbucket. To see the contents of a specific commit in isolation, click a Commit link and Bitbucket takes you to the Commits page.
Step 2. Create a pull request
Now it's time to request that your quote get added to the original repository for all to see! From your myteamquotes repository in Bitbucket, do the following:
-
Press Create Pull Request . The system displays the request form.
-
Complete the form. For your purposes today, you only have to add a Title . When you are done it will look something like this:
-
Press Create pull request . The system opens your latest request on the Pull Request page of the original repository in the tutorials account. To see the list of all the pull requests against this repo, click the Pull Request tab.
After you create a pull request, you can't delete it. If you delete your fork after you make a request, the receiver can only decline your request because the repository to pull from is gone.
Step 3. Learn what happens to your pull request
You have to wait for the repository owner to accept your pull request. When the original repository owner logs into Bitbucket, that user's newsfeed shows your pull request and your fork from a few days earlier, as shown in the following image.
When the repo owner clicks on your pull request, that user can Merge, Edit, or Decline it. In addition to owners, anyone with access to the repository can Approve the request, which means that person reviewed the changes in the pull request.
You've contributed to a repository!
You'll get an email when your pull request is accepted or rejected. If you want to try out other things in Bitbucket while you wait, check out how to enable an issue tracker , set up a wiki , or add user permissions .
