Before you can understand this section, you should read and understand the section Too Many Unclear Terms.
I believe the Git term "remote" is the most misunderstood, misused, ill-defined and mis-defined term of Git. Even the Git documentation seems to get it wrong more often than not. Official Git documentation uses the term "remote" under 5 separate definitions.
Until I wrote my glossary entry for remote, casual users and beginners didn't stand a chance at properly understanding what is meant by "remote". And even thought I say the term "remote" has 5 definitions, there wasn't enough space in the glossary to fully detail where these 5 definitions came from. This web page is dedicated to backing up what the claim in my glossary.
Are you an expert user and think you know what the term "remote" is? What about other terms like "remote-tracking branch" or "remote repository"? Are you sure? We'll see.
I go through a lot of mind-numbing, boring effort in the next few sections. I'll understand if you want to jump to the section titled Summing Up What We've Found About Definition of "Remote" and continue reading from there.
Unfortunately, I have to properly document for several reasons:
There is no entry for the term remote in the Git glossary.
Interestingly, in the Git glossary, the word "remote" is used 19 times, but most of those are used in conjuction with another word to produce another term other than "remote" (i.e., "remote-tracking branch" or "remote repository".) The only time the term "remote" is actually used is when the terms remote repository and remote-tracking branch are defined, but neither explicitly defines what a "remote" actually is.
At best, we can begin to assume that "remote" and "remote repository" are synonyms, but that is far from certain based on the given information in the glossary.
If they are synonyms, then a "remote" assumes the same definition as "remote repository". Here is the definition of remote repository from the Git glossary:
A repository which is used to track the same project but resides somewhere else.
Quite frankly, this definition is pretty poor. If you already understand Git, it makes sense, but if you don't, it will only confuse you.
Spoilers:
In the definition of "remote repository" I quoted above, the terms "remote" and "remote repository" are supposed to be synonyms, but I will wind up showing that they aren't always synonyms.
For better and worse, "remote" and "remote repository" are never explicitly defined to be synonyms in any of the official documentation I've read. Pro Git Chapter 2.5 and Pro Git Chapter 10.3 come the closest to linking the terms "remote" and "remote repository" as synonyms. I'll address Pro Git in more detail shortly.
Note: I've said it before, but it bears repeating. Git documentation broke a cardinal rule of technical documentation: never use synonyms for technical terms. Synonyms are avoided in technical documentation becuase they lead to confusion -- something that has very clearly happened with the word / term "remote".
In the man pages for git remote, we see the following descriptions:
git-remote [manages a] set of tracked repositories
and it also says
[git-remote manages] the set of repositories ("remotes") whose branches you track
This is already confusing. It's obvious git remote is managing repositories, but... are the repositories somehow tracked? Or do the repositories have branches that are tracked? That seems like an important distinction.
Note: When we discuss tracking in What is Tracking?, we'll see the word "tracking" makes no sense in Git. Technically, git doesn't do any tracking at all. But, let's run with what we have for now.
The term remote is defined as "repository". We know this because the word "repositories" is followed by the word "remotes" in parenthesis. This is a firm definition.
The term repository should be pretty clear. A repository can either be a local repository or an external repository.
That leaves us with two potential ways to define remote at this point. A remote is a:
Note: If you're an expert, you should already be balking at my extracted definition. And please don't say I'm purposely defining this wrong -- I simply pulled the definition from the man pages and made a reasonable and logical assumption -- just like a beginner who knows very little about Git would. In fact, this happened to me, and for a long time, it confused me.
Note: If you're a casual user or beginner, do not believe my adjusted definitions at all. They are completely wrong and are sending you down the wrong path. My example is designed to show experts how poorly defined the term remote is.
I've made my point. If the sentence has "repositories", I should be able to add the words "local or external" before it, but in this case, it's a bad idea. (If the documentation meant "external repository" or "local repository", then it should explicitly say that. Anything else is unclear.)
This was obviously a dead end. The words "local or external" are not part of the original definition, so let's go back to the original definition and define remote as one of the following:
I've done some digging and can't find another reference to the term "tracked repository". Doing an internet search for this term yields low quality results. As far as I know, the term "tracked repository" only exists once in the whole of the man pages and Pro Git book -- and we're looking at it. That probably means "tracked repository" isn't a term at all, and it's literally saying that a "repository is tracked". This is blatently false. Git does not "track" anything by any reasonable definition of the English word track. Thus, the defintion "tracked repository" is a dead end. We'll have to discard "tracked repository" as a bad definition and ignore it.
Note: Again, when we discuss tracking in What is Tracking?, we'll see the word "tracking" makes no sense in Git. Technically, git doesn't do any tracking at all. But, again, let's run with what we have for now.
So, now we're left with only one definition:
When we focus on remote being defined as "repository whose branches are tracked", we may be getting closer to what a remote could be, but we're still pretty far away from any solid definition.
We can conclude that the man page entry git remote defines the Git term "remote" as a "repository whose branches are tracked".
If you're an expert, this definition probably makes sense to you. If you're a beginner, this completely conflicts with the definition that we extracted from the Git glossary.
The man pages for the three commands git fetch, git push, and git pull produce a somewhat different take on the term "remote" than git remote.
Note: For clarity's sake, I'll only quote from git fetch, but git push and git pull have very similar documentation to git fetch.
The term "remote" is never actually defined in any of these three man page entries, but there are many references to the term "remote" in the man pages. Here are some (but not all) examples from git fetch:
origin remote will be used..."--all states: "fetch all remotes"-p / --prune states:--mirror option..."Looking at the command line option --all where it states that it fetches all remotes, it can be surmised that "remote" is a synonym for "remote repository".
We don't seem to be getting firm answers yet -- certainly nothing that a beginner can use. Let's see what Pro Git has to say.
Pro Git, Chapter 2.5 strongly alludes to the idea that the terms "remote" and "remote repository" are the same, but also simultaneously alludes to the idea that they aren't.
git remote show <remote> command. If you run this command with a particular shortname, such as origin..."git remote show <remote> command. If you run this command with a particular shortname, such as origin... It lists the URL for the remote repository..."In Pro Git, Chapter 3.5, in the section on Pushing, it also alludes that both "remote" and "remote repository" are the same:
We've looked in depth as to what "remote" might possibly mean. We've found the following:
git remote:git fetch, git push, git pullSo, based on Pro Git, it can be assumed "remote" and "remote repository" are synonyms. Probably. (I think it's fair to say a beginner could never be sure.)
And assuming these two terms are synonyms (based on Pro Git), when we combine the Git glossary information, we see "remote" and "remote repository" mean "A repository which is used to track the same project but resides somewhere else".
Adding the Man Pages information, we see "remote" and "remote repository" actually mean "A repository whose branches are tracked; these tracked branches are used to track the same project but this project resides somewhere else."
Wow. That was a lot of work for a beginner. And we've learned very little.
By this point, it should be clear that use of the word "remote" is not properly defined and is used very poorly in the Git documentation. But I'm not done. We've merely tried to see how the official Git documentation defines the word "remote". (And in the process, uncovered a lot of poor and incorrect documentation.)
To a beginner, this does not actually define what a remote is much less what it is used for.
For now, we'll simply say "remote" and "remote repository" are the same.
As for what "remote" / "remote repository" actually means, we'll take a step towards an answer in the next section.
On the surface, it seems pretty clear that a "remote repository" should not be in the "local repository", and yet, official Git documentation seems to indicate sometimes that it is.
The question that the Git documentation fails to properly address is the following: Does the term "remote repository" mean a repository, as in another Git repository that is external to our local repository? Or does the term "remote repository" refer to a setting inside of the local repository that points to an external repository?
It's an important distinction and one that the Git documentation confuses very often.
We can start with the command git remote itself. It is designed to add, remove, and rename something. If git remote is adding information to our local repository and letting our local repository know that an external repository exists, then that makes sense. Additionally, if git remote is removing knowledge from our local repository and stating that the external repository is no longer important, then (on the surface) that could make sense.
But what about the rename functionality of git remote? You can't rename "knowledge". To answer this, we need to understand a little bit of what Git does under the hood. And to understand what it does under the hood, we'll look at the command git fetch for a moment.
The command git fetch <URL> <remoteBranch> fetches a specific branch from an external repository. The command git fetch <shortname> also fetches all branches from a particular repository where shortname is pre-programmed into the local repository and represents a URL. (The URL represents the external repository.)
Note: The man pages don't use the term "shortname", but the term "shortname" is used by Pro Git in Chapter 2.5.
Specifying a URL with git fetch implies that an external repository exists at the other end of the network where the URL says it exists. And when we successfully use a command like git fetch with a URL, it's only while the command runs that our local repository becomes temporarily aware that an external repository exists. When the command is finished, the command is discarded and our local repository no longer knows if the URL is still valid. The external repository could be taken offline for maintenance or perhaps the external repository is destroyed in a fire. Our local repository doesn't care because it doesn't keep track of these things when we specify a URL directly.
The man pages say that the git fetch command can use either the shortname or URL for the <repository> parameter. Specifically, the man pages say:
<repository>The "remote" repository that is the source of a fetch or pull operation. This parameter can be either a URL... or the name of a remote...
Note: Actually, I find the parameters that the man pages lists a bit different from how git fetch actually operates, but maybe I'm just reading the documentation wrong. In my opinion, the man page of git fetch is particularly confusing.
Because we just pain stakingly found out in the previous section that "remotes" and "remote repositories" are actually the same thing, I want to take what we just from git fetch, combine it with what we found earlier, and rewrite part of the man pages into something more understandable:
"The <repository> parameter represents a 'remote repository', and can be either a URL or a shortname."
Looking at this (rewritten) part of the man pages, it seems to indicate that the term "remote repository" is some kind of external repository and does not refer to some setting inside of the local repository. Instead, the shortname is the setting inside of the local repository.
I wish I could say it was that straight forward. Unfortunately, the man pages for git remote depict something quite different.
As I said above, git remote can add, remove or rename something. What is that something? The man pages of git remote say we can:
Remember, we figured out that "remote" means "remote repository", so the man pages are literally saying the command git remote does the following:
Renaming a remote repository makes no sense at all. We can't "rename a URL", and we can't rename a remote repository because a remote repository doesn't exist at all on our local repository. This is a problem.
It would make more sense to say that we add shortnames, remove shortnames, and rename shortnames. That makes sense. (It's not fully correct, but makes sense and it starts us down the right path.)
It should be pretty clear by this point that we could maybe add, remove, and rename something like shortnames. We could maybe add and remove URLs, but we can't rename URLs. And most importantly, we can only reference remote repositories because they lie outside of the local repository entirely.
Unfortunately, Pro Git, Chapter 2.5 is littered with examples of using the term "remote repositories" to mean both an external repository and something like a shortname. I won't list every one, but I'll present a few examples of each.
Examples that reference a full external repository complete with files and commits:
Examples that reference a shortname:
Pro Git tried very hard to define what a remote repository was at the very top of Chapter 2.5. It states:
Remote repositories are versions of your project that are hosted on the Internet or network somewhere.
And it states in the note right below it:
It is entirely possible that you can be working with a “remote” repository that is, in fact, on the same host you are. The word “remote” does not necessarily imply that the repository is somewhere else on the network or Internet, only that it is elsewhere.
I never liked this wording. It's confusing and, quite frankly, completely blunders the definition of what a remote repository actually is.
Does a remote repository exists in the local repository?
The answer is a definitive no. The git remote command does not add and remove entire remote repositories complete with files and commits.
But what does git remote add and remove? Shortnames? No, not strictly speaking, because git remote adds and removes both shortnames and URLs at the the same time. The appearance of both represent something important. However, it's pretty striking that we can rename shortnames, but not URLs. This is also important.
And we still don't know exactly what a "remote repository" is. For instance, if it's remote, then why at the top of Chapter 2.5, does it state that "remote repositories can be on your local machine"? (Actually, this statement is correct. A remote repository can reside on your local machine, but it cannot reside in your local repository.)
This kind of stuff can be maddening for people who are new to Git.
It's time to answer these questions and make better definitions.
As I state in my glossary, remote has five official Git definitions:
At first glance, I think most people will say "This can't be". Yes, it can be, and now I'll show you where Git documentation defines all five terms. In fact, if you've read every word above, you've already seen four of them. ("Tracked Repository" and "Remote Name" are a little different, so I'll save those for last.)
The hardest thing about all of this is that Git never explicitly defines what "remote" is. All of these definitions had to be inferred. (For such an important and central term, that is really sad.)
Remote repository is the definition most people think of when they hear "remote". So far, this is what I've focused on.
Above, I had a huge list from Pro Git that strongly alluded to "remote" and "remote repository" being synonyms. Thus, I think it's safe to say that "remote repository" is a synonym for "remote".
This second definition, repository, exists because Git documentation cannot properly distinguish between what I call a remote repository and an external repository. Git documentation simply calls both "remote repository", but they are not the same.
With a casual glance, Pro Git, Chapter 2.5 is very convincing that "remote" can only be a synonym for "remote repository". For instance, we add a remote repository (into our configuration) and fetch branches from this remote repository.
However, what if we don't add any remote repository into our configuration? And what if we use the command git fetch <URL> <remoteBranch>?
I'll remind you that the man pages of git fetch has <repository> listed as a parameter to the command and underneath it says:
<repository>The "remote" repository that is the source of a fetch or pull operation. This parameter can be either a URL... or the name of a remote...
If we haven't added any remote repositories using git remote, then what kind of "repository" are we fetching from when we specify a URL? I would say that we're fetching an "external repository", not a "remote repository". And this is why I made the term "external repository" have a separate definition from "remote repository".
And now we come to the conundrum: If the Git documentation mixes two definitions when using the term "remote repository", the documentation doesn't mean "remote repository" all the time. It sometimes means "repository" in a more generic sense.
Note: This is obviously not 100% correct either because repository can mean external repository, remote repository, or local repository. Git documentation doesn't mean to include local repository like I do, but there is no other terms that either I or the Git documentation has defined, so we're kind of stuck. It's not important to define yet another term for this unfortunate scenario -- it's more important that Git clean up the documentation and use an appropriate term.
So, yes, what Git documentation meant exactly can be argued about, but there is no getting around the idea that the definitions of "remote repository" and "external repository" are mixed, and that the more generic term for both is "repository".
And now that you know that the Git documentation mixes these two terms up, you'll start seeing more instances in the documentation where "external repository" should have been used instead of "remote repository".
In the last section, we saw how "remote" can be a synonym not only for "remote repository" but also to a version of "repository". However, we only focused on the URL. Now I want to look at the "name of a remote".
Shortname is found in Pro Git Chapter 2.5 and Chapter 3.5. It's pretty clear that a "shortname" represents a URL, and that when a "remote is added" the shortname is then associated with the URL and thus the remote repository at the other end of that URL.
The command git fetch not only fetches information for URLs, but it can fetch information based on shortnames: git fetch <shortname>. Of course, that's not how the man pages state it. The man pages say:
<repository>The "remote" repository that is the source of a fetch or pull operation. This parameter can be either a URL... or the name of a remote...
Let me take some words out so it's more clear.
The "remote" repository [defined as <repository>] can be the name of a remote.
So, a "remote repository" is a synonym for "shortname"... and "remote" and "repository". Sort of. I don't know about you, but I find definitions to be very blurry at this point.
Maybe you think this explanation is iffy or far fetched? I want to remind you that Git never explicitly defined what a "remote" was. The definition of "remote" has to be inferred from the documentation and that's all I'm doing.
Let me ask you this: what makes more sense: Does the command git remote add, delete, and rename repositories? Or does it add, delete, and rename shortnames? Thus, this is a point to indicate that "remote" and "shortnames" are probably sometimes synonyms.
As a final point, if you peek inside of the .git/config file when remote names are defined and when tracking branches are defined, you'll find the term "remote" being utilized as a shortname.
The command git remote is an endless source of headaches. As I stated somewhere above, the man pages clearly state for git remote:
git-remote [manages a] set of tracked repositories
This clearly links "remote" and "tracked repository" to be synonyms... except for the fact that the term "tracked repository" isn't used again in Git documentation at all.
And in What is Tracking?, I explain that Git may throw around terms that have the word "track" in them, but Git doesn't actually track anything. Especially not repositories.
So, this is a bit of a ghost term, a source of confusion, and clearly labeled as a synonym for whatever that is worth.
Remote Name is a term I made up and is never used by official Git documentation, so I can understand this may be the hardest for many people to accept, but in my opinion, it is definitely alluded to by the git remote command. I simply finished flushing it out as a term in my glossary.
In the detailed definition that I give in my glossary, I explain how "remote name" is the link that joins a shortname and a URL together. In there, I also make an argument that git remote actually adds, removes, or alters "remote name".
The best explanation as to why "remote name" is needed as a fifth synonym is explained below in the section Why Have The Term "Remote Name"?. For now, I'd simply prefer to define five terms (including "remote name") before explaining why the term "remote name" is needed.
Some unofficial websites claim that git remote adds and removes remote references. This can't be. Although there are two definitions for "remote reference", both definitions specify that a remote reference is a kind of reference. A reference is a pointer to a Git object. None of the five definitions above have anything to do with references, and none of the official Git documentation that I've seen states this either.
It should be clear by now that the term "remote" is a complete mess. And I haven't even looked at the word "remote" in definitions like remote reference where two definitions exist. Or how the word "remote" alters the differences in definitions between tracking branch and remote-tracking branch even though both types of branches are stored on local repositories.
Although an overhaul from top to bottom is the only way to properly fix this problem, the cure may be worse than the disease. A complete overhaul of terminology would make tremendous amounts of official and unofficial documentation obsolete overnight.
Is there middle ground we can use? Yes, there is. What you're reading right now and my glossary are the middle ground. (I also want to make a list of common Git commands using my terminology as parameters, but that is an undertaking that I currently don't have time for.)
The primary goal of this article is to "demystify" the term "remote". When we do, there will be several collateral benefits -- like better understanding the command git remote. The secondary goal is to understand oddities in terms that contain the word "remote" like "remote reference" and "remote-tracking branch".
As we explored the Git definition of remote, we discovered "remote" is supposed to be synonymous with "remote repository", although that wasn't possible to explicitly prove.
It's time to learn exactly what a "remote repository" actually is, but it turns out that we can't define remote repository without defining four other terms first. (And once we're done with these initial terms, we'll then look at the other terms that involve the word "remote".)
A local repository exists inside of a .git directory on a hard drive.
That means the local repository (and .git directory) exists on a computer somewhere -- maybe on a laptop at home or maybe on a server in the cloud. The word "local" does not mean a physical location. It's defined by which .git directory you happen to be working in at the moment.
Note: I'm not including the staging area, staging index, and working tree in this explanation because 1) the Git documentation doesn't focus on these things and 2) it's not important at this moment. However, once you understand what a repository is, it would be good to make sure you understand how these work in relation to local / external / remote repositories. I suggest you look at Is a Staging Area Part of a Repository?
At this moment, there are millions of external repositories relative to a local repository.
Note: A URL represents the address of an external repository.
Two or more repositories are considered local / external only in relation to one another. Here are a couple of examples:
It's very possible that Repository A, Repository B, and Repository C all reside on the same laptop in three different .git directories. Or maybe the .git directories are scattered in different places across the internet. Either way, it doesn't change the fact that Repository B is an external repository to Repository A, and Repository A is an external repository to Repository B.
Important Note:
An "external repository" cannot be defined without a "local repository" -- this is a crucial point. If you are looking at one "external repository", then you're actually thinking about two repositories -- the external repository and the local repository. This is why we have to define both terms together.
The Git documentation missed explaining this important fact. Pro Git, Chapter 2.5 is the chapter that introduces readers to the concept of the "remote" / "remote repository", but you'll find the term "local repository" only stated one time.
(A "remote repository" is a kind of "external repository". I'll finish defining that in a moment.)
Many Git commands accept URL as a parameter, but they will also accept shortnames as well.
Shortname is not a term that I made up. It's used in Pro Git Chapter 2.5 and Chapter 3.5. I think it's a necessary (and underutilized) term.
A shortname if often created with the command git remote, but can also be created with other commands like git clone.
The shortname is stored in .git/config within the local repository.
A remote name can be referenced either by the shortname or the URL that defines it.
Because a remote name is made up of the shortname and a URL, a remote name is created at the same time a shortname is created. The shortname and URL are both stored in .git/config inside the local repository.
Note: "Remote name" is a term that I made up, but I felt it necessary. (My reasons will become clearer after I define "remote repository" and revisit the git remote command in Why Have The Term "Remote Name"?.)
There's no magic here. The existence of a remote name defines an external repository to be a remote repository. In other words, the link between a shortname and a URL designates a specific external repository found at the other end of the URL to be special to the local repository.
Note: An external repository defined to be a remote repository is still considered to be an external repository.
Note: I haven't tried this, but I think it's possible to have two remote names that point to the same external repository. If this is the case, then two or more remote names can define a single remote repository.
Official Git terminology and documentation can make some things really uncomfortable.
It always felt odd to me to use the command git remote add <shortname> <URL>. Why? Well, we're supposed to be doing something to a "remote". If the Git term "remote" is a synonym for what I call an external repository, then is this command somehow adding the entire contents of the .git folder from the external repository to our .git folder in our local repository?
Note: Keep in mind that a remote repository (as defined by strict Git documentation) or an external repository (as defined by me) is a repository that has a completely separate .git directory from our local repository.
No. We're adding two pieces of information to the .git/config file in our local repository: a URL (which represents the external repository) and a shortname (which is a name substitution for the external repository). That's it. Repository contents are not added nor copied. This is simply a local settings change.
Even worse -- and using terminology that only what Git documentation has presented us (i.e., a "remote" is defined to be a "remote repository) -- we can use git remote add <shortname> <URL> to create a remote repository in our local repository, and then use git fetch <shortname> to copy a remote repository into our... er... well, we've copied a remote repository into a remote repository.
Well, this is really awkward.
(No, a "remote repository" doesn't become a tracked repository. I've already explained that above and in my glossary.)
However, if we consider remote to be a synonym for remote name like I've defined, then when git remote add takes a shortname and URL as parameters, then it fits perfectly to say that git remote add adds a "remote name".
It should be clear by this point that the command git remote isn't about external repositories that exist "somewhere else". It's about settings we place in our local repository.
"Remote name" is a representation of settings in our local repository. And looking at it from this perspective, git remote remove and git remote rename make more sense.
Even the command to "view remotes" is improved. In other words, when I use the command git remote to show us our remote names, it shows us part of the remote names (just the shortname). However, we can also use the verbose form git remote -v to show us the entire remote name (both the shortname and the URL).
My definition of "remote repository" depends upon the term "remote name", and in doing so, we find that my definition of "remote repository" is almost entirely compatible with the way Git documentation uses the term "remote repository".
And the icing on the cake is that when we add a remote name, we transform an external repository into a remote repository. That is not awkward and certainly cleaner than what the official Git documentation currently has.
I think what I've explicitly defined what the Git documentation was trying to achieve, but missed.
One of the biggest advantages to defining the terms the way I have is that my terms are almost completely compatible with the Git documentation. In other words, my terms are designed to supplement the Git documentation, not contradict it.
Of course, you will see the occasional contradiction, but there are some things I can't fix. For instance, the command git remote show <shortname> doesn't display shortnames and URLs, but instead it lists remote branches, tracking branches, and remote-tracking branches. (Yuck.) As I said, a complete overhaul is needed from top to bottom to properly fix everything, but at least what I present is a big step closer and doesn't require a lot of programming effort -- only a documentation overhaul. Or we can just force newbies and casual users to read my documentation.
Note: A given local repository may have no remote repositories defined or it may have many remote repositories defined.
I've introduced some different terms that may be hard to follow for some people. I'll borrow an example from Pro Git, Chapter 2.5, subsection Adding Remote Repositories, and explain how my terms fit:
Note for beginners:
git remote shows you a list of shortnames.git remote -v shows you a list of shortnames and their associated URLs broken down by fetching and pushing. (In Two URLs per Remote Repository Or One?, I talk more about why there are separate entries for fetching and pushing.)At all times:
https://github.com/schacon/ticgithttps://github.com/paulboone/ticgithttps://github.com/schacon/ticgithttps://github.com/paulboone/ticgitBefore the command git remote add pb https://github.com/paulboone/ticgit is executed:
https://github.com/schacon/ticgithttps://github.com/schacon/ticgitorigin and the URL https://github.com/schacon/ticgitAfter the command git remote add pb https://github.com/paulboone/ticgit is executed:
https://github.com/schacon/ticgithttps://github.com/paulboone/ticgithttps://github.com/schacon/ticgithttps://github.com/paulboone/ticgitorigin and the URL https://github.com/schacon/ticgitpb and the URL https://github.com/paulboone/ticgitIf you're new to Git, you may have noticed an oddity in my example from Pro Git, Chapter 2.5, subsection Adding Remote Repositories.
I'll use a slight variation so we can see it more clearly.
We used one URL to define a remote name, but two URLs are being shown when we get information about the remote repository -- one for fetching and one for pushing. What happened?
This confused me for a long time until I finally got deep enough to see what was happening. Pro Git, Chapter 10.5 explains in detail, but I'll give you the short answer.
You must fetch and push to the same repository (meaning the base of the URL will be the same), but depending on Git server settings, the path (i.e., the ending of the URL) can be different between fetching and pushing.
There are a few minor problem with my definitions:
I admit, these are gray areas, but there's no need to be pedantic in this case. My goal is to fix official Git documentation while also remaining compatible with it. These are very minor edge cases that can be overlooked.
Although I've tried very hard to remain compatible with the Git glossary and Git documentation, there are a few items in my glossary which purposely contradict official Git documentation and this is probably the most prominent: I refuse to use is the term "remote". For reasons detailed above and below, using the term "remote" is really bad. It is simply too confusing to use.
As Git documentation usually means to use "remote" as a synonym for "remote repository", others on the internet have simply abandoned use of the word "remote" and use "remote repository" all the time. I urge everyone else to abandon use of the word "remote" too. I also urge the Git team to deprecate and stop using the term "remote" and start using "remote repository" and "external repository" instead.
We've (mostly) established that the Git term "remote" means "remote repository". We know what a remote repository is and we know it is (mostly) the opposite of a local repository.
The next step is to see if Git uses the word "remote" correctly from an English perspective. In other words, when we see the terms, "reference" and "remote reference", can we rely on the English definition of "remote" to help us understand what we're reading?
Spoiler: No, we can't. In some cases, the English works, but far from all cases and not always in the way you'd expect.
Let's start with an exact English definition of "remote".
I'm going to state a simple English definition of "remote" that I created:
(adjective) far removed in space or time or relationship
(adjective) denote that a computing object can only be accessed by means of a network
(noun) a device used to control an object from a distance
My definition is based on these sources:
(adjective) far removed in space, time, or relation (Merriam-Webster)
(adjective) Denoting a device which can only be accessed by means of a network (Lexico.com -- Powered by dictionary.com and Oxford University Press)
(adjective) separated by an interval or space greater than usual (Merriam-Webster)
(adjective) acting, acted on, or controlled indirectly or from a distance (Merriam-Webster)
(adjective) Having very little connection with or relationship to (Lexico.com -- Powered by dictionary.com and Oxford University Press)
(adjective) operating or controlled from a distance, as by remote control (dictionary.com)
Remote Control
(noun) remote control (Merriam-Webster)
"remote control" is defined as: (noun) a device or mechanism for controlling something from a distance (Merriam-Webster)
(noun) A remote control device (Lexico.com -- Powered by dictionary.com and Oxford University Press)
"remote control" is defined as: (noun) a device used to control the operation of an apparatus or machine, as a television set, from a distance (dictionary.com)
Does the Git term "remote" fit in with the English definition of "remote"? No, it does not.
The Git term "remote" is a noun. The only English definition of "remote" that is a noun is "a device used to control an object from a distance". This definition does not describe the function of remote repository.
"Remote repository" almost fits the English definition, but what are the other terms that use "remote" and how well do they fit in with the English definitions presented? There are four variations to consider:
I will go over each case as best as I can, but I've already gone into excrutiating detail trying to figure out how the word "remote" is used in the Git documentation and it didn't end well. I will not go into as much detail on these other terms, but unfortunately dealing with "branch", "remote branch", "tracking branch", and "remote-tracking branch" is complicated.
While the term "remote" doesn't fit the English definition, the word "remote" in the term "remote repository" does sort of fit the English definition.
Repository and remote repository cannot be compared against one another because "repository" is a more general term. In this context, the adjective "remote" does not fit.
However, if "remote repository" is compared against local repository, we find that "remote repository" is indeed far removed in relationship from a "local repository", so it does fit. Of course, when the term external repository is introduced, things become more cloudy about how the adjective "remote" actually behaves.
The word "remote" in the term "remote reference" does not fit the English definition.
There are several reasons. Ignoring that the term reference is complicated, remote reference actually has two definitions which don't mesh well together. Further adding to the confusion is that under certain conditions, a "reference" can simultaneously be both a "local reference" and "remote reference". (See the detailed glossary entry of local reference for more information.)
In short, the definitions of "local reference" and "remote reference" are not precise enough to even begin to decide how the word "remote" makes an impact.
While the term "remote" doesn't fit the English definition, the word "remote" in the term "remote branch" does sort of fit the English definition.
Branch and remote branch cannot be compared against one another because "branch" is a more general term. In this context, the adjective "remote" does not fit.
However, if "remote branch" is compared against local branch, we find that "remote branch" is indeed far removed in relationship from a "local branch", so it does fit.
The word "remote" in the term "remote-tracking branch" does not fit the English definition.
Both tracking branches and remote-tracking branches are actually local branches. At the same time, both types of branches (almost always) represent a remote branch.
(This is yet another reason I don't condone the use of the term "tracking branch". But it is an official Git term, so it's in my glossary.)
I may not like the term, but the term remote-tracking branch exists and is therefore defined in my glossary.
Apparently, the term remote-tracking reference also exists. As my glossary explains, this is an erroneous term used by official Git documentation. The term itself should not exist because it makes no logical sense.
This means that the words "remote-tracking" has no special meaning and cannot be compared to the term tracking.
The word "remote" as defined by the English language (used as either a noun or adjective) is not properly used by the Git documentation. In the terms where it can fit, it's not a tight fit. Thus, the English definition cannot be relied upon to help figure out the meaning of Git terms.
It should be clear that the word "remote" is used inconsistently and incorrectly in the Git documentation. I also argue that the word "remote" is too overloaded and over used.
I won't give every example where remote is over used, but I'll present a couple.
In Pro Git, Chapter 2.5, the first paragraph has 116 words, 8 of which are the word "remote". That means 6.9% of the words in a single paragraph are "remote". It's not even the same term. "Remote repository", "remote", "remote branch", and "remote-manangement skills" are the four different terms used.
In Pro Git, Chapter 3.5, the first three paragraphs contain 195 words, 17 of which are the word "remote". In this paragraph, that's an 8.7% use percentage of the word "remote". The 5 terms used are "remote reference", "remote repository", "remote branch", "remote-tracking branch", and "remote". The word "remote" is also used as part of command names like git ls-remote and git remote show. Some of the parameters for these commands also use the word "remote". And finally, we also see the refspec <remote>/<branch>.
I acknowledge that heavy usage of a word (even at 8.7%) and the various incarnations of those words are not always indicative of overloading a word too heavily or using a word too much. However, it should be a red flag that so many terms depend upon a single word.
And by reading the Pro Git documentation, the man pages, and the glossary, it becomes very clear that the word "remote" is indeed too heavily overloaded and too overused.
The git term "remote" has four major problems:
Additionally, the numerous terms that use the word "remote" (like "remote branch" or "remote reference") often: