Mark Mikofski -- Git Version Control with GitHub

September 10, 2018 at 4-5:30pm in BIDS, 190 Doe Library

Agenda

  1. Requirements
  2. Objectives
  3. What is Git VCS?
  4. GitHub
  5. GitHub Pages
  6. SSH or HTTPS
  7. Git Primer
  8. Winning Workflow

Requirements

To prepare for this tutorial make sure you have the following:

  1. We’re going to use Git, so make sure you have Git installed on a laptop, and of course, don’t forget to bring your laptop to the tutorial.

    • MacOS: you already have git, open a terminal and type git

    • Windows: install Git-for-Windows, no admin

    • Linux: use your app manager, eg Ubuntu: sudo apt install git

    For more info, see the Git SCM Book on installing Git

  2. We’re going to make a personal webpage on GitHub, so make sure your computer has working internet access. AFAIK anyone can use CalVisitor or AirBears WiFi connection for free.
  3. If you are not already registered for GitHub, please create an account. I strongly recommend that you enable two factor authentication using an app like Google Authenticator.
  4. You’ll probably want a basic editor like Notepad on Windows, TextEdit on Mac, and gedit in Linux, or you can also just edit your files directly on GitHub. Anything will do, but not a word-processor, no, and a fullblown IDE is also probably overkill. Something like Sublime Text or Notepad++ is just right IMHO.
  5. A willingness to participate, try new things, make mistakes, learn and have fun!

Objectives

At the end of this tutorial you will be able to do the following:

  1. explain to a colleague what version control is, why it’s important, what it’s important for, and when to use it
  2. use Git to version control your documents between iterations
  3. teach a coworker to use basic git commands, and to create a pull request on GitHub
  4. collaborate with others on GitHub using a feature-branch workflow
  5. make a personal webpage using GitHub Pages

Git VCS

What is Git? And why is it important?

In case of fire, git commit, git push and leave the building

In case of fire, git commit, git push and leave the building

From GitHub repo in-case-of-fire (c) 2015 Louis-Michel Couture

Git on Git

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. [1]

XKCD on Git

xkcd 1597: Git

Version Control Software (VCS) aka Source Code Management (SCM)

But what is Version Control?

… version control, aka source control, is the management of changes to documents, computer programs, large web sites, and other collections of information. [2]

Whether you’re writing a dissertation, developing an analysis, or writing code, you will revise, revise, and revise. Each iteration is important. Using Git VCS gives you the ability:

References

  1. Git SCM
  2. Wikipedia: Version Control

GitHub

Repeat the following 3 times out loud:

Git is not GitHub, and GitHub is not Git.

GitHub is an online hosted Git service that acts as a centralized repository for its users. You can create and clone Git repositories on GitHub, and you can pull from and push to Git repositories on GitHub, just as if they were on your own laptop, another networked laptop, or another online Git hosting service like Bitbucket or GitLab.

If you have not already created a GitHub account, you need to create one now to participate in this tutorial. Also, I encourage you to enable two-factor authentication (TFA on your GitHub account, and store your backup codes in a safe location, that you will remember. TFA makes it more difficult to hack your account.

GitHub Pages

GitHub allows users to host static content on GitHub Pages. Content written in markdown is automatically rendered as html using Jekyll, a Ruby static content generator. GitHub offers themes to beautify your site look and layout. It’s a great place to host your personal website.

  1. To create your personal GitHub Page, you need to create a new repository called <your-github-username>.github.io, for example mikofski.github.io.

  2. After the new repository is created, open the repository settings, and select theme chooser.

  3. After Choosing a theme, an online editor opens with index.md. You can make edits to this file like change the title to your name.

  4. Scroll to the bottom, find where it says commit directly to master, in the first field enter, “initial commit”, and then press the commit button.

Congratulations! You’ve just made your first Git commit on GitHub, and created your personal website. But, it’s far from done. It could use a little mroe work. Let’s take it offline, and iterate on it, till it’s just the way you want.

SSH or HTTPS

In order to pull the repository to your laptop, you’ll have to prove to GitHub, that you are who you say you are, and that you have permission to edit the site. There are two ways to authenticate to GitHub:

Git Primer

The most important Git command is git. If you type it in a terminal you get a list of the other most important Git commands such as init, clone, status, log, diff, add, commit, checkout, remote add, pull, and push.

The first thing you should do, after setting up your .ssh keys is to tell Git your full name and email address to use. Then we can get your new website and start hacking on it. The following commands are entered in a shell in a folder you use for projects for.

  1. Add your name and email using git config:

    $ git config --global user.name "Your Name Comes Here"
    $ git config --global user.email you@yourdomain.example.com
    
  2. Clone your GitHub repository to your laptop using git clone:

    # if you're using SSH
    $ git clone git@github.com:<github-username>/<github-username>.github.io.git
    
    # if you're using HTTPS
    $ git clone https://github.com/<github-username>/<github-username>.github.io.git
    
  3. Enter the newly cloned repo, display the remotes and the log

    $ git log
    $ git remote
    $ git remote show origin
    
  4. Now open your editor and make some changes to your index.md file.

  5. Before you make too many changes, go back to the shell and view the status, a diff from the previous version, and commit your changes

    $ git status
    $ git diff
    $ git commit -am "put any message here, usually under 50 characters"
    

XKCD on Git Commit

xkcd 1296: Git Commit

Winning Workflow

The secret power of using Git with GitHub is how easy it makes collaborating with others. AFAIK the feature-branch workflow is the most frequent method of collaboration on GitHub. I outlined it’s steps in a THW-Berkeley talk last year on using GitHub in OSS.

Additional Info

Share