utoronto-comp-aero - Setup Users on Bitbucket

Click here to return to top level Code Management page.

This page describes the Bitbucket setup procedure for Jetstream code developers. Before you begin the setup procedure, please take a moment to familiarize yourself with the Forking Workflow that is used to manage Jetstream code development. The following instructions assume that you have accepted the invitation to join the Jetstream code repo on Bitbucket and have created a Bitbucket account.

Apply For Academic Licence on Bitbucket

Click here and complete the application

Fork the Official Jetstream Repository

The steps below describe the procedure for creating your personal public Jetstream repository that resides on Bitbucket. Your public repository is how you share your code contributions with the group.

Log into your Bitbucket account from a browser
Navigate to the official Jetstream repository at the following location: https://bitbucket.org/utiascompaero/jetstream
Select "Fork" from the "Actions" list (located down the left-hand side of the browser window). This will bring you to the "Fork utiascompaero/Jetstream" page
Retain all the default settings on the "Fork utiascompaero/Jetstream" page and click the "Fork repository" button

After completing the above steps you should now have a public Jetstream repository located at
https://bitbucket.org/<your_user_name>/jetstream

Set Access Permissions for Your Public Jetstream Repository
The steps below describe the procedure for setting permissions to allow other group members read-only access to your public Jetstream repository.

Log into your Bitbucket account from a browser
Navigate to your personal public Jetstream repository located at: https://bitbucket.org/<your_user_name>/jetstream
Select "Settings" from below the "Navigation" list (located down the left-hand side of the browser window)
Select "Access Management" under the "General" list
Select "Developers" and "Read" from the drop-down lists under the "Groups" heading and click the "Add" button

Set Access Permissions for Your Private Local Jetstream Repository
Your local Jetstream repo on SciNet is your personal development area. This area is typically for code still under development and not ready for public consupmtion. To control what you share with others in the group, restrict access to your local Jetstream repo with the following command:

gpc-f101n084-ib0-$ cd $HOME
gpc-f101n084-ib0-$ chmod -R go-rwx jetstream

To share your code with others, you can push what you want to share to your public repo on Bitbucket. Check here for details on how to do that.

Setup SSH Authentication for Communication with Bitbucket
SSH must be setup before attempting to clone Jetstream to your local machine (In most cases, your local machine will be SciNet). On SciNet you already have a default SSH key pair generated, sitting in ${HOME}/.ssh/, and modifying the default key pair is likely to cause problems, so follow only step 6 described in the Bitbucket SSH tutorial. Steps 1 and 2 give a good overview of SSH and are worth reading for some background info.

Clone Your Public Jetstream Repository To Your Local Machine

The steps below describe the procedure for creating your personal private Jetstream repository that resides on your local machine. This repository serves as your private development area on your local machine.

Log into your Bitbucket account from a browser
Navigate to your personal public Jetstream repository located at: https://bitbucket.org/<your_user_name>/jetstream
Select "Clone" from the "Actions" list (located down the left-hand side of the browser window).
Click on the drop down menu that appears and select "SSH"
Copy the "git clone ..." command
Open a terminal on your local machine and navigate to the location where you want your private Jetstream repository to reside.
If you already have a Jetstream repository on your local machine, rename it to Jetstream_backup. Otherwise, just proceed to step 8
Execute the "git clone ..." command that you copied in step 5

Compile Jetstream On Your Local Machine

To do a fresh install of Jetstream on your local machine execute the following script from your Jetstream repository directory:

$ ./make_jetstream

Develop Code and Share With others

After completing the above steps you should now have a newly created directory on your local machine named "Jetstream" containing your personal private Jetstream repository with one branch named “master”. This is your private development environment. It is recommended that you create working branches in your repository to implement new features. To create and checkout to a new branch use the following command:

$ git checkout -b <branch_with_new_feature>

By default, the "git clone ..." command has created a remote link to your public repository on Bitbucket named “origin”. Code changes made to your local private repository can be shared with others by pushing your local changes to your public Jetstream repository, then notifying others that changes are available on your public Jetstream repository that can be pulled into their local repositories. The following command will push changes from a working branch on your local private repository named <branch_with_new_feature> to your public Jetstream repository:

$ git push origin <branch_with_new_feature>

Create a Link to the Official Jetstream Repository

To obtain important code updates, you need to create a remote link from your local Jetstream repository to the official Jetstream repository. This is accomplished by executing the following command from your private Jetstream repository on your local machine:

!-- "Upstream" is the conventional name given to the official code repository in the Forking Workflow
$ git remote add upstream git@bitbucket.org:utiascompaero/jetstream.git

Code updates from the official Jetstream repository master branch can now be obtained with the following command:

$ git pull upstream master

Pull Branches From an Existing Jetstream Repository

If you already had a Jetstream repository on your local machine, let’s call it your old Jetstream repository, you may want to pull branches from your old Jetstream repository to your new Jetstream repository. The procedure involves creating new branches in your new Jetstream repository and pulling content into them from the corresponding branches in your old Jetstream repository. To do this, execute the following commands from your new Jetstream repository on your local machine:

$ git checkout master
$ git branch <old_branch_name>
$ git checkout <old_branch_name>
$ git pull /path/to/old/Jetstream/repo/ <old_branch_name>

After you have pulled all the branches that you wish to keep from your old Jetstream repository to your new Jetstream repository, you can now continue code development in your new Jetstream repository from where you left off in your old Jetstream repository.