Using Git and GitHub

This document provides a workflow for creating and contributing to a new GitHub repository, specifically a repository in the NC State Libraries Data & Vis Organization, using the Git command line tool or the application GitHub Desktop.

Requirements

• A GitHub account (If you do not have an account, create one through the join GitHub page).
• Membership to the NC State Libraries Data & Vis Organization (Email Joddy or Shannon to receive an invitation).
• Git (Git Download page) OR GitHub Desktop (GitHub Desktop download page).
• Setting up a personal access token (PAT) for authentication and login (Creating a personal access token).

Step 1: Create a new repository on GitHub

The following instructions walk through the process of creating a new GitHub repository in the NC State Libraries Data & Vis Organization. If you want to contribute to an existing repository you can skip to Step 2a, or Step 2b for instructions on using Git in the terminal or GitHub Desktop.

1. In a browser, navigate to the NC State Libraries Data & Vis Organization.

2. Click the button labeled New in the upper-right corner.

3. On the Create a new repository page the default owner should be set to ncsu-libraries-data-vis.

4. Create a new repository name:

   1. The name should be short (approximately five words or less) and descriptive.

   2. Separate each word with a dash (-).

      For example:

      The workshop "An Introduction to Programming with Python" has the repository name introduction-to-programming-with-python.

5. Add a short description of the repository (approximately one to two sentences).

   For example:

   The workshop "An Introduction to Programming with Python" has the description These materials introduce fundamental concepts of programming through the Python programming language.

6. In most cases, the repository should be set to public–anyone on the internet can see the repository but cannot automatically commit.

7. Initialize the new repository with:

   1. A README file (This file will eventually contain an in depth description of the repository materials.)

   2. If the repository will consist of software, a License file (From the license options select MIT License. The copyright attribution on line 3 of this file, Copyright (c) 2021 NC State Libraries Data & Vis, should eventually be edited to: Copyright (c) 2021 NC State University)

      If the new repository will consist of instructional materials, skip creating a LICENSE file. Instead, manually create a LICENSE file and add copy the Creative Commons Attribution 4.0 International license language contained in the LICENSE file within this repository.

   3. If using a specific language/tool, a .gitignore file using the appropriate provided template.

      For example:

      The workshop "An Introduction to Programming with Python" uses the Python template.

      If there is not an appropriate template for the new repository, skip creating a .gitignore file. A .gitignore files should eventually be created in the root folder of the repository. A good base .gitignore configuration example is available in "Some common .gitignore configurations". You can also explore this collection of .gitignore templates for a relevant template for your materials (e.g., there is a template for Microsoft Office for PowerPoint, Excel, etc.).

8. Click the button labeled Create repository

Step 2a: Using Git from the terminal

Step 2b: Using GitHub Desktop

Adding new materials

1. In Github, navigate to your repository.
2. Click on the green "Code" button in the top right.
3. Select "Open with GitHub Desktop."
4. In the GitHub Desktop app, select a local path.

   You are creating a copy of the repository on your machine to edit, so choose a local path that makes sense for you (for example: a folder that stores all of your GitHub repositories).

5. Click the blue "Clone" button.
6. Access the instruction materials on your computer.

   If you are transferring materials from a shared Drive, this may mean downloading the entire folder for the workshop materials and unzipping them.

7. Move the folder of downloaded materials into the folder you chose earlier for your local path. This will move the materials into your local copy of the repository.
8. In GitHub desktop, you should now see in the left pane that there are changed files (the ones you just moved).
9. Commit to the main branch
   1. At the bottom left, write a short title for your commit and an optional description.
   2. Click on the blue "Commit to main" button
10. Push commits to the origin.
    1. At the top toolbar, the right-most box should now give you the option to "Push origin," click on that box to push.
    2. Alternatively, in the right pane, you should now see the option to push commits to the origin remote.
11. Click the blue "Push origin" button.

Editing existing materials

1. Before editing, fetch the most recent changes and check to make sure you are in the right branch.
   1. Check your branch and create new branches in the middle dropdown of the UI called "Cuurent branch."
   2. Click the rightmost box in the top toolbar that says "Fetch origin"

   This will make your local copy match the one in the GitHub repository. If you have changes that you have not pushed, this may cause a conflict.

2. Make your edits as usual and save to the same file.
3. In GitHub desktop, you should now see in the left pane that there are changed files (the ones you just moved).
4. Commit to the main branch
   1. At the bottom left, write a short title for your commit and an optional description.
   2. Click on the blue "Commit to main" button
5. Push commits to the origin.
   1. At the top toolbar, the right-most box should now give you the option to "Push origin," click on that box to push.
   2. Alternatively, in the right pane, you should now see the option to push commits to the origin remote.
6. Click the blue "Push origin" button.