Installing and setup Git

Overview

Questions Objectives
How do I get set up to use Git? Configure git the first time it is used on a computer.
Understand the basics of how automated version control systems work

When we use Git on a new computer for the first time, we need to configure a few things. Below are a few examples of configurations we will set as we get started with Git:

  • our name and email address,
  • what our preferred text editor is,
  • and that we want to use these settings globally (i.e. for every project).

Verify the installation of Git on your computer

You first want to double-check if Git is already installed on your computer.

Go to your terminal and enter which git to request the path to your Git executable:

which git
## /usr/local/bin/git

and then git --version to see its version:

git --version
## git version 2.31.1

If the terminal returns a path and version, that means you have Git and you can skip this installation step! That being said, you might want to ensure your Git is the latest version.

If you don’t see a path and version, but something like git: command not found - then you definitely need to continue with installation.

Install Git on a Utrecht University laptop

If you use a laptop from Utrecht University, you can install git from the Software Center.

Install git on a Personal laptop

Follow the the instructions relevant to your operating system.

  • Windows: Go to gitforwindows.org. Make sure you include Git Bash in your installation!

  • Mac: Go to git-scm.com and install the the latest version available.

  • Linux: Go the Linux-specific page of git-scm.com. There are commands specific to various package managers.

Configure Git

On a command line, Git commands are written as git verb options, where verb is what we actually want to do and options is additional optional information which may be needed for the verb. So here is how a user called Alfredo sets up his new laptop:

git config --global user.name 'Alfredo Linguini'
git config --global user.email 'alfredo@ratatouille.fr'

This information is used to later connect to GitHub when we want to upload (push) or download (pull) code.

Setup Git for yourself and make sure you use the email associated with your GitHub account!

Now that you configured Git for you, please check whether everything is correct with:

git config --global --list

Set up an SSH key pair

To authenticate with the GitHub server we will set up a so-called SSH key pair

In the following steps, you will generate a private and a public SSH key, that together allow your local computer to interact with projects that are on GitHub. SSH keys provide a more secure way of logging onto servers than relying on passwords alone.

You can think of the public key of an SSH key pair to be the lock which we will add to the GitHub server and the private key as the key, which needs to be placed in a special folder on your computer

Below we summarize the steps we will carry out:

  1. Check for existing SSH keys.
  2. Generate new SSH keys.
  3. Add private key to the ssh-agent.
  4. Add public key to your GitHub/GitLab/BitBucket account.
  5. Test your SSH connection.

These instructions are borrowed heavily from Happy Git with R, GitHub’s user guides, and NLeSC Small Scale Initiative - Introduction to GitVersion Control with Git.

Check for existing SSH key pairs.

Go to your terminal and type the following command to list existing SSH keys:

ls -al ~/.ssh

If you have key pairs already, they may look like the following:

  • id_rsa.pub (public key) & id_rsa (private key)

  • id_ecdsa.pub (public key) & id_ecdsa (private key)

  • id_ed25519.pub (public key) & id_ed25519 (private key)

If you’re happy to stick with your existing keys, then you can jump to step 3 which is about adding the private key to the ssh-agent.

Generate a new SSH key pair

Go to your terminal and type the following command, substituting “USEFUL-LABEL” with something like your GitHub username and/or your device.

ssh-keygen -t ed25519 -C "USEFUL-LABEL"

Accept the proposal to save the key in the default file location. Just press Enter here:

> Enter a file in which to save the key (/Users/you/.ssh/id_ed25519): [Press enter]

If you’re new to setting up SSH keys, then skip the option to enter a passphrase. It’s a best practice, but you can come back to it after the workshop. Just leave the passphrase option empty and press Enter:

> Enter passphrase (empty for no passphrase):

Here’s an example of how it should have played out, if everything went smoothly:

jenny@2015-mbp ~ $ ssh-keygen -t rsa -b 4096 -C "USEFUL-COMMENT"
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/jenny/.ssh/id_rsa):     
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/jenny/.ssh/id_rsa.
Your public key has been saved in /Users/jenny/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:ki0TNHm8qIvpH7/c0qQmdv2xxhYHCwlpn3+rVhKVeDo USEFUL-COMMENT
The key's randomart image is:
+---[RSA 4096]----+
|      o+   . .   |
|     .=.o . +    |
|     ..= + +     |
|      .+* E      |
|     .= So =     |
|    .  +. = +    |
|   o.. = ..* .   |
|  o ++=.o =o.    |
| ..o.++o.=+.     |
+----[SHA256]-----+

Add the private key to the ssh-agent

We will now ‘activate’ your private key. To add your private key to the ssh-agent on your local computer, please follow the steps under Adding your SSH key to the SSH agent.

At the top of the page, be sure to select Linux as the operating system, even if you use Windows or MacOS and type the commands provided in your terminal. We’ve had issues with the instructions for the other operating systems.

Add public key to your GitHub/GitLab/BitBucket account

  • Open your public SSH key (the file ending with .pub) in a text editor and copy the whole key. Make sure to avoid copying any newlines or whitespace.

  • On GitHub, click on your profile picture and go to Settings -> SSH & GPG keys.

  • Click on New SSH key.

  • Paste your public key in the box and give it an informative label, maybe the same as the “USEFUL-LABEL” you used when generating the keys.

  • If you are part of a GitHub organization that requires Single-Sign On (such as the Utrecht University organization), you can also click “Configure SSO” after having created the SSH key. This will make sure you can also use your local computer with git repositories in that organization.

Test your SSH connection

Open your terminal and type in the following command:

ssh -T git@github.com

You may see a warning which includes an RSA key fingerprint. Make sure this fingerprint matches that of GitHub’s, you can double-check that here: GitHub’s SSH key fingerprints

If the fingerprint matches, type yes if you were asked if wanted to continue connecting.

If all goes well, you’ll see something like the following:

> Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Make sure it’s your username that terminal returns!

Troubleshooting

GitHub has a whole page on Troubleshooting SSH. If you run into issues, you should double-check if your errors are covered here.

We have collected some commonly seen errors:

  • You have made the key pair and copied the public key to GitHub, but SSH will not connect. Are you sure that you turned on the agent?

  • You receive an error message like “Error: Permission denied (publickey)”. Follow the link to GitHub guide on this issue.

  • Did you remember to add the public key to GitHub?

  • Did you set up SSH keys, but connect to your GitHub using HTTPS?

    You can check your remote URL by going to terminal and typing:

git remote -v

An SSH remote should like this:

git@github.com:USERNAME/REPOSITORY.git

Whereas a HTTPS remote will look this:

https://github.com/USERNAME/REPOSITORY.git

You can switch between the SSH & HTTPS remotes for your repo using the following command: git remote set-url See GitHub’s user guide on Changing a remote repository’s URL

  • Did you remember to configure Mac OS Sierra or High Sierra to persistently store your passphrase in the keychain?

  • You can run commands like ssh-keygen or eval, but they do not return any information, not even an error message. If you are on Windows and have have Citrix workspace installed, there is a known bug where Citrix interferes with the SSH key generation process.

    • Uninstall Citrix workspace
    • Restart your computer
    • Restart the SSH key generation tutorial.
    • If, after setting up SSH key pairs, you want to reinstall Citrix, be sure to do so via the Microsoft store.

Now you are ready to follow the training section about GitHub.