How to collaborate on Bitbucket.

org
using Git
by Phong Cao (ID: 108512924)
Contents at a Glance
Contents at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1. Create a Bitbucket Academic Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Download and Install Git for Windows and/or Mac OSX . . . . . . . . . . . . . . . . . . . . . . . 2
3. First-time set-up for Git. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
4. Generate SSH Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Make Git Bash remember SSH Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
6. Add SSH Key to Bitbucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
7. Fork a project to your Bitbucket account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8. Subscribe to a Bitbucket repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
9. Grant fork repository access to team members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
10. Clone a fork to local computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
11. Update, Add and Delete Remotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
12. Git Commit & Git Push Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
13. Git branch commands, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
14. Update (Synchronize) local fork with the original repository. . . . . . . . . . . . . . . . . . . 30
15. Create a Pull Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
16. (For Administrators) Merge the Pull Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
17. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

1. Create a Bitbucket Academic Account:

1.1. If you havent had a Bitbucket account yet please go to https://bitbucket.org/ and
register for one with your email address.

2. Download and Install Git for Windows and/or Mac OSX:

2.1. Go to the following link to download Git command-line setup for both Windows and
Mac: http://git-scm.com/downloads
2.2. For Ubuntu and Fedora, you can install Git through issuing platform-specific install
commands:
$ sudo apt-get install git
$ sudo yum install git

# for Ubuntu, Aptitude, deb packages

# for Fedora, YUM, rpm packages

Other Linux and UNIX distributions follow similar procedures.

2.3. This User Manual will mostly present examples and screenshots of Git
commandline, but the steps should apply similarly in IDE-embedded Git. Thus, if you
dont have to use an IDE (see the reasons above), please please please use Git
command-line to make this manual easier to understand and learn interesting Git stuffs.

3. First-time set-up for Git:

3.1. Open your command-line Git and set your Git public identity for easier collaboration
and identification as follow:
$ git config --global user.name <First Name> <Last Name>
$ git config --global user.email <Your Email Address>

3.2. By default, Git lets you type in your commit message using the systems commandline. However, you can set Git to use a different editor for your commit message:
$ git config --global core.editor <Your Text Editor of Choice>

3.3. If you want to check all of your Git settings, issue the following command:
$ git config --list

Or the following command if you just want to check for a particular setting:
$ git config <Settings Name>

4. Generate SSH Key:

4.1. Check if you have existing default Identity:

4.1.a. Open Git (or Git Bash on Windows)

4.1.b. Enter the following command to verify the SSH client is available:
$ ssh -v
If you are using Git Bash (Windows) or have ssh installed (Mac OSX), you should see
the following output:

4.1.c. Now that you have ssh installed, enter the following commands to check if you
already have an SSH key:
$ ls -a ~/.ssh
If you have not used SSH on Git Bash or Terminal you will see something like this:

If you have already had a default identity, you will see two id_* files (Skip immediately to
Step 5):

The content of the id_rsa.pub file is what we are after.

4.1.d. If you havent yet had the SSH Key files, issue the following command to create
them:
$ ssh-keygen
If it asks Enter file in which to save the key: and Enter passphrase: and Enter same
passphrase again: just leave them blank and press <Enter>. The final output should
look like this:

After this, issue the command in Part (c) above to make sure that the SSH Key has been
generated:
$ ls -a ~/.ssh
which should show the following output:

5. Make Git Bash remember SSH Key:

5.1. Use your favorite text editor, edit an existing (or create a new) file called config
under ~/.ssh folder (or in other word, edit or create a new ~/.ssh/config file) with the
following content:
Host bitbucket.org
IdentityFile ~/.ssh/id_rsa
This config file is similar to the option Remember me or Remember my Username and
Password when you log-in into Amazon or Google. It helps you not having to enter the
whole SSH Key anytime you push your stuffs to Bitbucket.org.
NOTE: The single space in the 2nd line is VERY important! You have to indent exactly 1
space or Git Bash wont be able to remember your SSH Key.
5.2. Save and close the file.
5.3. Restart your Git Bash terminal

6. Add SSH Key to Bitbucket:

6.1. From the top right corner of Bitbucket, go to Manage Account which display the
Account Settings page.

6.2. In the Account Settings page click on SSH keys on the left sidebar, which takes
you to the SSH Keys page. Now click on Add Key to add your SSH Key to Bitbucket:

