Learning Git: From soup to nuts

This tutorial and sequence of assignments is adapted from newtFire.

Introduction

This course requires all students to learn Git, the field standard for collaborative version control for coding. Git is a powerful tool and knowing how to use it will pay dividends for a wide variety of computing methods even outside this course. However, Git was designed with programmers in mind, which means that it takes some getting used to. If you find the learning curve frustrating at times, do not worry!: you are not alone. By the end of this course, the basic Git workflow will be second nature, and this initial sequence of activities will help you get there.

Because many of the challenges and pitfalls that crop up when getting to know Git are specific to indvidual user experiences, we will not devote much class time to Git. But you can use the Slack channel, comments in your homework submissions, and project group meetings to troubleshoot.

Part I: The Big Picture

This assignment helps orient you to version control systems and how they work. It's the system we use with git and Github for sharing files and the system you'll be using to publish and share your website for this class.

Read the following articles:

  1. About Version Control
  2. A Short History of Git
  3. What is Git?
  4. The Command Line

After reading these brief articles carefully, write a short response paper (by the date indicated on the syllabus, and submitted via Canvas) addressing at least some of the following questions:

Part II: Setting up your Github account

This assignment is straightforward: set up your Github account and cloud service. (We will leave the command line application from which you will normally interact with your account for the next step in this sequence.) To do so, follow these steps.

After you have created your account, submit a comment simply listing your full name to this issue in the course Git repo. Github forums use a format called "Markdown" (which you may have used when texting without even realizing it, for instance *italics* surrounded by asterisks automatically reformatted to italics ). Read the GitHub three-minute guide to Mastering markdown. Then, to complete this assignment, submit a link to your comment via the Canvas assignment, experimenting with Markdown formatting (e.g., formatting your first name in bold and your last name in italics ).

Part III: Setting up Git locally on your own machine

The next step is to install Git tools on your personal computer so that you can interact with the remote repository (the one hosted on the website) from your local repository. This is where you might start to run into some challenges.

To install Git locally, follow the set of instructions that corresponds to your operating system. Note that this will be an "invisible" app / program that you interact with from command line: there is no icon to click on, and it will not appear in your Applications folder.

Common pitfalls at this stage:

Token authorization

Now that you have the application installed on your machine, we need to authorize your machine (home to your local repository) to interact with the remote repository hosted on the Github website. You might assume that you could simply provide the same username and password that you created when you registered for a free Github account (and in the past you indeed you could), but these days Git favors a Token system of authorization because it is more secure. (After all, software developers are using this same infrastructure to develop code worth millions of dollars!) Fortunately, this added step of security is fairly straightforward, and in practice works a bit like a temporary password. (Note that there is another way to authenticate using an SSH key, which you are welcome to use, but we will favor the Token for instructional purposes.)

To set up your Token and link your local repo with your remote repo, follow these steps:

  1. Make a GitHub repo! Go to your GitHub Profile on the web. Click the + sign next to your profile and Create a new repository and give it a name.
  2. Set this repository to be Public (so you can use it to publish your website).
  3. Mark the box to Add a README file. (All github repositories should have a README which describes what they're about, and this gives you a starter file in your repo to work with.)
  4. You don't have to set a license for your code yet, but if you're okay with sharing your code openly with the GitHub community, you could choose Creative Commons Zero v1.0 Universal.
  5. Set up your Personal Access Token and store it on your computer! Read this: https://www.howtogeek.com/devops/how-to-set-up-https-personal-access-tokens-for-github-authentication/ Follow the instructions for your computer (Windows / Linux / Mac) on storing your credentials

To submit this assignment: Upload a screen capture of your new repository with its README file featured to the relevant Canvas assignment.

Part IV: Moment of Truth - interacting with your remote repo from the command line

This is where it all comes together. You are ready for this assignment if you have set up your GitHub account, set up your GitHub personal access token/credential storage, and created a public GitHub repo for yourself with a Readme.md file to start.

First, examine the following videos and slides (created by Elisa Beshero-Bondar) carefully for a general orientation:

Next, follow these steps carefully:

1. Creating your Git directory in an appropriate location

Find the best place on your computer to work on GitHub: Make sure you have just ONE folder ("directory" in computing terminology) where you will store Github repos. Make a directory called github or GitHub in a place on your computer that you can reliably use to find and open files. It needs to be a place that is easy to access when you go to open a file in the oXygen XML Editor.

You can make this directory if you have navigated there in the command line (Git Bash or Terminal) with mkdir github, or you can create it in your Windows File Manager or Mac Finder on your computer. You can then right-click on the directory and open (on Windows) a new Git Bash shell or (on Mac, under Services) a new Terminal here. Use your Git Bash Shell (Windows) or the Terminal (Mac) and practice navigating to this space and getting information with command line codes: cd yourDirectoryName, cd .., ls, pwd.

Note : If the "home" location on your computer is not one you can easily find from your GUI File Manager/ file viewer, it may be easier to right-click and open a Bash shell at a point you can reliably open on your computer to make your GitHub directory.

2. Cloning Time

It's time to clone the GitHub repo you created! (You only need to do this once.) Go on a web browser to your profile on GitHub, look at the code view, and click the green "Code" button to copy your repo's clone address with HTTPS: the address should end with .git.

Next, enter git clone and paste in the address you copied. The command should look something like this: git clone https://github.com/....git (with your full GitHub repo address showing). Press Return on your keyboard. You should then see the repo being cloned to your directory space on your computer.

3. Rinse, Repeat

Okay, let's do that again! This time, clone our class's shared GitHub repo at https://github.com/pickettj/teaching. Be careful! You must clone it inside the GitHub folder, not inside your personal repo! If you clone one repo inside another, the .git files start colliding--it's not healthy. If this happens, delete the repo on the inside. (If this happens and you don't notice for a while, it's probably a good idea to trash the double-nested Repo blunder (and empty the trash)! And clone them again properly. Navigate to the outer GitHub folder you created before you clone.)

Your GitHub folder should now have two directories inside it: GitHub/yourNewRepo and GitHub/teaching. If you do your cloning successfully, when you visit your github or GitHub directory, and enter the ls command you should see your repo, and the introDH-Hub listed.

To complete this assignment: Upload a screen capture of your command shell with you navigated to your github directory to the relevant Canvas assignment showing the results of the ls command.

Part V: The Git Workflow

Once you have your repositories (both personal and project) cloned to your personal computer, your basic Git workflow will look something like this:

  1. git pull to make sure that the code in your local repo has the latest version of the code on the remote repository
  2. git add followed by the file names of all the files you have modified and wish to stage
  3. git commit -m "your message explaining your changes here" to essentially "save" the changes to files that you added in the previous step (though without yet sending them to the remote repo)
  4. git push to send all the changes to the committed files to the remote repo

To complete this assignment, submit a screen capture of your command line as you move through this sequence of steps with a file of your choosing from a repo of your choosing (which can be your project repo.)

Reference

Key Terms for Git