Timothy Wood - Git & GitHub

Git & GitHub

Git is a version control tool to help you track changes to a set of files. Git (and similar tools like cvs, svn, mercurial, etc) is invaluable for safely keeping files synchronized for a team of programmers, or even just for yourself across multiple computers. GitHub is a website that provides a hosting location for your files and a convenient web interface to them. While you can use git without GitHub, having a web interface to your source code repositories is very helpful.

This page will give you the minimum skills needed to get started using git and GitHub. This tutorial was written on August 7, 2013; while git's interface is fairly stable, the look of the GitHub website may change with time.

Basic Terminology

A repository is a place where the files for a project are stored. A "repo" can store any type of files just like a set of folders on your computer, but with git it also tracks the entire history of changes made to the files and directories within the repository. With git/github, you will have a local version of the repository on your own computer, and you will synchronize your files to the remote repository hosted on github's servers.

After making changes to your files, you commit them back to the remote repository. This preserves your changes so others can see them, but also allows you to roll back if you realize you made a mistake.

Other important terms include conflicts, branches, merging, and tags, but we will ignore all those advanced issues for now.

Gitting Started

You can download and install the git command line tools from http://git-scm.com/downloads. Git runs on mac, linux, and windows, so you really have no excuse not to use it. On windows you should install Git Bash. This tutorial will assume you use the command line tools.

Since we will be using GitHub, you should also create a (free) account for yourself on their website. The basic free account only allows public repositories, but if you register with a .edu email address you can request a student or faculty account that lets you create private repositories as well.

Once you install the tools, it's a good idea to set up your username and email since that will be associated with any commits you make. From the command line, run:

git config --global user.name "Your Name"
git config --global user.email "email@example.edu"
Getting A Repository

In some cases you are using git to create your own project, in which you need to create your own empty repository to store your code (Option 1). Other times you are building off of someone else's code that already exists in another repository. In that case you need to fork the repository which gives you a copy to work from (Option 2).

Option 1: Creating a Repository

This will tell you how to create your own empty repository. We will do this through the GitHub web interface. GitHub's BootCamp has a good tutorial, but I think the steps below are simpler.

Log in to GitHub and click the green "New Repository" button. This will give you a form like:

Fill in a name and description, and mark it as public or private (if available). Check the "Initialize this repository with a README" option so that our repository will have something in it. Click Create Repository when you are happy with your name and description.

On the next screen you will see an overview of your mostly empty repository. Its only current contents is a Readme.md file (the" md" is for "markdown", essentially a text-only file type that allows for some basic formatting). As you add new files and folders to the repo they will show up here.

Option 2: Forking a Repository

If you are building off of someone else's code that already exists in a git repository, then you can create a fork to easily get a copy to build on. This has the added benefit of making it easy get updates that they make to their code or even for you to suggest updates based on changes you make in your repository.

Forking a repository is simple. Simply go to the web page of the GitHub repository you want to copy and click the Fork button in the top right of the window.

Cloning a Repository

Whether you chose to create an empty repository or fork an existing one, right now your repository only exists on GitHub's servers—if we want to edit files locally we will have to make a clone to work in. First, we need to find the URL of our repository. You can find this on the bottom right of the screen. Click the clipboard icon next to the "HTTPS Clone URL" to copy the address to your clipboard.

You should have a URL similar to: https://github.com/YOUR-USERNAME/YOUR-REPO.git

Open a command line and run:

# Paste in the URL for your repository
git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git
cd YOUR-REPO

You should now have a folder with the same name as your repository. If you did Option 1 and created your own repo, then you will find a single file, Readme.md, which should have the name of your repository inside of it. You now have a local repository where you can make changes, before synchronizing with the version on github's server.

Adding Files to the Repo

Next we will add some files to our local repository so we can start tracking them. Copy or create at least two files inside the YOUR-REPO folder. Then go back to your terminal and run the command git status

You should see an output similar to:

git status
# On branch master
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	file.c
#	server.c
nothing added to commit but untracked files present (use "git add" to track)

The status command gives us lots of useful information, in this case that we have two files which git is not actively tracking. Git is also friendly enough to tell us exactly what command we need to run to add those files to our repository so that git will keep track of their changes. Follow the instructions and run:

git add file.c
git add server.c

Now if we run git status again, we will see that it is tracking our new files:

git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	new file:   file.c
#	new file:   server.c

However, git add only prepares them to be tracked! We still need to run: git commit -m "Adding new files"

git commit -m "adding new files"
[master 001c575] adding new files
 2 files changed, 49 insertions(+)
 create mode 100644 file.c
 create mode 100644 server.c

This records that everything was committed to the local repository successfully. Here we used a simple commit message ("Adding new files"), but it is a good practice to include a longer description of the changes made by this commit.

Note that unlike other source control systems like CVS or SVN, with git you need to run git add whenever you want to commit the changes you have made to a file (NOT just the first time you are adding the new file to the repo). Think of git add as recording a snapshot of the file's current state, and then git commit as preserving the snapshots of all files you have added.

Pushing to the Remote Repo

When you commit a file, you are recording its current status into the local repository's history. If we want the changes to be reflected on the remote repository (the one hosted on github's website), we still need to push the files. To verify this, refresh the website of your github repo—it still should only show your Readme.md file!

To send our commits to the remote repository, run: git push origin master

git push origin master
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 77.58 KiB, done.
Total 4 (delta 0), reused 0 (delta 0)
To https://github.com/twood02/testing.git
   c9549a6..001c575  master -> master

Now you can refresh the github website, and you should see your new files!

Pulling from the Remote Repo

Source control systems are generally used when multiple people will be editing the files in the repository. Since git keeps a local version of the repo on your computer, you need to explicitly ask it to pull down changes from the remote repo after others make commits.

To see how this works, let's first use the github web interface to edit the README.md file. Click the file's name and then click Edit. This will give you a simple text editor. For source code files, the editor will provide syntax highlighting, giving you a nice way to view and make small changes to the code. After adding a few lines to the README.md file, write a commit message and click "Commit Changes".

Not surprisingly, if you open your command line and look at the README.md file on your local machine, it will not have the changes you just made. In order to see those changes, we need to run git pull origin master

git pull origin master
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From https://github.com/twood02/testing
 * branch            master     -> FETCH_HEAD
Updating 001c575..eeb65e1
Fast-forward
 README.md |    1 +
 1 file changed, 1 insertion(+)

This shows that git has downloaded the changed files and modified our local repository by applying all of the commits we missed.

That's Git!

You now know all you need to know in order to create and clone a git repository, add and commit to your local repo, and push or pull from the remote repository. In general your workflow should be:

  1. Add a small chunk of new functionality to your code or fix a bug
  2. Use git add and git commit to save your changes to the local repo
  3. Periodically (e.g., every few commits, or whenever you want others to see your code) use git push to send all of your recent commits to the remote repo.
  4. Run git pull to download changes that others have made and integrate them with your own code.

Remember: git status is your friend! It will tell you the current state of your files and will remind you about the commands to commit or reset files to their last saved state. You can also get a wealth of information from git help.

Further Material

There is a lot more you can learn about git. Try these resources:

While this tutorial has focused on using GitHub as your remote repo, in fact you can use almost any server on which you have ssh access (although you won't get the nice web interface). You can also try BitBucket, which offers a very similar service as GitHub (with the benefit of allowing you to have private repos for free). Most of what you have learned here is interchangeable regardless of where your repos are hosted.

learn/git.txt · Last modified: 2016/08/17 15:37 by twood