6.3. A dialog will appear letting you add the key. Simply enter a name for the key in the
Label textbox and paste the whole content of ~/.ssh/id_rsa.pub file into the Key
textarea (the extension *.pub indicates that this file contains SSH Key for registering on
public sites & repos like Bitbucket. The id_rsa file on the other hand only responsible for
logging-in when you do a Git push):

6.4. Finally, click Add to add the SSH Key into your Bitbucket account.

7. Fork a project to your Bitbucket account:

7.1. From the top Bitbucket navigation bar, click on Team -> <Team_Name>. This will
bring you to the Bitbucket page for <Team_Name> Team:

7.2. Now click on the URL for <Project_Name> project, which would lead you to the
<Project_Name> project main page:

7.3. On the <Project_Name> project homepage, click on Expand Sidebar at the bottom
to expand the Bitbucket Sidebar:

7.4. On the expanded Bitbucket Sidebar youll see an option called Fork. Click on that
Fork link will lead you to the Fork settings page where you can set options for your
fork:

7.5. After the Fork settings page is displayed, enter the information as below and click
Fork Repository to fork the original <Project_Name> repo to your Bitbucket account:

10

7.6. After this step, go back to your homepage. You should see a project called
<your_Bitbucket_username>/<Project_Name> under your Bitbucket homepage. Click
on that project link to get to the Overview page of your <Project_Name> fork:

7.7. When youre at the Overview page of your <Project_Name> fork, you will see a line
called Fork of which indicates the original repository that this <Project_Name> fork
belongs to, and on the top-right of the screen you will see an SSH link that you will (later)
use to clone the fork to your local computer and update it as changes are made to the
original repo:

7.8. Now as youre done with the forking of <Project_Name> to your Bitbucket account,
copy the SSH link (shown in the above screenshot) and move on to the next step!

8. Subscribe to a Bitbucket repository:

11

8.1. From the top Bitbucket navigation bar, go to the Bitbucket page for <Team_Name>
Team and then <Project_Name> project repository:

8.2. When youre at the Bitbucket page of the <Project_Name> repository, click on the
Down arrow next to the Watch button on the top right of the project Bitbucket page.
Check all the checkboxes so that you can watch for all the changes (Wiki, Push, Pull,
etc.) of the project:

12

8.3. Now go to your (fork) <Project_Name> repository on Bitbucket and repeat the 2
steps above. This is very important because it lets you know in case there is any team
member that forks your <Project_Name> fork repository.

9. Grant fork repository access to team members

9.1. From the Bitbucket navigation bar, go to your Bitbucket account homepage and then
your <Project_Name> fork repositorys Overview page:

9.2. On your <Project_Name> fork repository Overview page, expand the left sidebar.
Click on the item called Settings to access the settings of your <Project_Name> fork
repository:

9.3. On your <Project_Name> fork repository settings page, click on Access

Management to access the Access Management page:

13

9.4. When youre on the Access Management page, click on the drop-down menu in the
Groups section and choose Administrators (<team_name>:administrators) then click
Add. Do the same for Developers (<team_name>:developers) group in the drop-down
menu. The final result is in the second screenshot following:

14

10. Clone a fork to local computer

10.1. Now that you have copied the SSH link, open Git Bash and issue the following
command:
$ git clone [email protected]:<your_Bitbucket_username>/<Project_Name>.git
~/<Project_Name>
This command will clone (or download, in other words) the <Project_Name> fork from
your account to a folder called <Project_Name> under your home folder.
+ If youre using Windows, the path to folder is
C:\Users\<your_Windows_username>\<Project_Name>.
+ If youre using Mac OSX or Linux, the path to folder is
/home/<your_username>/<Project_Name> or simply ~/<Project_Name>.

15

10.2. After the cloning process is finished, you can check to see if the Git remote repo of
your local <Project_Name> match with the SSH link of the <Project_Name> fork on your
Bitbucket account by cd-ing into the projects folder (which means getting inside the
project folder using the command-line) and issuing the following command:
$ git remote -v

10.3. So in the above screenshot, I got my remote addresses correctly. The remotes, by
default, are called origin and their addresses should match the SSH addresses of your
<Project_Name> fork.
As you can see, after the URL of each remote there is a parentheses indicates what
kind of remote it is. In this case, (fetch) remote means that when you do a Git pull and
a Git fetch (youll see it later), the source code will be fetched from this URL to your
local computer. When you do a Git push (which means uploading your code to your
Bitbucket <Project_Name> fork), the (push) remotes URL will be where your code is
gonna get uploaded.

