Lab 06: Introducing Github

This lab is a very brief introduction to the Git revision control system. Git is the most powerful and widely-used version control system in the world; it is primarily used by software developers but is enormously useful for any text-based document repository and is increasingly being used by humanists to share their work. You can find git repositories for most of my teaching materials, for instance.

I strongly recommend you follow this lesson up by reading the Git book, especially the first 2 or 3 chapters.

Most people love git once they start to use it, but it can be very frustrating and difficult at the beginning. We’ll go over it once, kind of quickly, then try a real-world example (checking out the next STA).

Pasta-Please

My friend Kate Hudson creted a simple github training exercise last week for some of my other students. It was really fun, so let’s check it out:

  1. Sign Up for a Github Account (or sign in if you already have an account)
  2. Navigate to my fork of the pasta-please repository
  3. Take a quick look at the README. Can you understand it? Maybe we need to add some extra instructions (like, what does npm install -g mean? And where do those emoji come from?) What does the program do, and (if you can get this far) how does it work?
  4. Have you found where the Recipes live?
  5. Add a new recipe from inside Github itself(!) simply by navigating to the right spot and clicking the + button. (see the picture below)
    • Be sure to name the file “some-recipe-name.md” so that everyone knows it’s written in Markdown
    • follow markdown syntax in writing your recipe
    • When you save the file, Github will automatically create a forked repository under your account! Magic.
    github-add-file.png

  6. File a pull request with me by navigating back to the main page of your repository (github.com/your-user-name/pasta-please/) and hitting the Github pull request button: github-pull-request.png

Wow, that was cool, right? And if we get through this fast enough, we can try working from the command line.

  1. Choose an appropriate home for your repo and execute git clone https://github.com/your-user-name/pasta-please.git
  2. Add your directory to atom as a “project directory: github-add-project.png
  3. Install the “git-plus” package in Atom
  4. Create a new file in the appropriate place.
  5. Choose menu item Packages \rarr Git Plus \rarr Add, then Packages \rarr Git Plus \rarr Commit, then Packages \rarr Git Plus \rarr Push

There’s still tons to learn but this is a good start.

Quick Start

Resources

This web page is woefully incomplete! Here are some better resources:

Install Git

If you’re on Mac or Windows, the easiest way to start is to install the Github Desktop client. This will also install the command-line tools you need for our tutorials, while giving you a very pretty GUI interface. You can learn more about the desktop client here (There’s no Linux version, so I don’t use this).

Once you’ve installed Git, let’s execute our first command-line commands. In Mac, open Terminal. In Windows, open Powershell (it comes with Github Desktop). Then type

git config --global user.name "Your Name"

and then:

git config --global user.email youraddress [at] mail [dot] utoronto [dot] ca

This tells git some basic information about you, which it will use later on.

Git “States”

(feel free to skip this if you want to get to the action)

A git repository has three important “areas”, each of which represents a different “state”:

  • Working Directory (Uncommitted)
  • Staging Area (Staged)
  • .git repository (Committed)

When you look at the repository, all you see is the working directory. So, if I want to start a new project, I create an empty directory, say, “Project”. Then I run the command:

git init

This command creates the invisible .git subdirectory, which is the real heart of the repo: it stores all the information about previous and current states of the repository.

Doing and Undoing

Every time you commit your changes in git, git saves a snapshot of the working directory to the .git repository. So, in principle, you can get back to any earlier working state of the repository, which is awesome.

commit
the most elementary operation in git is “committing”; this saves your working directory to the repository. Here are the steps

  • make some changes
  • commit them with git commit -a -m Message
checkout
To inspect some other state of the repository, you will need to “checkout” that state: git checkout HEAD~3 will checkout the version you were working on 3 saves ago, for instance.

Branching

Sometimes you want to be able to come back to a particular revision – maybe you have everything working fine, and you want to be sure you can get back to the working state. Maybe you create an “experiments branch” to work on; if it breaks, you can just switch back to the master branch with no harm done.

git branch # show branches 
git branch -c experiment # create the experiment branch
git checkout experiment # chekout the experiment branch; then work on it for a while
git commit -a -m "added a cool new feature, but it doesn't quite work" # commit your changes
git checkout master # go back to the master branch, since it still lworks and you need to use it for something.

Push and Pull

When you’re working together you may want to pull someone else’s changes or push your own to the group.

git pull # get the most recent branch of your original repository
git push # send all your commits on the current branch to the original repository

OK, that’s what I’ve got for now. Follow the excellent links near the top for more info. Good luck!