MDAG workshop: Part 4c
Git and GitHub

Author

J Nienkemper-Swanepoel

Background

  • Part 4 of the MDAG workshop will show you how to create a website using Quarto and GitHub with no knowledge of Git.
  • However, in the long run it would greatly benefit your workflow to acquire skills in Git.
  • Git and GitHub are crucial for collaborative projects.
  • This document is a first step to your future with Git and GitHub.
  • The steps are easy to follow and will definitely be worth it in the end.
  • We encourage you to give this a try!!

Installing Git

The Bash shell is the preferred way to communicate between Git and GitHub.
In computing, bash refers to a program that allows command-line interface. Therefore, Git-bash provides a command-line environment to submit documents and projects to GitHub (more information on this later).

  • You will have to install: Git
    • For MacOS: You do not have to install anything, Bash is available from the Terminal (/Applications/Utilities).
    • For Linux: Git is possibly already available, if not install via your distro’s package manager. For Debian/Ubuntu run sudo apt-get install git and for Fedora run sudo dnf install git. For more information: Carpentries website
    • For Windows: Git Bash is preferred. Download this from git for windows. The carpentries website provides complete Shell installation instructions and a video tutorial. FOLLOW ALL THESE STEPS DILIGENTLY, accept for Step 2.2 where you may select a text editor you are familiar with.

      Once installed, Git bash will be available in your programme list:

When you open this application a similar screen will appear:

Now, you will have to configure git the first time it is used on a computer. This will include configuring:

  • your username and email address (same address as your GitHub account)

  • specifying your preferred text editor (this is very useful when you run into conflicts with different versions of your documents)

  • set the settings to be used globally (i.e. for all projects).

Type the following in Git Bash:

  • Change your name and surname and press enter: git config --global user.name "Your name and surname"
  • Change your email address to the GitHub account email address and press enter: git config --global user.email "email@domain"

Further reading: Software Carpentry: Version Control with Git

Setting up your working directory

  • Decide where you are going to save your repositories / folders locally. I have a dedicated ‘Repositories’ folder under ‘Documents’. This destination is entirely up to you, just ensure you know where to find it again.

Workshop specific steps

At this stage it is assumed that the Git and GitHub steps have been completed. If you have already created the copy of the template as explained in Part 4b, you can skip step 1 to 3.

  • Step 1: Sign into your GitHub account.

  • Step 2: Search for the MDAG workshop website template. Click on Use this template and Create a new repository:



  • Step 3: Specify a repository name and Create repository:



You will have to keep the visibility of the repository Public for the website to render.
You will see the following screen once you have selected Create repository.



  • Step 4: Click on Code and under the HTTPS panel click Copy url to clipboard.



  • Step 5: Open RStudio.

  • Step 6: Create a New Project.



  • Step 7: Select Version Control:



  • Step 8: Select Git:



  • Step 9: Paste the url you have copied in Step 4. Typically, the project directory name will automatically be filled in, but if this does not happen you can type the name of the GitHub repository you have specified. Change the subdirectory to the working directory you have created for repositories (eg. …Documents > Repositories).
     

  • Step 10: To practice the commit procedure, make a small change to the README.md file. For example:



  • Step 11: Commit this change by selecting Git in the Environment / History window. Select the file that has been changed (for this example, only README.md) and click on commit.
     

  • Step 12: A window will open to allow a message to be added. Be concise and descriptive as this could be useful to keep track of future changes.



  • Step 13: Close the Git Commit window:
     

  • Step 14: Click push to sync these changes with the online GitHub version.



  • Step 15: If this is your first time using GitHub, you will be asked to Connect to GitHub since you have to setup a secure shell (SSH). You will only have to do this once. More information on SSH.



  • Step 16: Once you are signed in to your account, navigate towards your repository copy of the createQuarto_website template. If you see the following by selecting Code and SSH, you will have to add a public key by following steps 17 to 22.



  • Step 17: Select SSH and GPG keys under your profile settings and click on New SSH key.

  • Step 18: Now open Git Bash and type the following by only changing your account email address and press Enter: ssh-keygen -t ed25519 -C "mymail@emaildomain.com"


 This will generate a key and it will disclose the destination of these files in the terminal (see an example below):

  • Step 19: Navigate towards the destination where the key is saved. There will be two documents that can be opened by selecting a text editor when clicking Open with. The two documents contain different information, you require the document that contains information that starts with ‘ssh-ed25519’ and ends with your account email address. Copy this and open the browser with GitHub again.

  • Step 20: Add a Title for your key (this can be anything) and paste the information in the Key text box. Finally, click Add SSH key.

  • Step 21: This will ask you for a Git authorisation. Click on Git Credential Manage by Git Ecosystem followed by Authorize git-ecosystem.

  • Step 22: This should be quickly followed by a successful authentication:

  • Step 23: Now, back to RStudio, you can attempt to push the changes again and should be followed by a similar message box:

  • Step 24: Refresh your browser where GitHub is open. You should see the commit message next to your README.md file:

Working in Git Bash / terminal

  • Using RStudio for version control is typically easier when you are starting out.

  • However, if you expand your projects beyond R, it would be useful to familiarise yourself with Git.

Open Git Bash and change the current directory to your Repositories folder by using cd space followed by the path.



  • Press enter. The current directory should now point towards the Repositories folder:

  • You can now use commands such as git status, git pull, git add, git commit -m "message" andgit push.

  • Git functionalities are beyond the scope of this workshop, please refer to the following useful resources for further reading: