Git and GitHub
GitHub is a host for git repositories—a way to share access to collections of code or other materials. Git itself is a version-control system. Version-control systems keep track of changes to files, and make it easier for people to collaborate on big projects. You’ll only collaborate with one partner at a time in CS 70, and you’ll always work together, but you’ll still be able to take advantage of some of the great things that come from using version control.
Repositories
Each of your assignments will be distributed as a repository,
which is a collection of files that share things like their record
of changes and list of people who can access them. For example, for
Homework 0, you used GitHub Classroom to clone a repository whose
name started with homework-00-. That repository included a file
called Readme.txt, a file called written-answers.md, and some
additional files whose names started with a . (period) that tell
git and VS Code how to interact with the files in the repository.
(Files whose names start with a . are hidden on *nix systems
(including macOS and Linux) unless you tell your file browser or, in a terminal, ls or a similar command to show them.)
Git Actions
Working with git involves a number of high-level concepts. While the terminology might be a bit unfamiliar, most version-control systems use similar ideas. The following sections outline the basic set of operations for using git.
Cloning
To make changes to the files in a repository, you first need to have a local copy of the repository on the computer you’re working on. Copying that repository is called cloning the repository. You will need to create a clone of your repository on every computer that you want to use to work on the assignment. [On lab machines, you'll need to make a new clone each time you log in.]
You can get the path for cloning a repository by navigating to it on GitHub, clicking the green , and copying the URL that is displayed. Then, in VS Code, you click on the button, and paste in the URL you copied.
Committing
git keeps track of different versions of your files, but it only knows about changes when you tell it about them.
To tell it to store a new version of a file or files, you have to commit the changes you'v emade. When you commit, you should include a brief message that describes how this version is different from previous versions. When a repository is open in VS Code, the commit message field, and the commit button (which looks like a checkmark), are at the top of the Version Control tab.
Pushing
Committed changes are only stored in your local copy of the repository unless you push them to repository on GitHub.
In VS Code, you use the menu next to the button to get to the command.
Pulling
The opposite of pushing is pulling, which copies any changes from your GitHub repository into your local repository. Pulling causes git to copy the remote files and then merge them into your existing files.
In VS Code, use the menu next to the button to get to the \span class="app-menu-example">Pull command.
Merge Conflicts
Merge conflicts occur when you've changed files in your local repository that have also been changed on GitHub. When you pull changes from GitHub into your repository, git's attempt to merge that code with what you have can result in conflicts—parts of the code you've both changed will be called out in the code, and must be resolved by editing the files and choosing one of the versions of the code to keep.
The best way to avoid merge conflicts is to pull changes into your repository before you start working—that way, your code is less likely to contain changes that conflict with changes on GitHub.
Once you're done working on your code, you should push your changes back to GitHub. (If something has changed on GitHub while you were working, you will have to first pull those changes, resolve any conflicts, and then push your changes to GitHub.)
If you find yourself with a merge conflict you can't resolve, a prof or grutor will be happy to help you resolve it.
Rolling Back
Sometimes you commit a new version of your code, then realize that you wish you’d kept an older version! If that happens, you can roll back to a previous version of your code. There are lots of options here, and we recommend that you check with a prof or grutor if you don’t feel comfortable finding the right approach on your own. We’re happy to help!
A Basic Glossary of Git Jargon
This part of the glossary defines some common git/GitHub-related terms that you will definitely encounter in the course of your work for CS70.
(Some definitions were taken from https://help.github.com/articles/github-glossary/.)
Common Terms
Add—to put changes to a repository in the queue to for git to save. In VSCode, use the button next to a changed file's name to queue its changes in a file for saving. The file is queued as it is at that moment, which means that if you change the file again after adding it to the queue, you will need to add the file again to add those additional changes to what will be committed.
Clone (verb)—to copy a remote repository in its entirety and store the the copy locally on your computer.
Clone (noun)—A clone is a copy of a repository that lives on your computer instead of on a website’s server somewhere. Changing the clone does NOT change the original repository.
Commit (verb)—to tell git (not github!) to save your most recent changes (i.e. current version) of a repo locally.
Commit (noun)—a version of (set of changes to) a repo that is saved locally (e.g. “The second commit contains all the work we did on the second task.”).
Commit message—a message written by you that describes the changes made to the repository when you commit (e.g. “Added header file” or “finished writing function 1”).
Git—a version control system (a program) that runs on your computer.
Github—a website that acts as a wrapper for git.
Local—stored on your computer. You can change local files or repositories by navigating to your home directory and adding, deleting, or changing material.
Markdown (md)—the style in which GitHub readmes, comments, and issues are written.Origin—the source of a cloned repository. If you change a clone, the origin remains unchanged.
Pull—to download the current copy of a repository from the cloud and save it locally. You should do this at the beginning of every work session.
Push—to tell GitHub to save your most recent changes to a repository in the cloud, accessible through your personal GitHub account.
Readme—a file that provides information about a repository. You should typically read the README before looking at or editing the other files in a repository.
Remote—stored in the cloud and accessible through the GitHub website. You can view remote repositories and files, but you cannot change them.
Repo[sitory]—a collection of files that share a change log and a list of people who can access them. Typically, all the files associated with one project will be located in a single repository. You can think of a repository as a folder or a directory that you access with a computer.
Staged—refers to changes that git will commit the next time the command git commit is run.
Unstaged—refers to changes that git will NOT commit the next time a commit happens. All changes are unstaged until you tell git to care about them by adding them.
Version control system—something that keeps track of changes to files and the timing of those changes.
Visual studio code—a text editor that you can use to write your CS70 Code.
Working directory—the folder that you are currently in.
Less Common Git Terms
This part of the glossary defines some less-common git/GitHub-related terms and terms that you may encounter when searching through GitHub (and other) documentation. You won't need to worry about these when completing CS 70 assignments, but they might be useful for personal projects or later work.
Branch—a parallel version of a repository that is still contained within the original repository. Branches are used to keep certain parts of code (such as new features or bug fixes) separate from stable code. Changes made to one branch of a repository are not automatically added to another branch, but they can be easily merged with another branch once you have finished testing them. This lets developers separate their work (on bug fixes or new features, for example) separate from the copy of a project that is being used by others until their changes have been thoroughly tested.
Note that even without deliberately creating branches yourself, the code you get from GitHub is already in a branch—the “main” (or, old-school, “master”) branch.
Commit id—a unique hashed number that is associated with the changes made in a commit. You will sometimes need this hash (or a truncated version of it) to refer to a specific commit.
Config[uration]—a collection of settings defining a particular set of behaviors git will use—for example, what text editor should be used when writing commit messages, or the name and email address you want associated with your work.
You can adjust many of these settings with the terminal command git config, but you will need to run git config on each machine you work on for the settings to be active on that machine. (Or copy the configuration file from machine to machine.)
Diff—the difference between two commits, or two sets of saved changes. The diff will visually describe what was added to or removed from a file since its last commit.
Init—a function you use to create a new repo for a new or existing project in its own directory. You will not need this function in CS 70 because you will begin each by cloning a starter repository from GitHub Classroom, but you will use it when working on your own projects.
Insertion—a line that was added to a file. Git will tell you how many insertions were made each time you commit your changes.
Issue—a suggested improvement, task, or question related to the repository—a “bug report”. You can view issues by navigating to the main page of a repository on GitHub with a web browser, and then clicking on the tab in the page header. Each issue has its own discussion forum on GitHub, and issues can be labeled (with, e.g., “bug”, “question”, “wontfix”) or assigned to a particular user for them to address.
Main—see master, below.
Master—the traditional (and problematic) name for the main branch of a repository, containing the original code or the already-working code.
The “master” branch is now usually called the “main” branch, and new repositories will usually use “main”. It's also possible to rename a branch, so changing from “master” to “main” is easily done.
Merge conflict—a problem that occurs when you try to combine two different sets of changes to the same parts of a repo. For example, perhaps you push some changes on line 42 of your code to GitHub. Then, your friend edits line 42 on their local copy without pulling your changes first. When your friend tries to push their changes, a merge conflict will occur, because git can tell that your friend edited an earlier version of the repo, and that their changes affect the same part of the repo as yours. When a merge conflict occurs, VS Code will show you all versions of the conflicting lines and ask you which changes you want to keep. Nothing will be overwritten unless you tell git to do so. In the line 42 example, you will have to choose whether you want to keep your changes to line 42 and reject your friend's changes, or accept their changes and discard your own. (Or even combine both sets of changes into a new whole.)
Pull request—a message asking the owner and collaborators of an origin repository to accept your changes to a clone (or a branch) of that repository to which you do not have write access. (I.e., you were able to clone their public repository and make changes, but getting those changes into the official repository has to be done by the owners/maintainers.)
Pull requests are usually associated with a particular issue—for example, they might address a bug or add a feature.
Rollback—to revert to an earlier version of your repository. You may want to roll back your code if you have made several mistakes in a current version of your repository. Rolling back your code in your local repository is unlikely to cause any problems for your collaborators, but if you've pushed your changes up to GitHub, your collaborators are likely to have conflicts. GitHub stops you from “changing history” by default, but you can still make those changes if you know what you're doing and you coordinate with your collaborators.
(When logged in, completion status appears here.)