539 Git Overview

About this Doc

Assumptions:

• Students are aware of the existence of git, but have not used it in a collaborative context. Each probably used it for term project versions, but that is different from using it to work together, and managing remote repositories

Goals:

• Motivate git usage in 539 - it’s a need to know to succeed
• Introduce git vocabulary & structure at a high level
• Give a couple sample workflows (no terminal commands, but using proper vocabulary)
• Some best practices

• Commit small changes often
• Stay in sync
• ALWAYS provide descriptive commit messages

• Provide next steps:

• What to download
• What lessons to do (where they can learn the real commands)

Non-goals:

• Teach the class how to use git

• This is intractable for a short lesson, and will need to be done

Introduction + Motivation

Git is a tool everyone in 539 will need to know this semester.

From term projects and malloc, most of you have probably used git to go back to old versions of your own code. This document focuses on how to use git as a collaborative tool. In 539 you are building a product, so we you use version control the way it is used in industry, not the way you use it for a personal project.

Git will be the medium through which we will store, share, review, and export code. If you want to contribute to 539 code, you need to know git.

Git Vocabulary

Git - Git is a tool that lets us take snapshots of our codebase, called versions. Git also lets us switch between new and old versions, combine versions and share our versions with other people.

GitHub - GitHub is a website that hosts GitHub repositories, but is distinct from plain old “git.” GitHub puts our git repository in the cloud, so it is easier to share code with one another. We will also use GitHub’s project management tools, like its issue tracker and code review system. Neither is part of standard git.

Repository - Git stores the history of each project in a repository. We will probably have at least one repository for each team.

Commit - When you want to save a copy of your code, either to go back to in the future, or to share it with someone else, you bundle up your changes in a commit. You can use the word commit as a verb:

Hey! That little change fixed the bug, I’ll commit my code now so I can come back to it if <crazy change> doesn’t work out.

Sometimes, commit is used as a noun, referring to a specific version of the code:

        Can we revert master back to the previous commit? The last change broke it.

Branch - A branch is a specific sequence of commits. Usually, we have multiple branches in the same repository. Contributors can commit code to one branch without interfering with the others, which is what makes it so easy to collaborate on different features in the same repository.

Remote - When you see remote, think “on GitHub.” A local branch or repository is one that you created on your computer, if you don’t push it to remote, your local code will never appear on gitHub.

Push/Pull - Pulling is taking code from a remote branch, and putting it into your local branch. Pushing is taking the code that you have on your computer, and writing it to a remote branch.

Merge - Merging is the process of reconciling changes that happened in one branch or commit with changes that happened in another. When two people edit code in the same repository, they have to merge it together.

Merge Conflict - If you try to merge two commits that edit the same lines of code, there is a “conflict” that you as the programmer must resolve. Merge conflicts are the ugliest part of git, when in doubt, ask for help!

Pull Request - A pull request is a request to merge code you committed on one branch into another. It is also the time when we will do code reviews. Pull requests happen on GitHub.

Visual Workflows

To see visual representations of workflows, see this PDF.

Best Practices

Be altruistic when using git for collaboration. If you put it an extra few seconds of work on your end, you will save your reviewers and collaborators oodles of time.

• Keep your changes small - This applies to both individual commits, and to pull requests. Keeping pull requests small will make them easier to review (meaning you’ll get reviews back faster), and make merge conflicts less likely. Small commits will make fixing merge conflicts easier if the do occur.
• Make every commit message count. If your commit messages are good, all collaborators, including Future You, will thank you. See the blog post in the Best Practices / Workflow section for great advice on commit messages.
• Stay in sync - Use “git fetch” and “git pull” often to make sure you don’t diverge too far from master. Divergence leads to merge conflicts.
• Don’t delete history. If you find yourself typing “git reset --hard” or “git push -f” stop and ask yourself “am I sure this won’t erase a bunch of code?” then ask someone who knows git better than you the same question. Then think about it more. THEN you can (maybe) run one of those commands.

• “git rebase -i” is a command that can be used for good or evil. Be careful with it, but I find I use it for legitimate purposes more often than the above commands.
• “push -f” is especially dangerous because you can delete other people’s code.

Resources

What should I download?

If you have a mac or linux machine, and feel at home in your terminal, you’re in luck! Git is already installed. See the “Learning Git Commands” section to get started.

If you use Windows, are uncomfortable in a terminal, or want to avoid learning a fairly complex terminal command, you should download a git GUI. GitHub provides simple GUIs, and GitKraken is a more advanced client that is free for non-commercial use.

Homework

• 15-131 Git Lessons - The GPI staff have been revising this lesson for years, it goes from configuration to using git with GitHub, which we want to do for this course.
• Git Game - This is a good way to test your skills after completing the above lessons.

Documentation

• Official Git Documentation - Reference section for commands, external links section for more learning
• GitHub cheat sheet - This focuses on terminal commands

Best Practices / Workflow

• The GitHub Flow - There are many git workflows, but we’ll probably use a variation of this one. Btw - when you see “fork and pull” vs “shared repository” we are using the shared repository model.
• “The Commit Message Blog Post” - This is how to write commit messages. We won’t be pedantic about verb tense, but your TAs/intern hosts/reviewers will LOVE you if you write good commit messages.