Git/Github Tutorial

Version control is a system that helps you track and manage changes to your work over time. Whether you're writing documents (such as LaTeX, plain text, or Markdown) or developing code, version control allows you to save different versions of your project, making it easy to revert to an earlier state if needed. This means you can experiment freely, knowing you won’t lose progress if something goes wrong.

One of the most widely used version control systems is Git. Git keeps track of changes in your project, allowing you to create snapshots (called commits) of your work at different points in time. This makes it easy to undo changes, collaborate with others, and maintain a history of your progress.

While Git is the tool used to manage versions of your files locally on your computer, GitHub is an online platform that hosts Git repositories in the cloud. By storing your projects (repositories) on GitHub, you can:

Access your work from anywhere
Share your projects with others
Collaborate with teammates in real time Git is primarily used through the command line, while GitHub offers a web-based interface for repository management, reviewing changes, and collaboration.

Setting up Git to work with GitHub

Creating a GitHub Account

You can create a GitHub account using your e-mail address and a password of your choosing. If you are using your Davidson e-mail, try to choose a password different than your e-mail password. You will also enter a username of your choosing, which can be used by others to find your profile on GitHub.

Setting Up Git Config

If it is your first time connecting to a research cluster node, it is best to set up your git credentials for your user. Whenever you run a git command, your system will associate it with your GitHub account.

git config --global user.name [GitHub username]  
git config --global user.email [GitHub e-mail address]

Note

You can check your Git configuration file using the cat ~/.gitconfig command.

Example

Once you entered your information, your config file may look like this:

[user]  
name = AndrewScott  
email = anscott@davidson.edu

Connecting to GitHub

SSH (Secure Shell) keys allow you to securely connect to GitHub without needing to enter your username and password every time. First, check if you have created a pair of SSH keys before by running the ls -al ~/.ssh command. If you receive a "No such file or directory" message, proceed to the Generating SHH Keys section. If you already have files named "id_ed25519" and "id_ed25519.pub", then check the contents of these files to see if you have an ssh-key generated associated with your GitHub e-mail address (refer to Entering SSH Keys to GitHub section for an example).

Generating SSH Keys

You can generate a new SSH Key by using ssh-keygen -t ed25519 -C "[GitHub e-mail address]" command.

Example

ssh-keygen -t ed25519 -C "anscott@davidson.edu"

Once you entered the command, you will be prompted with the following questions:

Example

Enter file in which to save the key (/home/DAVIDSON/anscott/.ssh/id_ed25519):  
Created directory '/home/DAVIDSON/anscott/.ssh'.  
Enter passphrase (empty for no passphrase):  
Enter same passphrase again:

You may press "Enter" for each of the prompts. Once the last prompt is answered, you may see an output similar to the following:

Example

Your identification has been saved in /home/DAVIDSON/anscott/.ssh/id_ed25519.  
Your public key has been saved in /home/DAVIDSON/anscott/.ssh/id_ed25519.pub.  
The key fingerprint is:  
SHA256:TIYH9XHaEtmfWWZ6K/9JZZdCnjd8gTPAFuYTmsMeVik anscott@davidson.edu  
The key's randomart image is:  
+--[ED25519 256]--+  
|      ... +O+    |  
|       o.EB=+ . +|  
|      . +B*o.* O |  
|       =o o=+ X +|  
|        S.   - **|  
|             .oo=|  
|              o. |  
|              ...|  
|               .o|  
+----[SHA256]-----+

Entering SSH Keys to GitHub

To associate the SSH Keys with the GitHub account, open up a browser log in to your GitHub account and navigate to Settings. In the left sidebar, click on SSH and GPG keys, and then click the New SSH key button. First, give your key a descriptive title (e.g., "compute0 access"). Then, paste the output into the "Key" field cat ~/.ssh/id_ed25519.pub command. Then, click Add SSH key to complete the process.

Example

The output of cat ~/.ssh/id_ed25519.pub command may look like this:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AFFAINEUXKjXifc2rFMIwl54TUcokiOaPpowft7m42b9ccUY anscott@davidson.edu

Ensure the email in the .pub file matches your GitHub account.
You may have more ssh-keys listed in this file, you only need to copy one of them to add a SSH key to your GitHub account.

Creating a GitHub Repository

Projects in GitHub are called repositories, and you can create a GitHub repository from the main page of GitHub. Once you are logged in, in the left sidebar, you can click on the new green button to create a new repository. This will direct you to Create a new repository page.

On this page, select the repository owner from a dropdown menu and a repository name. After that, you may provide a brief description on what this repository entails in the Description section, and opt in to create a README.md file to describe your project. You can edit this file after you create the repository. Lastly, you need to choose if you want this repository to be public or private. A public repository is visible to everyone, and private repository is only visible to you by default. In both private and public repositories, you can add other users to make edits to the project later.

Example

Owner: AndrewScott
Repository Name: Psychedelic Drugs Testing
Description: A list of resources on how to process the contents of the drugs
Private Repository

Note

Most of the time a README.md file includes how to run the code in a repository and more detailed information regarding the content of the repository.

Cloning a GitHub Repository

To access a GitHub repository from your research cluster node, you can clone your repository. This will copy everything you have on a repository to a folder in your current directory.

Cloning a repository requires retrieval of the repository link. This can be found in the GitHub repository page by clicking on the green Code button. This will display a modal with three methods to clone the repository. The default one is HTTPS, and you need to select the SSH option. Then, you can copy the repository link.

Example

The HTTPS and SSH repository links will look something like this:
HTTPS: https://github.com/[username]/[repository name].git
SSH: git@github.com:[username]/[repository name].git

With the repository link, you can use the git clone [repository link] command to create a copy of the repository in your current directory.

Note

If you used the HTTPS link to clone a repository, you can remove the repository folder completely from your directory and then clone with SSH link again.

You can read about how to clone repositories with HTTPS and SSH if you want to try a different method.

Git Add-Commit-Push Flow

Once you are in the cloned repository folder, you can make changes to any file or folder inside it. When you are done with your changes and would like to save them, you can use the Add-Commit-Push flow. This flow includes using git add, git commit, and git push commands.

Before we go over each of these commands, it's a good idea to retrieve and check the repository's current status of the repository using the git remote update and git status command. The first command will retrieve all of the changes made by others, and the second command can show you whether your current state of your repository is the most updated.

Example

After running git status, you may see an output like this if your repository is up to date with latest changes.

On branch main
Your branch is up to date with 'origin/main'.
(...)

If there was a change, the output may look like the following:

Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
(use "git pull" to update your local branch)

If your repository is not up to date with the latest changes (this may be because someone else made changes to the repository), you may have to resolve merge conflicts.

Once you know it is safe to move on with the Add-Commit-Push workflow, change your current directory to the top directory of your repository.

git add . This command will record every change you made in the repository folder since the last time you completed the Add-Commit-Push flow.

git commit -m "[commit message]" Once you recorded every change, you must give a log message describing the changes for the new changes. Ensure your commit message is meaningful and clearly describes what was changed/added/removed from the project (while respecting to the 72 character limit).

Example

git commit -m "Added comments to training.py"
git commit -m "Removed bug #12 - refer to meeting notes"

git push The last leg of the flow is synchronizing the changes with the repository to allow changes to be seen by everyone else.

Best Practices

You can change the a repository from private to public, or public to private anytime.
If you have confidential or large sized files, you can create a .gitignore file in your repository's top folder to ignore these files from being uploaded.
When collaborating with multiple people, it is best to work on different branches. This will help you avoid merge conflicts.