In our continued quest to document everything we can about Git in a way that helps out anyone looking to learn, we come to the remote.
You may have heard of remotes, or even seen the commands necessary to add a new one to your repo. But do you know what it means to do so, and how to use them? If not, let’s dig in, and you can learn what you need to know.
What is a Remote?
When you save or commit a project using Git, you’re putting the current state of that project in one place, known as a repository. While we often think of repositories as project pages on a site like GitHub, the truth is, a repository can be anywhere, up to and including stored on your local machine. In fact, most developers keep a local repository, and commit to the public repository only sporadically as necessary to collaborate.
If you have a local repository, and a repository stored on GitHub, you have two different repositories. One is local to you, and the other is remote, in the traditional definition of the word. But, is that what a Git Remote is? Not quite.
In git parlance, a remote is not the repository itself. Rather, it's like a bookmark in your git system. When you make changes to your project and you want to commit those changes, you can stick to your local repository and then push those changes to a remote repository.
The actual process of adding a remote doesn’t create a new repository. All it does is create a shortcut, a quick reference, to an existing remote repository within your git configuration. This way, instead of having to know and type in the URL of the remote repository you want to commit to, you can simply commit to the remote.
In a way, it's like DNS registration. Where DNS associates an IP address and a domain name so you can type a simple domain rather than a string of characters for an IP, a git remote allows you to type a simple name rather than a string in a URL.
One important note is that a remote doesn’t *have *to be on a web server or network. It can, in fact, just be a secondary repository elsewhere on your local machine. All that matters is that it’s somewhere other than your primary local repository. A git remote repository is often a use case for internal development, with the repository located on a company’s internal network, rather than anywhere public like an open GitHub repo.
What do you need to add a new Git remote?
To add a new git remote, you need a local repository. You also need to have a remote repository, which could be a GitHub repo, a repo on a local network, or any other location. Learning how to initialize a new repo, either for your local copy or your remote copy, is a subject for another day.
You also need pieces of data.
The first is the name you want to use to reference your remote repository. The name you choose can be anything you like, but you should pick something that is easy to remember and descriptive enough to use as a memorable name. Git’s default name is Origin, for example.
Why is git’s default name for a remote repository “Origin”? This is because of the most common use case for remote repositories.
Typically, when you’re joining a project as a developer, there will be a repository stored somewhere like GitHub or on a network share for your internal development. You won’t be working on or committing to that repository, however; you will instead clone that repository so you have a local copy of the code base from which to work.
Most of the work you do, then, will commit to your local copy. However, when it comes time to share your code with others, you can push it to the original repository you cloned. You can also pull data from that repository to sync with your local copy to reflect changes made by others. This is all a major part of why git was invented in the first place.
The first remote you’re likely to create, then, is a remote that acts as a bookmark to the remote repository from which your local copy originated. In other words, the *origin *of your code. Thus, origin is the default name.
The second thing you need is the remote repository URL. This can be in one of two forms: as an HTTPS URL, or as an SSH URL. GitHub’s examples are:
HTTPS:
https://github.com/user/repo.gitSSH:
git@github.com:user/repo.git
It does not matter which you use, as long as SSH is active. If SSH doesn’t work, using HTTPS is a more consistent option. As long as access exists, the remote will work when used in other git commands.
How to add a new remote
The actual process for adding a new remote is simple, as long as you have all of the above. The command is thus:
$ git remote add [name] [url]
As an example, then:
# Define a new Remote
$ git remote add ProjectOne https://github.com/companyname/ProjectOne.git
Once you run this command, your new remote, named ProjectOne, will be created in your local configuration. Note that the name [ProjectOne] is a replacement for [Origin] and can be whatever name you want it to be. Origin is a good name for the source of your code, but in development environments where you’re working with multiple projects with multiple origins, using Origin for all of them has the potential to be confusing. Or, by keeping it standardized and using Origin for the source you pull from and commit to, it may be more consistent. It’s up to you, your habits, and any directives from your management.
Since it’s always a good idea to check your work, you can verify the remotes that have been added to your configuration. The command for this is also simple:
$ git remote -v
When you run this command, you’ll receive an output that lists the name, URL, and accepted commands. For our example above, you would receive:
ProjectOnehttps://github.com/companyname/ProjectOne.git(fetch)ProjectOnehttps://github.com/companyname/ProjectOne.git(push)
If you have more than just the one remote defined, you will get more than one set of validations back. For example, if you have a second remote defined with a different repo, you might receive:
ProjectOnehttps://github.com/companyname/ProjectOne.git(fetch)ProjectOnehttps://github.com/companyname/ProjectOne.git(push)ProjectOneMirrorhttps://github.com/companyname/ProjectOne.git(fetch)ProjectOneMirrorhttps://github.com/companyname/ProjectOne.git(push)
If you’re defining a large number of remotes to a large number of repos, this can get confusing, but that’s the nature of asking for lists of things.
How to use a remote in Git
Using a remote is easy. Any time you would push to, pull from, commit to, or otherwise interact with a repository, instead of typing in the whole URL of the repository, you simply type in the name of the remote.
Say, for example, that you want to fetch the ProjectOne repository found at https://github.com/companyname/ProjectOne.git. There are two ways to do that. The first is:
$ git fetch https://github.com/companyname/ProjectOne.git
This involves typing a 45-character string. It might not seem like much, but if you get something wrong – like HTTP instead of HTTPS, or accidentally typing github, or even in some cases getting the cases wrong (i.e. projectone instead of ProjectOne) – the request will fail. So, instead:
$ git fetch ProjectOne
This does the exact same thing as the 45-character string URL, except instead of a long string with numerous possible chances of making a mistake, you have a simple short name that counts as the URL for all purposes.
Cloning a repository automatically adds the source repository as a remote under the name Origin. Commands like pushing and pulling can use a remote name instead of a URL as necessary. Consider it as a simple replacement for the URL and you can do anything you would with the URL using the remote reference instead.
Inspecting a remote
If you are inheriting a project or have remotes you aren’t sure what they are or what they reference, you can inspect a remote.
The command to do so is:
$ git remote show [name]
This will show you the name, fetch URL, push URL, head branch, remote branches, branch configurations, and local reference configurations for the repository at the other end. There may be very little information there, or quite a bit more, depending on how large, complex, and active the project is.
Renaming a Remote
If you’ve decided that you don’t like the name of a remote – for example, if you keep typing the name incorrectly, or if the name you assigned it no longer applies – you can change the name of a remote.
This, too, is quite simple:
$ git remote rename [oldname] [newname]
So, to rename ProjectOne into your team’s official name for it, Brandname, you would use:
$ git remote rename ProjectOne Brandname
Conveniently, if you have any remote-tracking branches, those will change automatically. You don’t have to go through and painstakingly rename them all.
Removing a Remote
Similarly, it’s also easy to remove a remote if that remote is no longer valid or necessary. For example, maybe the server source has been changed, or you’re no longer using a specific mirror, or the contributor you were relying on is no longer active, you can remove the remote. This helps with the issue we mentioned above, where the list of remotes gets long and unwieldy.
All you need to do is this:
$ git remote remove [name]
This does also delete any remote-tracking branches or settings, so make sure you’re certain you want to do so before you execute the command. You can always recreate the remote, but you can’t undo the deletion, so you would then have to go through and re-add the remote-tracking branching or additional configuration settings, as necessary.
Troubleshooting Remote Issues
One of the most common issues you might get when trying to add a remote is the error:
fatal: remote origin already exists.
For those who aren’t familiar with the name Origin, and haven’t read our sidebar above, you might be confused. Does this mean the remote source already exists, so you can’t add the remote? In fact, no; all it means is that there is already a remote named Origin already. Since this is added automatically when you close a repository, it exists without you having created it.
To solve this issue, really all you need to do is ignore it. A remote you don’t use doesn’t hurt anything. However, if it’s disruptive, you can fix the problem. Start by verifying your remotes as mentioned above, to see what the URLs are for the existing origin remote. Then make your decision.
Do you need a new remote referencing another URL? If so, simply add a new remote under another name. As long as you know what the name is, it will work just fine; there’s nothing inherently special about the name Origin, and it functions identically to any other remote.
Do you want to keep the existing Origin remote, but have a different remote named Origin? In this case, you can rename the existing Origin remote to something else, and create a new remote named Origin to serve your needs.
Do you not need the Origin remote at all? You can simply delete it. You can then add a new Origin remote if you prefer, or add a remote under a different name, or even choose not to use remotes at all if you don’t want to use them. There’s no wrong way to use Git in this case.
Making the Most of Git
Do you want to streamline, simplify and speed up git use? Do you want to pull ahead of your peers, or get institutional buy-in to improve your processes? Whatever the choice is, we’re here for you.
At Graphite, we’ve developed a fully GitHub-integrated platform to parallelize review and development, cutting down on the time you spend managing your repos and giving you more time to dedicate to building the code you want to create.
It’s super simple to get started, and you can read all about our features here. We look forward to working with you!
