GitHub 101

Lesson adapted from the fantastic Ishaan Dey!

Intro to Git

Let's say we're working on our personal websites for Project One. As such, we have a hierarchy of HTML files that will contain the structure and content for our pages and subpages.

We'll also have a CSS file to handle our styles, and some JavaScript to handle user interaction and allow us to make some more complex buttons and other displays. Currently, our local directory (the folder on our laptop that contains our project files) looks like this:

└── my-envision-website
    ├── html
    │   ├── index.html
    |   ├── about.html
    │   └── contact.html
    ├── js
    │   ├── adding-some-d3.js
    │   └── contact.js
    ├── css
    │    └── styles.css
    

But, as we're trying to edit one of our files, we accidentally corrupt or delete our css/styles.css file. If we weren't using git, this would be a huge problem—this file is irrevocably deleted from our computer, and we'd have to spend hours carefully re-developing the styles we've worked on!

Luckily, we've made our project folder (my-envision-website/) into a Git repository.

Because of this, we can tell git to "roll back" our folder to a previous version, and get that CSS file right back!

What is Git?

Git is a version control system. Much in the way Google Docs allow us to look back at previous versions of a document, Git gives us the ability to track changes to a project.

Git does this by taking a series of snapshots of the project over time. Every time we save the state of the project, or commit, Git takes a picture of what all the files looked like just in that moment of time. It stores this information in a “database” of sorts.

When we take a look at these changes, we can view a quick summary of what changed. For example with css/styles.css:

body {
    color:green;
    border: 10px solid blue;
    margin: 10px;
-   font-family:Helvetica;
+   font-family:Inter;  
    }
    
+ h1 {
+    font-family:Nichrome
+    }  

The lines marked with plus signs in the above code are those which were ADDED since the last commit, and those with minus signs are those which were DELETED.

Each one of these snapshots are saved in sequence, so Git allows us to see versions over time, then go back to previous ones with ease.

Git allows us to easily roll our project back to previous versions

In fact, every time a file in our project changes at all, git recognizes and remembers the change. That information gets stored into a hidden git "database," also known as a git repository, or "repo" for short.

Once you start using Git through making "commits" to take "snapshots" of the current state of your directory, you'll notice a hidden folder appear, called .git. Your directory will now look like this!

└── my-envision-website
    ├── .git
    |   └── < lots of things ... >
    ├── html
    │   ├── index.html
    |   ├── about.html
    │   └── contact.html
    ├── js
    │   ├── adding-some-d3.js
    │   └── contact.js
    ├── css
    │    └── styles.css

GitHub

Let's say we'd like to share our project with a friend, who's a much better designer than we are and has graciously offered to give us some help with our CSS styling.

GitHub uses git to make this type of online collaboration extremely easy.

To be clear, GitHub is entirely separate from git. GitHub is an online platform that hosts repositories, and uses the git version control system to do this.

I've been trying to think of a non-techy analogy for this. The closest I can get is git = Microsoft Office, while GitHub = Google Drive?

Microsoft Office pioneered the technology involved, and allows you to edit docs, sheets, and slides on your local computer, while Google Drive lets you do the same sort of thing online, backed up in the cloud, in a collaborative environment with your peers.

Take it if it works, leave it if it confuses you!

How do we give our friend access to our website code?

It's actually extremely easy, since GitHub uses git and we're already working in a GitHub repository locally. All we need to do is create a corresponding repository for my-envision-website on GitHub, then connect our "local" repository to that "remote" repository.

Then, our friend can use the command:

git clone https://github.com/our-username/my-envision-website

This is called cloning, and it will give our friend a local copy of our my-envision-website folder on their laptop. We can now work on this same project together, quite easily!

If our friend makes edits that they'd like us to incorporate into our site, they can push those edits from their local computer to that same remote GitHub repo.

To bring those changes back to our computer, we can pull them down to our computer, which will update the files our friend changed.

Source: Git-It

Honestly, that's pretty much it, in terms of core principles! There's a good bit more to Git, and I encourage you to check out on your own (look up git branching, and Pull Requests) but this is the general concept behind what we'll need this semester.

The Basic Workflow

We’ve already covered most, if not all of the basics of working with Git. Let’s walk through an example:

At any point, use git --help or git <command> --help to pull up help pages (Type q if you see a : in the command line to exit the help pages).

Set Up Remote

1. Let’s start by navigating to the directory (folder) that you'd like to make a Git repository. This should be the folder for your envision website!

   • Open the bash terminal of your choice (For MacOS: use Terminal — For Windows: use Git Bash)

   • Using bash commands, cd into your directory

   • Make sure there’s at least one file in this directory. (Your index.html should be there, at least!)

2. Initialize the repository with git init:

   • This creates a hidden .git directory, which we can now reveal with ls -la

3. Check the status of the files in your repository with git status . This will show you what changes you've made since you last committed your repository, including what files are added, deleted, or modified.

4. Stage all changes using git add --all. Whenever Git detects a change to a file, it goes into one of 3 distinct phases:

   1. Modified means that the file is changed, but isn’t yet saved to the repo. This occurs by default. These changes as saved in the working directory.

   2. Staged means we’ve marked the modified file as ready to enter into the next commit. We would say that these edits are saved to the index.

   3. Committed means that the snapshot, containing only the staged edits, is now saved to the repo.
5. Commit these changes to the local repo using git commit -m "Initial Commit"

   • The "-m" flag stands for message

   • Good practice for naming commits are short statements with a verb up front, i.e. “Add thing x”

6. In order to push our changes up to a remote repository, we first need to create a GitHub repo

   • Log in to GitHub in your browser, and create a new repository. The name doesn't have to be the same as your folder on your computer, but doing so can make things a bit easier to remember and keep track of!

7. Push up your changes to your new remote!

   1. Once you've created the repo, follow the instructions under "...or push an existing repository from the command line". It should give you three commands to run, which will:

      1. Connect your local repository to the new remote one (git remote add origin...)

      2. Make sure that you're on the "main" branch of that repository (git branch -M main)

      3. And push up your changes (git push etc.)