What does "git remote add" exactly do?

Question

I've recently been introduced to git in a project I've started working on, which encouraged me to start reading the online version of "Pro Git" by Scott Chacon.

There is a section in the book which briefly touches the subject of adding a "remote repository". Since Git is a distributed SCM, I understand that a common situation of using GIT would be to "clone" a remote repository on your local machine and work on your local copy. When you're done with your changes and committed all changes to your local copy, you then "push" your changes to the remote repository so others can view your changes too.

Which brings me to my question - from what I've understood, "git remote add" effectively "adds" a remote repository as a shorthand notation which we can use later. What I don't understand is this - since I clone by only specifying one repository URL, how can I add multiple repository urls under my local project's directory?

To be precise, suppose I check out the Apache commons-lang project using

git clone git://git.apache.org/commons-lang.git

This results in GIT copying over the whole project in my local directory named "commons-lang". Since I've used only one url for cloning, what does doing a "remote add" mean here? Does it mean that the same project (commons-lang) could be hosted on multiple servers, or is it that I could clone a new project within my local project by adding a new remote address?

Apologies for beginner-like tone of the question. Just trying to get my facts dead straight. Thanks.

Answer 1

You can add as many upstream repo address you want with git remote add (from "Git Basics - Working with Remotes").

When cloning, one is added for you, named 'origin'.

Does it mean that the same project (commons-lang) could be hosted on multiple servers,

Yes, that is due to the distributed nature of Git, since pushing and pulling introduces a publication workflow which is orthogonal to the merge workflow.

or is it that I could clone a new project within my local project by adding a new remote address?

No. You can fetch from different upstream repos.

See "Definition of “downstream” and “upstream”".

One classic scenario where you git remotes add is when forking on GitHub:
See "How do I merge locally a master and a fork in git?"

• origin is added for you when cloning your fork on GitHub.
• but you need to git remote add upstream https://github.com/user/reponame in order for your local clone to keep up-to-date with the original repo (hte one you cannot contribute directly, which is why you had to make a fork on GitHub in the first place).