Using Git with GitHub

GitHub is a "Git server", which allows different Git users to synchronize repositories. In M2, all our code are saved in private repositories on GitHub.

Setting up your GitHub account

To login to GitHub from your terminal, use of SSH keys is preferred. Read this article by GitHub to setup your SSH key. If you have done the SSH lab, you have already generated an SSH key.

It is fine to have an SSH key without a passphrase, as long as you don't leak your ~/.ssh/id_rsa private key file.

Creating a repository

If you already have a Git repository initialized locally, you can create an empty repository on GitHub.

Go to https://github.com/new to create a repository. Do NOT select "Initialize README", nor choose the gitignore/LICENSE files; otherwise GitHub will create an orphan commit for your repository.

Managing remotes

A "remote" in a local Git repository is a remote location to push commits to and fetch commits from. The default remote is usually called origin. One GitHub repo corresponds to one remote.

In M2, we only need one remote in most cases.

Adding your GitHub repo as a remote

Suppose our GitHub account name is USERNAME and our repo is called REPONAME. After creating your repository, GitHub should have redirected you to https://github.com/USERNAME/REPONAME.

In your local repository, run the command

$ git remote add origin [email protected]:USERNAME/REPONAME

Info

You can also use git remote add origin https://github.com/USERNAME/REPONAME, which does not require SSH keys. However this will require you to type your username and password every time you interact with GitHub on the command line. Furthermore, this has usability problems with those who use 2-factor authentication.

This also applies to git clones.

Cloning an existing repository

If the Git repository already exists on GitHub but it is not yet on your computer, you can clone the repository. This is equivalent to initializing a local repository, adding remote (with the name origin), fetching commits and checking out the default branch.

$ git clone [email protected]:USERNAME/REPONAME

This will initialize a clone of the repository in a new directory called REPONAME.

Info

Sometimes you are told to clone with USERNAME/REPONAME.git instead. This .git actually does nothing, so save your time from typing 4 extra characters.

Pushing commits to GitHub

After adding the remote, we have to mark the remote (and its corresponding branch) as the "upstream" of our local branch. (Since we have not covered branches yet, assume branch = repo)

This can be done with the -u option the first time we git push in a repository:

$ git push -u origin master

Ater the upstream has been setup the first time, just type

$ git push

Do not force push.

If you see some answer on StackOverflow telling you to use git push with --force, think carefully before doing it. If someone else has already pulled the commit, your force push will end up creating inconsistent branch history, and it will result in scary merge conflicts them when they pull/push that branch again. Avoid doing that unless you are sure you are the only person using that branch.

Pulling commits from GitHub

If someone else has pushed changes to GitHub, you can download the changes with the command git pull.

git pull only works after you have set the upstream, which is already done in git push -u or in git clone.

If your local commit history is a prefix of the remote commit history (i.e. the remote just appended a few new commits after your latest commit), git pull will succeed with the word "Fast-forward" somewhere in the message. But if both local and remote have different commits since the last common commit, you will need to merge or rebase them. This will be explained in the next section.