How to Add a Remote Repository in Git

The Problem

You're working in a local Git repository, you try to push your code with git push, and you get an error: fatal: origin does not appear to be a git repository. Your commits are safe locally, but Git has no idea where to send them.

This happens more often than you'd think. Maybe you initialized a local repo without connecting it to a remote. Maybe you deleted your .git/config by accident. Maybe you switched machines. The fix is simple: you just need to tell Git where your remote repository lives.

The Solution: Add a Remote with git remote add

The command is straightforward:

git remote add [remote-name] [repository-url]

In most cases, you'll use origin as the remote name (by convention, this is your main repository):

git remote add origin https://github.com/username/repo.git

That's it. Git now knows where to push your code.

Understanding What Just Happened

When you add a remote, Git stores the connection in your .git/config file. The remote name (origin) is just a label - you can use anything like upstream, backup, or production. But origin is the standard convention for your primary remote repository.

When you later run git push -u origin main, Git uses this remote configuration to know exactly where to send your commits. The -u flag sets origin main as the default tracking branch - you only need it once. After that, a plain git push is enough.

Common Scenarios and Solutions

Scenario 1: You Cloned a Repo But Lost the Remote

Maybe you cloned a repository, and somehow the remote got deleted. Check what remotes you currently have:

git remote -v

If the output is empty, add the remote back:

git remote add origin https://github.com/username/your-repo.git

Scenario 2: You Created a Local Repo and Now Want to Push It

You initialized a local repository with git init, made some commits, and now you've created an empty repository on GitHub (or GitLab, Gitea, etc.). Connect them:

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

Breaking this down:

• git remote add origin ... - connects your local repo to the remote
• git branch -M main - renames your current branch to main (only needed if it's not already)
• git push -u origin main - pushes your commits and sets main to track origin/main

Scenario 3: You Added the Wrong Remote URL

You can see all your remotes with:

git remote -v

If the URL is wrong, either update it or remove and re-add it:

git remote set-url origin [new-url]

Or remove and start fresh:

git remote remove origin
git remote add origin [correct-url]

Scenario 4: You Want Multiple Remotes

You can have more than one remote. For example, if you fork a repository on GitHub, you might want both your fork and the original:

git remote add origin https://github.com/your-username/fork.git
git remote add upstream https://github.com/original-author/repo.git

Now origin is your fork (where you push), and upstream is the original (where you pull updates from).

How to Verify It Worked

Run this to see all your remotes:

git remote -v

You should see output like:

origin  https://github.com/username/repo.git (fetch)
origin  https://github.com/username/repo.git (push)

Now try pushing:

# provided you used `git push -u origin main` before
git push

Your commits should upload successfully.

Why This Matters

Without a remote configured, your local work is isolated. You can commit all day, but Git can't push anywhere. Adding a remote is what connects your local repository to the rest of your team, to GitHub, or to your backup server. It's the bridge between your machine and the cloud.

Key Commands Reference

Quick Troubleshooting

"fatal: remote origin already exists"

• You're trying to add origin when it already exists. Either use a different name, or remove the old one first: git remote remove origin

"Connection refused" or "Permission denied" after adding remote

• Your URL might be wrong, or you might not have SSH/HTTPS access set up. Double-check the repository URL and your credentials.

"Your branch is ahead of origin/main by X commits"

• This is normal after adding a remote. Your local commits haven't been pushed yet. Run git push to send them.

Conclusion

Adding a remote repository is one of Git's most fundamental operations, and it's dead simple once you know the command. Whether you're connecting a local repo to GitHub for the first time, recovering from a deleted .git/config, or setting up multiple remotes, git remote add is your tool. Keep it in your muscle memory, and you'll never be stuck with commits that have nowhere to go.

Found this helpful? Please share it with someone who also might find it helpful. Would you like more posts from me? Subscribe to the newsletter. Got questions? Send an email to commitnobug@outlook.com.