How to use the git remote add origin command

How do you connect a local Git repo to a remote repository your team has set up in GitHub, GitLab or Bitbucket?

There are two ways to push a local project to a remote Git repo: the recommended way, which is somewhat convoluted, and my easy sort-of-cheating way, which is much easier.

• The recommended way is to use the git remote add origin command.
• The easy way is to clone the remote repo, followed by a bit of copy and pasting.

We'll cover both approaches in this git remote add origin tutorial and let you decide which option suits you the best.

The simple method is described at the end of this article, so please don't click away before checking it out. It might make your Git journey a lot easier.

Simple git remote add origin use

The git remote add origin command works best under the following two conditions:

• The remote repository has no Git commit history.
• The remote repository has absolutely no files in it.

Let's start this git remote add origin tutorial with a happy assumption that both conditions are true.

How to use Git's remote add origin command

The steps to add a local project to a remote repo with the git remote add origin command are as follows:

1. Use git init to create a new local repository.
2. Add files and perform a git commit.
3. Obtain the Git URL of the remote repo.
4. Issue the git remote add origin command.
5. Use the git push command to upload your files.

Step 1: Create a local Git repo

To connect a new project to a remote Git repository, you must create a Git repo locally, add files and perform at least one commit. The terminal window commands to do this are as follows:

git init
git touch alpha.txt
git add alpha.txt
git commit -m "Git commit history created"

These commands create a local Git repository that includes one file and one commit.

Step 2: Add a reference to the remote repo

To connect this new project to a repo on a remote hosting service such as GitHub, GitLab or Bitbucket, obtain the Git URL of the remote repository and issue the following command:

git remote add origin https://github.com/cameronmcnz/remote-repo-url.git

This adds a reference to the remote server in your local project.

Step 3: Push your changes to the server

After the remote reference is configured, you can transfer your local files to the server with the git push command.

git push -u origin master

When this command completes, the files in your local repository, along with your branch's full commit history, are pushed up to the remote server.

This example assumes you created the local repository with a branch named "master," which is still the current default for Git. This creates a new branch on the server named "master" as well.

Collaborative Git operations

That's how easy it is to use the git remote add origin command when there is no commit history on the remote server.

After you add the remote server to your local Git installation, you can perform future push, pull and fetch operations normally.

• git push origin sends your local updates to the remote server.
• git pull pulls updates down from the local server and updates your workspace.
• git fetch pulls updates down from the local server without updating your workspace.

Use main, not master

Locally installed Git software defaults to master for the primary branch name when it is created in a new repository.

However, GitHub, GitLab and Bitbucket have all moved away from master and use the name main instead. You should too.

To rename your local master branch to main and push the main branch after the git remote add origin command runs, follow these steps:

git branch -M main
git remote add origin https://github.com/scrumtuous/repos-git-url.git
git push -u origin main

What if the remote repo isn't empty?

If the remote repo isn't empty, connecting to a remote Git repository becomes a bit more complicated.

If you push your new Git repo to a remote repository with an existing commit history, you will encounter the "failed to push some refs to remote" error.

One way to resolve this problem is to push with force, which is coded as git push --force or git push -f, but this is a dangerous operation if others are also working with the remote repository. A better option is to rebase, which preserves the Git commit history.

Push to origin with force

A push with force to the recently added remote origin server looks like the following:

git branch -M main
git remote add origin https://github.com/scrumtuous/repos-git-url.git

git push -u -f origin main

Again, if others on your team cloned this repo, problems will occur the next time they go to fetch or pull updates because the entire commit history on the main branch will have been rewritten.

If you're the only one working in this repo you'll be fine, but if the repo has been shared a rebase and push will be required.

Safely rebase and push a new project

To safely push an existing project to a remote Git repo that isn't empty, complete the following steps:

• Run the git remote add origin command.
• Perform a git pull.
• Rebase your local branch onto the pulled branch.
• Push your rebased files back to the server.
• Delete your old local branches.

The following commands assume your local branch is named master and the remote branch is named main. When performed, divergent Git commit histories are safely combined and a push to origin does not require force.

git remote add origin https://github.com/example/repo-git-url.git
git pull origin
git switch master
git rebase main
git push origin
git branch -d main

The Git push cheat method

Articles and videos on how to add a project to a remote repository with the git remote add command continue to be my most popular content. However, the joy that I'm helping people with Git recently turned to guilt when I realized there is a much easier way to add a local Git project to a remote repository.

The alternative approach might not work well if you want to preserve a long, local Git commit history, but it's positively delightful for a local repository with a manageable number and a Git commit history you are willing to give up.

Instead of forcing a push or rebasing a branch, this cheat method starts by simply cloning the remote repository.

When you clone, all the remote references and upstream branches are preconfigured automatically. There's no need to run the git remote add origin command. The process will already add the remote.

git clone https://github.com/scrumtuous/repos-git-url.git

After the clone, go to your existing project and copy all the files, with the exception of the hidden .git folder, into the cloned repository.

Then issue the compulsory git add, git commit and git push origin commands.

git clone https://github.com/scrumtuous/repos-git-url.git
cd repos*
git add .
git commit -m "Using the Cheat Method"
git push origin

The new, cloned repository becomes the new source of truth on your computer, and you can delete the old project. Just point your VS Code or Eclipse editors at the newly cloned repository and you're good. It's that easy.

That's pretty much the full gamut of different ways to use the git remote add origin command, along with a neat way to bypass the command entirely.

With that information, you can connect your local Git projects and push them up to a remote hosting service like GitHub or GitLab.

View All Videos