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.
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:
Click the drop-down menu from the upper right area of the screen near your profile picture icon.
Select “New repository” as your option
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:
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 Master
Messing around with the master 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:
Everything worked out nicely this time. So what did we do differently? There were two major differences in our approach here:
We skipped creating a new branch via the branch -M main command.
We specified the master 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)
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.