Add An Existing Project to an Empty Github Repository

Adding a local project to an empty repository on Github is an easy process. This is a useful workflow for local projects in need of remote versioning. Unfortunately, the instructions offered by Github on an empty repo’s URL don’t always work out smoothly.

TL;DR – Github’s instructions for adding a local project to an empty repo don’t always work out as expected. The following code will ensure your local project makes it to the remote repo every time. Note: this will delete anything currently in the remote repo.

git init
git add -A
git commit -m 'initial commit'
git remote add origin https://github.com/<usename>/<repo-name>.git
git push -u -f origin main

2022 Update: Github has changed the name of the default branch from master to main. A previous version of this article described pushing things to master but has been updated to reflect the change. Read about it here. GIT may not reflect this change when creating local projects first. To reconfigure one’s local GIT software’s default branch name use the following command:

git config --global init.defaultBranch main

The main argument represents the new default branch name (updated from master in most cases.) This will avoid pushing a second master branch to new empty Github repos with an empty main default branch.

Adding A Local Project to an Empty Github Repository

In this article, you’ll learn how to quickly initialize a local project folder for versioning via git, create an empty repo on Github, and then push your local project to that repo. The workflow is nearly identical to that recommended by GitHub with a few notable exceptions we’ll cover in some detail.

Step 1: Create a Repository on Github

The first step in adding a local project folder to a new Github repository is to create a new repository! Github makes this process simple and achievable by the following actions:

1. Click the drop-down menu from the upper right area of the screen near your profile picture icon.
2. Select “New repository” as your option
3. Enter the repository name and configure options on the resulting Create a new repository screen.

A local project can be pushed to an existing repository as well—even one that is not empty—but that process is beyond the scope of this article. Let’s see what our newly-minted Github repository looks like.

Step 2: Configure Local Project

It should go without saying you need to have an existing project before attempting to add something to Github. This requirement can be satisfied either by creating a new project (Option 1) or by pushing an existing project (Option 2). The first one works as expected but Github’s instructions for the second can cause issues.

Option 1: Push a Newly-Created Project Folder

Github’s instructions work perfectly—for those creating a new project folder without existing version control. This can be achieved by following the instructions provided by Github. Note: creating the README.md file is optional but the git init command is essential. Here’s the code provided by Github per the new repo screen:

echo "# example" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/<your-username>/<your-repo-name>.git
git push -u origin main

Option 2: Push an Existing Repository via Command Line

Pushing an existing project folder where version control is already in place doesn’t always work when following Github’s official instructions. Below are the official Github instructions for adding an existing project to an empty repository:

git remote add origin https://github.com/<your-username>/<your-repo-name>.git
git branch -M main
git push -u origin main

Now, let’s see what happens when we try that:

(venv) \path\to\project\Example>git init
Initialized empty Git repository in \path\to\project\Example/.git/

(venv) \path\to\project\Example>git add README.md

(venv) \path\to\project\Example>git remote add origin https://github.com/alphazwest/example.git

(venv) \path\to\project\Example>git branch -M main

error: refname refs/heads/master not found
fatal: Branch rename failed

At this point, our new repository is still empty since we weren’t able to get to the point where we’d normally push our local project. At least that means we don’t have to nuke our repo to try again. Now, let’s take another approach.

Fix: Pushing to Main

Messing around with the master main branch directly can cause trouble. This won’t be an issue in those cases since we’re just pushing an existing project to an empty remote repository. There’s nothing to overnight, nothing to merge, and no conflicts to resolve. This can be achieved similarly to the steps taken in Option 2 above, but with a few notable differences:

(venv) \path\to\project\Example>git init
Initialized empty Git repository in \path\to\project\Example/.git/

(venv) \path\to\project\Example>echo "# example" >> README.md

(venv) \path\to\project\Example>git add README.md

(venv) \path\to\project\Example>git commit -m "initial commit"
[main (root-commit) 2c763fd] initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

(venv) \path\to\project\Example>git remote add origin https://github.com/<username>/example.git

(venv) \path\to\project\Example>git push -u -f origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 225 bytes | 225.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/<username>/example.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Everything worked out nicely this time. So what did we do differently? There were two major differences in our approach here:

1. We skipped creating a new branch via the branch -M main command.
2. We specified the master main branch to push to, using the -f flag to overwrite any existing content (not completely necessary in this case) and the -u flag to set the remote origin as default (makes push commands easy later on)

Final Thoughts

Version control is one of the hallmarks of responsible software development. These powerful tools aren’t restricted to professional workflows alone, however. Systems like Git, mercurial, and subversion can be used on projects of all sizes and complexities.

Github makes pushing, pulling, and branching from remote repositories simple. These commands can be issued via command line or, as is the case with many modern workflows, via integration with IDEs like IntelliJ or Visual Studio.

I often find myself working on projects locally without having moved versioning and project files to a Github (or similar) remote repository. The process to transfer an existing project to Github is outlined poorly by Github and often fails. I hope the approach outlined here can help save some collective Googling for developers everywhere.