Git Course 0%

git remote

Intermediate Git CLI Safe ≈ 5 min

Summary: git remote manages the named URLs your repository can sync with. origin is the one git clone creates; a fork workflow adds a second, conventionally called upstream.

Safe — it edits the [remote …] sections of .git/config. No commit is created, moved or deleted, and a wrong URL is fixed by setting it again.

What it does

Reads and writes names paired with URLs, and the fetch rules that go with them. Nothing else in the repository is affected; removing a remote does not remove any commit you already fetched.

Why it exists

So that git push and git pull can be typed without a URL, and so that a repository can talk to more than one server.

When to use it

  • Checking where a clone points, which is the first diagnostic for most push and authentication problems.
  • Connecting a repository made with git init to a project you created on the platform.
  • Switching between HTTPS and SSH.
  • Adding upstream in a fork workflow (lesson 7.7).

When not to use it

  • To move commits: that is fetch, pull and push.
  • To fix a rejected push: the remote is usually fine; the branch has diverged (lesson 7.6).

Syntax

Form Meaning
git remote List remote names
git remote -v List names with their fetch and push URLs
git remote show origin Ask the server for the full picture (needs network and access)
git remote add <name> <url> Add one
git remote set-url <name> <url> Change an existing one's URL
git remote rename <old> <new> Rename
git remote remove <name> Forget it; commits are untouched
git remote prune origin Delete bookmarks for branches gone from the remote

Examples

Terminal
$ git remote -v
origin	https://gitlab.com/northwind-trails/trailguide.git (fetch)
origin	https://gitlab.com/northwind-trails/trailguide.git (push)

The full picture, which asks the server:

Terminal
$ git remote show origin
* remote origin
  Fetch URL: https://gitlab.com/northwind-trails/trailguide.git
  Push  URL: https://gitlab.com/northwind-trails/trailguide.git
  HEAD branch: main
  Remote branch:
    main tracked
  Local branch configured for 'git pull':
    main merges with remote main
  Local ref configured for 'git push':
    main pushes to main (up to date)

Connecting a folder made with git init:

Terminal
$ git remote add origin https://gitlab.com/you/trailguide.git
$ git push -u origin main

Switching from HTTPS to SSH, which affects nothing but authentication:

Terminal
$ git remote set-url origin git@gitlab.com:northwind-trails/trailguide.git

A fork's two remotes:

Terminal
$ git remote add upstream https://gitlab.com/northwind-trails/trailguide.git
$ git remote -v
origin	https://gitlab.com/you/trailguide.git (fetch)
origin	https://gitlab.com/you/trailguide.git (push)
upstream	https://gitlab.com/northwind-trails/trailguide.git (fetch)
upstream	https://gitlab.com/northwind-trails/trailguide.git (push)

Expected result

.git/config gains, loses or changes a [remote …] section. Listing prints text. git remote show contacts the server and therefore fails if you are offline or lack access.

Common mistakes

  • error: remote origin already exists when connecting a folder. Use set-url rather than add.
  • Cloning the original instead of your fork, so origin is a repository you cannot push to. git remote -v reveals it; set-url fixes it (lesson 7.7).
  • Pushing to upstream. Refused, correctly; push to origin.
  • Adding a second remote to work around a problem instead of correcting the first one's URL.
  • Expecting git remote remove to delete anything on the server. It only forgets the name locally.

How to undo or recover

Every operation is reversible with another git remote command: re-add what you removed, rename back, set the URL back. No commit is ever affected.

In VS Code

No dedicated interface; use the integrated terminal. Cloning sets origin for you, and the Command Palette's Git: Add Remote… exists in recent versions.

In IntelliJ IDEA

Git → Manage Remotes… lists them with +, − and edit buttons, which is exactly git remote add, remove and set-url.

git clone creates origin automatically · git push, git pull and git fetch use what remote configures · git config edits the same file directly.

Lessons that use this command

What a remote is · clone, remote, fetch, pull, push · Forks and the fork workflow · Lab 2.

Key terms

Remote origin Upstream Clone

Related