git remote: the link to a remote repository

git remote manages the list of addresses your repository exchanges commits with. A remote is the same kind of git repository as yours, it just sits on another machine: GitHub, GitLab, a company server, or a folder on the computer next to you.

Locally the link is stored as a name plus an address. Every exchange command works with the name instead of the long URL, so you type the address once in the life of the project.

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

The two lines are the address for reading and the address for writing, and they usually match. Empty output means the repository is not linked to anything yet. add links it:

$ git remote add origin git@github.com:username/my-project.git

After git clone you do not need this: the clone writes origin in by itself.

origin is only a name

origin is the default name for the main remote, and there is nothing special inside it. Git substitutes that name when you type git push with no arguments. Rename origin and everything keeps working, you just have to spell the name out.

$ git remote rename origin github
$ git remote remove github        # drop the link, the history stays on disk

You can change an address by removing and re-adding the remote, but set-url is the proper way. You need it when a repository has moved or when you switch from HTTPS to SSH:

$ git remote set-url origin git@github.com:username/my-project.git

git remote show gives the full picture for one link: both addresses, the default branch on the server, and which local branch goes where.

$ git remote show origin
* remote origin
  Fetch URL: git@github.com:username/my-project.git
  Push  URL: git@github.com:username/my-project.git
  HEAD branch: main
  Remote branch:
    main tracked

Common mistakes

git remote add does not check the address. The command goes through silently with any typo, and the error only shows up at the first exchange, often as Repository not found. Start debugging with git remote -v.

The second mistake is adding origin on top of an existing one. Git answers error: remote origin already exists. What you want there is set-url, not add.

Where this is in the book

Chapter 6. GitHub: the cloud and working together. What to do with the link once it exists is covered in git push and git pull.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.