Connect Your Local Project Folder to an Existing GitHub Repository

You have a project folder on your computer and a repository already created on GitHub. They look like they should belong together, but they are not connected yet. Your local files do not push to GitHub, and changes on GitHub do not appear on your computer.

Connecting them is a one-time setup that takes only a few minutes. Once it is done, you can push, pull, and back up your work like any normal Git project.

This guide walks you through the whole process step by step, for a folder that is new to Git and for a folder that already has Git history, plus how to fix the most common connection errors.

Quick Answer

Inside your local project folder, run git init if Git is not set up yet, then add the GitHub repository as a remote with git remote add origin https://github.com/your-username/your-repo.git. Stage and commit your files, rename the branch to main with git branch -M main, and push with git push -u origin main. After that, your local folder and the GitHub repository are connected.

What You Need Before You Start

A little preparation makes the process smooth. Check these items first so you do not have to stop in the middle.

• Git installed: Run git --version in your terminal. If you see a version number, Git is ready. If not, install it first.
• A GitHub account: You need to be signed in to the account that owns the repository.
• The repository URL: Open the repository on GitHub, click the green Code button, and copy the HTTPS URL. It ends with .git.
• Your project folder: Know the exact location of the folder on your computer and make sure it contains the files you want to upload.

If Git is not installed yet, our beginner walkthrough on setting up Git on Windows 11 for the first time gets you ready in a few minutes, including the basic name and email configuration Git needs for commits.

Step-by-Step: Connect a Local Folder to GitHub

Step 1: Open a Terminal in Your Project Folder

All commands must run inside your project folder. On Windows, right-click inside the folder and choose Open in Terminal or Git Bash Here. On macOS and Linux, use cd to move into the folder.

Step 2: Initialize Git If Needed

1. Run git status. If Git says this is not a Git repository, your folder has not been initialized yet.
2. Run git init to create the hidden .git folder that makes this a Git project.
3. If git status worked in the first step, skip git init. Running it again will not destroy history, but there is no need.

Step 3: Add the GitHub Repository as the Remote

A remote is simply a named link to another copy of the repository. By convention, the main remote is called origin.

1. Copy the HTTPS URL from the GitHub repository’s Code button.
2. Run git remote add origin https://github.com/your-username/your-repo.git, replacing the URL with your real one.
3. Verify the link with git remote -v. You should see the same URL listed for both fetch and push.

The official GitHub guide to managing remote repositories explains how to change or remove a remote later, which is useful if you ever copy the wrong URL or move a project to a new account.

Step 4: Stage and Commit Your Local Files

1. Run git status to see all the files Git can now track.
2. Add them with git add . to stage everything in the folder.
3. Before committing, add a .gitignore file if your project has files that should never be uploaded, such as node_modules, environment files, or build folders.
4. Commit with git commit -m "Initial commit" or a message that describes your project start.

If Git asks who you are, set your identity once with git config --global user.name "Your Name" and git config --global user.email "you@example.com", then try the commit again.

Step 5: Match the Main Branch Name

GitHub now uses main as the default branch name, while older local Git setups may create master. To avoid confusion, rename your local branch with git branch -M main. This one command renames the current branch, even before the first push.

Step 6: Push to GitHub

1. Run git push -u origin main to upload your commit and set the upstream link.
2. Sign in if Git asks. Note that GitHub no longer accepts your normal account password for Git pushes. Use a personal access token or sign in through Git Credential Manager or GitHub CLI if prompted.
3. Refresh the repository page on GitHub. Your files should now appear there.

If the GitHub Repository Already Has Files

Sometimes the GitHub repository is not empty. It may contain a README, a license, or even code a teammate added. If you try to push your local history directly, Git may reject it because the two histories are different.

The safe fix is to pull the GitHub history into your local folder first and combine the two.

1. After adding the remote, run git fetch origin to download the GitHub information without changing your files yet.
2. Run git pull origin main --allow-unrelated-histories if your local project and the GitHub repository were created separately.
3. Fix any file conflicts if Git reports them, then add and commit the merged result.
4. Now run git push -u origin main again. With a shared history, the push should succeed.

Use the --allow-unrelated-histories flag only for this first connection when you are sure both sides belong to the same project. It is not a flag you need in daily work.

GitHub’s own official guide to adding locally hosted code to GitHub covers this empty and non-empty repository difference and offers GitHub CLI as an alternative tool.

How to Verify the Connection Works Both Ways

A one-way push is not a complete test. Check both directions so you trust the setup.

1. Make a tiny change to a file on GitHub using the web editor, and commit it there.
2. Run git pull in your local folder. The change should appear in your local file.
3. Make a small local change, add it, commit it, and run git push.
4. Refresh GitHub and confirm the second change is there too.

If both tests pass, your connection works. Your routine is now edit, add, commit, and push.

Using SSH Instead of HTTPS

The steps above use HTTPS, which is the easiest option for beginners. Many experienced developers prefer SSH because it uses a key file instead of a token prompt. If your team uses SSH, your remote URL will look like git@github.com:your-username/your-repo.git instead.

You can switch later with git remote set-url origin git@github.com:your-username/your-repo.git after setting up an SSH key.

Common Mistakes to Avoid

• Running commands in the wrong folder: If you run git init in your home folder or desktop by accident, Git will try to track everything there. Always confirm your terminal is inside the project folder first.
• Adding origin twice: If a remote called origin already exists, the add command will fail. Check with git remote -v and fix the URL with git remote set-url instead.
• Copying the wrong URL: The browser address of the repository page and the clone URL look similar but are not identical. Always copy from the green Code button.
• Forgetting a .gitignore file: Uploading dependency folders or secret keys is hard to undo. Set up ignores before your first commit.
• Pushing before pulling an existing history: If GitHub already has commits, pull and merge first. Forcing a push can erase your teammate’s work or the README history.
• Using your GitHub password for pushes: GitHub requires a token or credential manager sign-in for Git operations. A password error does not mean your account password is wrong.

Conclusion

Connecting a local project folder to an existing GitHub repository comes down to four ideas: initialize Git, add the repository as the origin remote, commit your files, and push the main branch with the upstream flag set.

If the GitHub side already has files, pull its history first and combine it carefully instead of forcing anything. Once your small two-way test passes, you can forget about the setup and focus on your project, knowing every push safely backs up your work to GitHub.

Frequently Asked Questions

What does “remote origin already exists” mean?

It means your local project already has a remote named origin, so Git will not add a second one with the same name. Run git remote -v to see the current URL, and change it with git remote set-url origin new-url if it is wrong.

Do I need to run git init if my folder already has a .git folder?

No. If the hidden .git folder exists and git status works, Git is already initialized and your history is there. Just add the remote and push. Running init again will not delete history, but it is unnecessary.

Why was my push rejected with a non-fast-forward error?

This usually means the GitHub repository has commits your local folder does not have yet. Pull first with git pull origin main, or use --allow-unrelated-histories for a first connection of two separate histories, resolve any conflicts, and then push again.

Should I use the HTTPS or SSH URL for my remote?

Use HTTPS if you are a beginner or have not set up SSH keys. Use SSH if your team requires it or you prefer key-based sign-in and have already added your public key to GitHub. You can switch later with the set-url command without losing history.

How do I disconnect my folder from a GitHub repository?

Run git remote remove origin inside the folder. This removes only the link. Your local files, commits, and the repository on GitHub all stay exactly as they are, and you can add a new remote later if needed.