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
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
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:
- 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:
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:
- We skipped creating a new branch via the
branch -M maincommand.
- We specified the
mastermain branch to push to, using the
-fflag to overwrite any existing content (not completely necessary in this case) and the
-uflag to set the remote origin as default (makes push commands easy later on)
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.