11. Update, Add and Delete Remotes

11.1. In order to update the URL of a Git Remote, issue the following command:
$ git remote set-url <remote_name> <new_remote_url>

16

As you can see in the above screenshot, I changed the URL of the origin remote from
[email protected]:phongvcao/<Project_Name>.git to phongvcao.com

11.2. In order to update the Name of a Git Remote, issue the following command:
$ git remote rename <old_remote_name> <new_remote_name>

As you can see in the above screenshot, I changed my origin remotes name from
origin to phongvcao.

11.3. In order to add a remote, issue the following command:

$ git remote add <remote_name> <remote_url>

17

As you can see in the above screenshot, I added a remote named origin
([email protected]:phongvcao/<Project_Name>.git) into my <Project_Name>s Git repo.

11.4. In order to remove a remote, issue the following command:

$ git remote remove <remote_name>

As you can see in the above screenshot, I removed the remote named phongvcao
while keeping the origin remote.

12: Git Commit & Git Push Commands

NOTE: Before being able to apply any of these commands, you must first issue cd into
the project folder (or getting inside the project folder using command-line) or any of its
sub-folder using the following command:
$ cd <path/to/project/folder>

18

12.1. Add a changed file to a Git commit:

$ git add <path/to/file>

12.2. Remove a file (or a folder and all of its sub-folder) from a Git commit (without
deleting it from the local filesystem):
$ git rm -rf --cached <path/to/file/or/folder>

As you can see in the above screenshot, the file LICENSE was removed from the Git
commit record, yet still existing in the local file system.

12.3. Remove a file (or a folder and all of its sub-folder) from a Git commit (and also
delete it from the local filesystem):
$ git rm -rf <path/to/file/or/folder>

19

As you can see from the above screenshot, my deletion of the LICENSE file was
unsuccessful because the LICENSE file was deleted from the Git commit record in the
previous step.

12.4. Add all files in the current project folder (or sub-folder, whatever folder your
command-line client is currently at) to a Git commit (but still keep the deleted files):
$ git add *

12.5. Add all files in the current project folder (or sub-folder, whatever folder your
command-line client is currently at) to a Git commit (but record the deleted files):
$ git add -A

12.6. Create a Git commit:

$ git commit -m Type your commit message here

20

The commit message typically contains the list of all of the changes you made in your
project and what is still left to do.
To enter a newline like in the above screenshot, you have to press <Shift><Enter>.

12.7. Push the Git commit to Bitbucket:

$ git push origin master

12.8. List all the Git commits that you made:

$ git log

The Strings highlighted in Yellow are the Hash Codes of the commits.
The Git commits listed by git log are sorted in reversed chronological order, with the
latest and most recent Git commit on top and the oldest one at the bottom.

12.9. View the current Git commit that you are at:

21

$ git log -n 1

12.10. Switch between Git commits:

$ git reset --hard <the_first_6_letters_of_the_Git_commits_Hash_Code>

22

As you can see in the above screenshot, I switched from my current Git commit which
is 051f1d to the first initial Git commit which is afd3f3.

12.11. Edit a Git commit message (in an external editor):

$ git commit --amend

23

Note: Before issuing this command, make sure that the core.editor variable of your Git
global settings has been set to your favorite text editor (see Step 3.2 above) by issuing
the following command:
$ git config core.editor

24

If your Git commit global editor is not yet set, you can set it using the following
command (mentioned in Step 3.2):
$ git config --global core.editor <Your Text Editor of Choice>

12.12. Replace a Git commit message:

$ git commit --amend -m <New Commit Message>

13. Git branch commands

Now that youve learned about Git branches fundamentals, lets look at the concrete
examples and commands used to manipulate Git branches.
13.1. List all Git branches:
$ git branch -v

25

The branch marked with the * character is your current branch

13.2. Create a new Git branch:

$ git branch <newBranchName_authorBitbucketUsername>

As you can see in the above screenshot, the new_feature1 branch has been
successfully created.
As a convention when you create a new branch please indicates your Bitbucket
username in the name of the branch, separated by underscore _ so we know who is
mainly responsible for working on this particular branch.
Also note that when you create a new Git branch, your Git HEAD pointer is still pointing
to the branch youre currently at. You have to explicitly issue a Git switch (Git checkout)
command to switch to the new Git branch you just created.

13.3. Switch to another Git branch:

$ git checkout <branch_name>

