AMT Data Management

Contents

What is Git

Git allows you to version control your code. This code will be stored in a git repository. On your device, this will look like a folder than contains your project.

With git, you can:

  • Back up your code
  • Get your code on any device and sync changes
  • Pull in other changes that other people have made to a piece of code
  • Track the history of changes to code - and revert to previous version if needed

How is Git used

Starting a Project

You can create a project that uses git by making a folder for your project, and running the command git init in your terminal within this folder. You will then be able to track changes made in this folder with git.

If you are unsure how to access the location you want through the terminal, you can right click the folder you want to access through file explorer and choose the "open in terminal option". This will open your terminal in the right location for you to run the terminal commands. If you need to move to a subfolder with cd foldername and move to the parent folder with cd ..

GitHub

Using GitHub requires making an account. Find details on accessing the AMT GitHub group here

Git repositories can hosted on sites like GitHub. On the GitHub website you will find a project page for each repository hosted there. The repository on the GitHub website is know as a remote repository, which means that it is hosted on a server accessible to others. You can access the code in this repository on your device by running git clone CLONE_ID - where CLONE_ID is a specific address that can be found on the project page - in the location you would like to store the code. The version of the repository that you have cloned to your device is know as a local repository, as it can only be accessed locally.

Making Changes to Code

Before you make any changes, make sure your local code is up to date with the remote repository. Run git pull to do this.

You can make changes to the code in the local repository on your machine in the same way you would edit any other code. You will then have to "add" these changes to a staging area by running git add filename, where filename is the path to the file you have changed. You can check what files you need to add by using the git status command, and git add . to add all the files.

After you have added all your files, you need to add a message explaining the changes you have made. Run git commit -m "message here" with your own message. This command will apply to all the files you have added.

These changes are currently only available to you locally. You can apply these changes to the remote repository by using the git push command. Afterwards, your changes should be available in the remote repository.

Getting Changes from a Remote Repository

Changes pushed from one local repository are not automatically applied to any other existing local repositories. If somebody else is working on code from the same remote repository, or you are working on a different device, you will have to ask git to get the changes yourself. You can get and apply the changes to your local repository by using the git pull command.

You should run this command before you make and push changes to ensure that your local branch is up to date and you do not introduce any conflicts.

Typical Workflow (No Branches)

Only use this workflow if you are not using branches. See below for a workflow example with branches

So a typical git workflow from your local code would be something like:

  • Check for and apply any changes that have been made to the remote repository
  • Add the files that you have made changes to the staging area
  • Add a commit message explainging the changes you have made
  • Push the changes to the remote repository

Or, translated into commands:

  • git pull
  • git add filename
  • git commit -m "my commit message"
  • git push

Working With Others: Branches

Branches

If there is more than one person working in a repository, it is common that each person works on their own branch. This means, if you were to make and push changes, the other person will not get the changes you have made unless they choose to merge your changes into their own branch. This means you can safetly push changes without conflicting with the other person's work.

Typically, there will be a main branch from which the other branches will stem from. Once you are satisfied with the changes you have made to your branch, you can merge your changes to the main branch. Everyone else working on the repository will then be able to git pull these changes from the main branch, and merge them into their own.

Branch Commands

To see what branch you are currently working on, use the git branch command. You can switch to another existing branch with git switch branchname. To make a new branch, use git switch -c branchname.

To apply the changes you have made to another branch, switch to the branch you want to apply your changes to, and then use git merge branchname, where branchname is the name of the branch that you have made your changes to.

Typical Workflow (With Branches)

If you are working on your own branch, your workflow will be something like this:

  • Check for and apply any changes that have been made to the remote main repository
  • Apply the changes made to the main branch to your own branch
  • Add the files that you have made changes to on your own branch to the staging area
  • Add a commit message explainging the changes you have made
  • Push the changes to the remote repository
  • When ready, apply these changes to the main branch
  • Push the changes to the remote main repository

Or, translated into commands:

  • git switch your-branch-name
  • git pull
  • git merge main
  • git add filename
  • git commit -m "my commit message"
  • git switch main
  • git merge you-branch-name
  • git push

Additional Settings

SSH Keys

You may need to connect to GitHub repositories with SSH. In this case, you will need to set up an SSH key to connect with.

First, you should check if you have any existing SSH keys. You can do this by running the following commands to list any files in your .ssh directory:

ls -al ~/.ssh

Windows ls -al ~/.ssh
Mac ls -al ~/.ssh

If you need to generate generate an SSH key, run the following command and replace your_email@example.com with the email associated with your GitHub account:

ssh-keygen -t ed25519 -C "your_email@example.com"

Windows ssh-keygen -t ed25519 -C "your_email@example.com"
Mac ssh-keygen -t ed25519 -C "your_email@example.com"

You will be prompted with Enter file in which to save the key, for which you can press enter to accept the default location. You will also be prompted choose a passphrase. Press enter if you do not want a passphrase.

You must now add your pubic key to your GitHub account. Copy the contents of the .pub file generated. With a public file named id_ed25519.pub, you could do this with the following command:

cat ~/.ssh/id_ed25519.pub

Windows clip < ~/.ssh/id_ed25519.pub
Mac pbcopy < ~/.ssh/id_ed25519.pub

Now, on your GitHub account, go to Settings > SSH and GPG keys and click New SSH key. Paste the .pub file contents in the Key box, give it a title, and save. You should now be able to connect to repositories via SSH.