Git / GitHub info

GitHub handles accounts and organizations separately, this means you can use your existing GitHub accounts to access our repositories. There’s no need to create a new account if you already have one. We can give your existing account membership to our organization.

Git overview

First let’s clarify some software and their roles (colours relate to the diagram below):

  • GitHub: Is a platform for storing version controlled code. TAU’s GitHub is managed by ITB under TMR’s enterprise GitHub.

  • PyCharm / VSCode: These are IDEs you’re using to write code in a workspace (which remains “staged” there until you commit it to your local repository)

  • Git: Is the software that handles the version controlling of your code and acts as the communication interface between your IDE and GitLab.

Now for some Git terminology and how these features interact:

  • Clone/pull: Clone/pull a project (set of code) from a remote repository to your workspace (local)

  • Branch: All code has a “main” (sometimes called “master”) branch. The main branch contains the latest working version of all code. You will probably have cloned this branch (although you can clone others). Now you want to start making some changes so you will create a branch of your own, which is a point-in-time deviation from the main branch.

  • Commit: You’re now working on the branch you created making changes that won’t impact the main branch. Well done, this is good practice. As you make changes in an IDE they’re probably being saved automatically, but when you reach particular milestones you may want to commit those changes. Think of this as a hard save so you have a marker in time that you can go back to. But commits are still only local.

  • Push: Because you live in fear of losing your work that was not backed up, at the end of each day you make a habit of pushing your code to the remote repository to back it up and let others see where you’re up to. When you push whilst on a branch, you’re still not messing with the main branch, you’re now putting your branch in the remote repository and pushing to that. No harm done!

  • Merge: You’ve now made all the changes you want to make on that branch and you’re ready to merge it into the main branch. To do this you create a merge request. The maintainer of your repository can talk you through protocols around this as they may vary from project to project.

The below diagram outlines how these actions relate to one another as well as some additional actions.

../_images/git_flow.png

For those within TMR, you can listen to our GitHub training videos for more information.

Watch ‘Git Fundamentals - Session 1 of 2’ | Microsoft Stream (Classic) Watch ‘Git Fundamentals - Session 2 of 2’ | Microsoft Stream (Classic)

Installing Git on your PC

Most TAU projects are now hosted on GitHub and requires git to be installed on your machine.

For TMR staff, the best way to do this is to place a SCO request for Git / GitHub access. The packaged installer will deal with some TMR environment specific challenges.

For external staff, consult your IT department or download and install from here.

Once you have done the installation, open git bash and run the following:

git config --global user.name "your name here"
git config --global user.email email@domain

Do the following if you need to add proxy settings.

git config --global http.proxy http://user:password@www-proxy.qdot.qld.gov.au:8080
git config --global https.proxy https://user:password@www-proxy.qdot.qld.gov.au:8080
git config --global credential.useHttpPath true

Remember to change proxy string as per your organization if you are not using this from TMR’s network.

This completes setup for git on your machine.

Once you are done with this stuff please head over to the Setting up two-factor authentication in GitLab

Setting up two-factor authentication in GitLab

Login to your account here [https://github.com]

If you don’t have an account, you can make one here.

Once you login to your account, make sure you setup Two Factor Authentication in settings.

Keep in mind to save the backup codes somewhere safe in case you loose your device.

Using Git in PyCharm

To clone a project from GitHub in PyCharm follow these steps (assuming you have done the setup as per the above installation guide):

  1. In GitHub (via web browser) navigate to the repository, click the green Code button and then copy the URL shown.

  2. Open PyCharm (if you have a project already open, close it) and select Get From Version Control

  3. Paste your clone URL from step 1 into the URL field in PyCharm

  4. (optional) Change the directory where you want to set up your local repository

  5. You will be asked to Log in via GitHub or Use Token. Select Log in via GitHub.

  6. Click through the relevant screens to authorise JetBrains to access GitHub; you may need to click the blue request button next to the TAU organisation when you get to the GitHub authorisation screen.

If the authorisation has worked, PyCharm will start cloning your repository and open it as a new PyCharm project. If Step 6 from above doesn’t allow you to authorize Github in PyCharm or if you get some SSH/proxy sounding error, there’s an alternative method to access the repository:

  1. Create a personal access token (Creating a personal access token - GitHub Docs). Important to save this token somewhere safe.

  2. Authorize token to access tmr-tau team (Authorizing a personal access token for use with SAML single sign-on - GitHub Docs)

  3. In GitHub (via web browser) navigate to the repository, click the green Code button and then copy the URL shown.

  4. Open PyCharm (if you have a project already open, close it) and select Get From Version Control

  5. Paste your clone URL from step 3 into the URL field in PyCharm

  6. (optional) Change the directory where you want to set up your local repository

  7. You will be asked to Log in via GitHub or Use Token. Select Use Token.

  8. Insert token when asked.

Navigation between branches and creation of new branches can all be done via your repository menu in the bottom right (it will likely say master after cloning). To create a new branch follow these steps:

  1. Click on master in the bottom right

  2. Click + New branch

  3. Give your new branch a name that follows the naming protocol used in this project (usually username/task_youre_working_on)

  4. Click OK (leaving the checkout branch option ticked will switch you onto this branch and off master)