26

As you can see in the above screenshot, the * character first highlighted the master
branch. Then after the command is issue the * character highlighted the new_feature1
branch.

13.4. Create and switch to a new Git branch (at once):

$ git checkout -b <new_branch_name>

As you can see in the above screenshot, the * character first highlighted the
new_feature1 branch. Then after the command is issue the * character highlighted the
newly-created new_feature2 branch.

13.5. Merge your Git branch with another branch:

In order to merge your current Git branch to another branch (for example, the master
branch), you have to first switch to the branch that is more stable using git checkout.
Then you can issue the following command to merge your current more-stable branch to
another less-stable branch:
$ git checkout <more_stable_branch>

27

$ git merge <less_stable_branch>

As you can see in the above screenshot, I first checkout the master branch which is
more stable than new_feature1. After that, I merge the master branch with the
new_feature1 branch.

13.6. List all Git branches that WERE merged to your current branch:
$ git branch --merged

13.7. List all Git branches that WERE NOT merged to your current branch:
$ git branch --no-merged

28

13.8. Delete a local Git branch

$ git branch -d <branch_name>

After this command is executed, the branch <branch_name> is deleted from the local
repository on your computer. However, if youve already pushed this <branch_name> to
Bitbucket, the branch <branch_name> still exists online on Bitbucket.

13.9. Push a local Git branch to Bitbucket:

To push a local branch to Bitbucket, issue the following command:
$ git push <remote_name> <branch_name>

13.10. Delete a remote Git branch:

29

As you can see in the preceding section, the git branch -d command only deletes the
local <branch_name> branch on your computer. When you do a Git commit again and
issue a Git push, the remote <branch_name> branch hosted on Bitbucket will not get
deleted. To also delete the remote <branch_name> branch, issue the following
command:
$ git push --delete <branch_name>

14. Update (Synchronize) local fork with the original repository

14.1. Here are the commands to update (synchronize) your fork with the *original*
<Project_Name> repository:
$ git remote add <a_name_for_<Project_Name>_original_remote>
<original_<Project_Name>_remote_url>
$ git fetch <a_name_for_<Project_Name>_original_remote>
$ git checkout master
$ git merge <a_name_for_<Project_Name>_original_remote>/master

30

As you can see in the above screenshot, I name the official, **original** <Project_Name>
remote main (so basically I replaced <a_name_for_<Project_Name>_original_remote>
with main and <original_<Project_Name>_remote_url> with
[email protected]:<Team_Name>/<Project_Name>.git which is the URL to the official,
**original** <Project_Name> remote on Bitbucket.
After this, you can do a $ git push origin master normally to push your newly-updated
local <Project_Name> fork to the <Project_Name> fork repository on your Bitbucket
account.

15. Create a Pull Request

15.1. After youve confirmed the stability of the changes you made, head over to your
Bitbucket account and go to the homepage of your <Project_Name> fork repository:

15.2. After getting into your <Project_Name> fork repository on Bitbucket, expand the
Bitbuckets left Sidebar (see Step 7.2). Click on the option called Create a Pull
Request, which will lead you to the Create Pull Request page:

15.3. On the Create a Pull Request page, make sure that the Git branches and Git
repositories information are correct (meaning they are what you want to merge):

31

When youre done reviewing, click on Create pull request button to start the Pulling
process from the team members <Project_Name> fork repository to the official,
**original** <Project_Name> repository.

16. (For Administrators) Merge the Pull Requests

16.1. Click on the Pull Request section on the left sidebar of Bitbucket, which leads to a
page showing all recent Pull Request created by team members.

32

16.2. Click on a Pull Request. Edit anything if needed, and when youre done please
click on Approve and then Merge to start the Merging process:

16.3. Now youll be presented a Merge dialog. Just click on Merge to finish the Merging
process:

16.4. Youre now finished! The team members <Project_Name> fork repository has
been successfully merged to the official, **original** <Project_Name> repo on Bitbucket.
You should now notify other team members about the Merge so they know to update
their local <Project_Name> fork repositories accordingly (see Step 14):

33

34

17. References
1. "Bitbucket Documentation." Atlassian Documentation. Atlanssian, 9 Jan. 2014. Web.
31 Oct. 2014. <https://confluence.atlassian.com/display/BITBUCKET/Bitbucket
Documentation Home>.
2. Chacon, Scott. Pro Git. 1st ed. Apress, 2009. 1-288. Print.

35