Git Remote

What Is a Remote?

Every Git repository can track connections to other repositories called remotes. A remote is nothing more than a name paired with a URL. Instead of typing out a long repository URL every time you want to sync changes, Git lets you give that URL a short alias, most commonly origin. Remotes make it possible for a distributed version control system to feel collaborative, even though every developer has a full, independent copy of the project history on their own machine.

Because Git is distributed, there is no single required 'central' server the way there is in older centralized systems like Subversion. A remote is just a convention, a pointer your local repository keeps so it knows where to push finished work and where to pull down updates made by teammates. You can have zero remotes, one remote, or many remotes pointing at forks, mirrors, or staging servers.

The Origin Convention

When you clone a repository, Git automatically creates a remote named origin that points back to the URL you cloned from. Origin is just a naming convention, not a keyword baked into Git's internals, but nearly every tutorial, tool, and teammate assumes it exists, so it is wise to keep using it unless you have a specific reason not to. Origin typically represents 'the repository I cloned this project from,' which is often, but not always, the same as the official project repository.

• origin - the default name Git assigns after a clone
• upstream - a common convention for the original repo when you are working from a fork
• A remote name can be anything you like: staging, backup, deploy, teammate-alex

Adding a Remote Manually

If you started a repository locally with git init rather than cloning one, you will need to add a remote yourself before you can push or pull anything. The command for this is git remote add, which takes a short name and a URL.

$ git init
Initialized empty Git repository in /home/dev/project/.git/

$ git remote add origin https://github.com/acme/project.git

$ git remote -v
origin  https://github.com/acme/project.git (fetch)
origin  https://github.com/acme/project.git (push)

Inspecting and Managing Remotes

Beyond adding a remote, Git gives you commands to inspect, rename, and remove them. git remote show origin prints detailed information, including which branches are tracked and whether your local branches are ahead or behind. If a repository moves to a new hosting URL, you do not need to re-clone; you can simply update the existing remote in place.

$ git remote rename origin old-origin

$ git remote add origin git@github.com:acme/project.git

$ git remote set-url origin git@github.com:acme/project-renamed.git

$ git remote -v
origin  git@github.com:acme/project-renamed.git (fetch)
origin  git@github.com:acme/project-renamed.git (push)

HTTPS vs SSH Remote URLs

Removing a Remote

If a remote is no longer needed, for example after a fork relationship ends, you can remove it with git remote remove or its shorter alias git remote rm. This only deletes the local reference; it has no effect whatsoever on the remote server itself.

$ git remote remove old-origin

$ git remote -v
origin  git@github.com:acme/project-renamed.git (fetch)
origin  git@github.com:acme/project-renamed.git (push)