Upload and link your local project to GitHub

This post is a part of a (planned) series on “Collaborative Coding with GitHub”, a workshop that I’ve given several times at EPFL (through LauzHack) to help students and researchers familiarize themselves with Git and GitHub. The posts are meant to complement the workshop, whose material (slides and recording) can be found here. However, the posts can also be used as a standalone guide. Enjoy!

Imagine you’ve been working on a coding project that you’re now ready to share with the world! (Or privately with your colleagues/friends.) GitHub is a great place to upload and host that project, to share it with others and to also receive feedback and suggestions.

In this post, we’ll walk through the process of uploading your “local” project (namely from your computer) to GitHub. Let’s go!

Note that we’ll have to run things from the command line, but we’ll try to be as clear as possible. And git should be installed.

🏃 GTG (Go to GitHub)

First thing of course is to log in to GitHub. If you don’t have an account, you can create one for free. Once you’re logged in, you should see a page like this:

We’ll go ahead and click on the green “New” button to create a new repo.

Initialize your repo settings

You’ll now be taken to a page that looks like this:

Here we’ll see one of GitHub’s strengths: an intuitive interface that guides you through the process of creating a repo. Let’s go through each of the fields, and don’t worry if you mess up, you can always change these settings later or start again!

Repository name

This is the name of your repo. It will be used in the URL of your repo, so it’s best to keep it short and simple. You can use hyphens to separate words, but not spaces. The repository name does not have to match the name of your local folder.

Finally, you can optionally provide a description of your repo. This will only be displayed on the repo’s homepage on GitHub.

Public or private?

If you’re alright with everyone seeing your code, feel free to make it public! If it’s a project you want to keep under wraps and just share with collaborators, you can keep it private. You can always change this setting later.

Note that if you create a private repo, it is recommended to have an SSH key set up with your GitHub account (for SSH communication/authentication with GitHub). How to do that is described here.

Initializing your repository with standard files

GitHub suggests skipping this step if you’re importing an existing repository. However, if you’re uploading a local project which doesn’t have any Git history, it is fine to do this initialization and in fact very helpful! Because you can add files (that GitHub has templates for) that you may not already have in your project but that will be useful for others. If you already have one of these files, don’t add it as it may run into conflicts!

• A README file will serve as the homepage for the project when people look at it on GitHub, and it’s where you can put useful information about your code.
• .gitignore will tell the git protocol which files to ignore. GitHub has templates for many languages; pick the one for the primary programming language of your project.
• LICENSE tells others how they can use your code. It is essential to have one if you share code with others. Check out this page for help on picking a license. I recommend picking one now; you can always change it later. If you don’t have a license, the default is that people can’t do anything with your code! (Similarly you should be careful about using code that doesn’t have a license, and contact the author to provide a license!)

After you’ve picked which files you would like to initialize your repo with, go ahead and press the green “Create repository” button. You’ll be taken to your repo’s homepage, which will look something like below:

Linking your local project to the remote GitHub repo

Now we need to make the link between your local project and this newly-created repo on GitHub.

To that end, the following commands need to be run from the terminal and in the directory of your project.

As an example, I will use this minimal project (feel free to download and unzip).

# 1) Initialize a Git repository with a branch called "main". 
# Make sure to match the branch name on GitHub!
git init -b main
# The above command is for newer versions of Git. 
# If it doesn't work for you, try running:
# git init; git checkout -b main

# 2) Link your local folder with the remote repository
git remote add origin git@github.com:USERNAME/REPONAME.git
# In my case, the URL is git@github.com:ebezzam/my-school-project.git

You can check that the link between your local folder and the remote repo was made by running:

git remote -v
# you should see something like
# origin git@github.com:ebezzam/my-school-project.git (fetch)
# origin git@github.com:ebezzam/my-school-project.git (push)

You can now “pull” (git terminology for download) the files from the remote GitHub repo.

# if necessary, replace "main" with the name of the branch on GitHub
git pull origin main

If you type ls in the terminal, you can see which files are now in your local folder.

The following command will show which files are “untracked” (git terminology for files that are not part of the repository):

git status

Since we haven’t added any files to the remote GitHub repository, all of your project files will probably be untracked. You can track and add files to the remote GitHub repository by running commands like below (for our minimal project):

git add python.py                # add file(s) you would like to track
git commit -m "Add Python file." # Message to describe changes/additions
git push                         # "push" (upload) files to GitHub

In another post, we will explain these commands and show more convenient (and insightful) ways of tracking and uploading files to GitHub, namely with GitHub Desktop and VS code.