Git keeps the full history on every machine, which works fine until a second person joins the project. Then somebody has to decide where the agreed version lives. That place is the remote repository, a Git repository on a server or network that holds a shared copy of the project’s commit history. Contributors push, fetch, and pull against it, so the history survives outside any one developer’s laptop.
Plenty of teams use GitHub, GitLab, Bitbucket, or Azure DevOps for this. Others run their own server.
According to the Pro Git documentation, Git reaches a remote over 4 transfer protocols (Local, HTTP, SSH, and Git). The URL stored for the remote decides which one carries the data.
What Is a Remote Repository?
Most people just say “remote”. When someone tells you to push to the remote, they mean send your commits to the hosted repository.
It’s an ordinary repository that happens to sit somewhere else, with the same branches, commits, and tags as the one on your laptop. It is not an automatic backup, because nothing reaches it until someone pushes. Pro Git adds that each contributor gets either read-only or read/write rights.
The word describes position, not distance. A directory on your own machine counts, and Pro Git notes it still goes through the standard push, pull, and fetch operations.
Git is distributed, so no central server is required. Pro Git still calls an intermediate repository the preferred way to collaborate. Pushing into a colleague’s working repository can confuse whatever they’re in the middle of, and a shared copy stays reachable when their laptop is offline.
Once you have more than one contributor, version control needs a shared reference point. The remote is that point.
How Does a Remote Repository Differ From a Local Repository?
A local repository sits on your machine and comes with a working tree you edit. The remote sits on a server and usually holds only the version data.
| Aspect | Local repository | Remote repository |
|---|---|---|
| Location | Your own machine | Server or shared network path |
| Working tree | Yes, checked-out files you edit | Usually none (bare) |
| Access | You, unless you share it by hand | Several people, with per-person rights |
| Offline use | Commits work without a connection | Unreachable when the network is down |
| Purpose | Daily edits and commits | Exchange point between contributors |
Your side is a standard Git repository, meaning checked-out files plus a hidden .git folder. The remote keeps just the folder.
Why a remote usually has no working tree
Nobody edits files on the server, so a checked-out snapshot would have no purpose. Pro Git calls this format a bare repository, which is the contents of the project’s .git directory and nothing else.
git init --bare starts an empty remote. git clone --bare copies an existing local repository into one.
Where Can You Host a Remote Repository?
Managed platforms take the maintenance off your hands, and you give up some control in return. Self-hosting reverses that deal.
Hosted platforms
Stack Overflow’s 2025 Developer Survey put regular GitHub use at 81.1% of 30,065 respondents, with GitLab at 35.6% and Azure DevOps at 16.6%.
- GitHub had 630 million repositories at the close of GitHub’s Octoverse 2025 window (August 31, 2025).
- GitLab is hosted by GitLab, or you can install it on your own server.
- Bitbucket is Atlassian’s service and sits comfortably beside Jira.
- Azure DevOps is Microsoft’s, with repositories next to boards and pipelines.
GitHub wraps pull requests and issue tracking around each repository, which makes it the default pick for open source work. Outside contributors already have accounts there, so the first hurdle is gone.
Self-hosted servers
You get control over where the data lives, and you pay for it with upkeep. The simplest setup is a bare repository on any server with SSH access. Gitea is a lightweight self-hosted Git service, and GitLab can run on your own hardware too.
Gitea’s documentation says a Raspberry Pi 3 can run it for small workloads, so a private remote for a small team costs very little to start.
The catch is that backups, updates, and uptime become your job. Pro Git has a sharper warning for the simplest setup. If everyone logs in to one computer, every repository instance lives on that machine, and a single disk failure takes all of them.
How Do Remote Names and URLs Identify a Remote?
Each remote is stored as a short name plus a URL. The name is a local alias you type, and the URL tells Git where the server is and which protocol to speak.
Remote names
Cloning creates a remote called origin automatically. Pro Git describes it as the default name Git gives the server you cloned from.
The name lives only in your local repository. Run git remote rename and every remote-tracking branch name changes with it, so pb/master becomes paul/master.
Fork workflows add a second name. By convention, upstream points at the original repository you forked from, and origin points at your own fork.
Remote URL formats
git remote -v prints the URL stored for each name, one line for fetch and one for push.
- HTTPS looks like https://github.com/schacon/ticgit.
- SSH is written as git@github.com:mojombo/grit.git, or in the longer form ssh://[user@]server/project.git.
- A local path is just /srv/git/project.git.
- The git:// protocol has no authentication and is served on dedicated port 9418.
Pushing over HTTP only became practical with Smart HTTP in Git 1.6.6. Before that release, HTTP remotes were generally read-only.
Pro Git warns against cloning over git:// unless you know what you are doing. There is no encryption, so an attacker who controls the network can alter the repository you receive.
Working with more than one remote
One local repository can hold several remotes at once. Pro Git’s own example lists five in a single repository (bakkdoor, cho45, defunkt, koke, and origin), each pointing at a different collaborator’s copy.
Each one is read-only or read/write for you, and git remote -v doesn’t say which. Fork workflows lean on this split. You pull from upstream and push to origin.
How Do Clone, Fetch, Pull, and Push Move Data?
Clone copies the whole repository and creates the remote. Fetch downloads new commits without touching your files, pull is fetch plus a merge, and push uploads your commits to a remote branch. Every one of them moves data in a single direction.
| Command | Direction | What it updates | Edits your files |
|---|---|---|---|
| clone | Remote to local | New repository, origin, origin branches | Yes, new checkout |
| fetch | Remote to local | Remote-tracking branches | No |
| pull | Remote to local | Remote-tracking branches, then your current branch | Yes, through the merge |
| push | Local to remote | The branch on the remote | No |
Clone
Cloning pulls down all the data and creates a local copy of the remote’s default branch, starting at the same commit as the remote’s.
The remote name is a default, not a rule. Pro Git notes that git clone -o booyah gives you booyah/master instead, because Git attaches no special meaning to origin.
Fetch and pull
A fetch only updates your local database. Your working directory stays exactly as it was, and you merge when you’re ready.
A pull is essentially a fetch followed immediately by a merge, in most cases. It needs a tracking branch to know which server and branch to use.
Since Git 2.27, git pull warns until the pull.rebase variable is set.
Set it to false for the default behavior (fast-forward if possible, otherwise a merge commit), or to true to rebase on pull.
Push
- The syntax is
git push origin serverfix, and Git expands the branch name to the full ref for you. git push origin serverfix:awesomebranchsends your serverfix branch to the remote’s awesomebranch.- Local branches never sync on their own, so private branches stay private until you push them.
git push origin --delete serverfixremoves the branch pointer from the server.
The server usually keeps the data until garbage collection runs, so an accidental delete is often recoverable (Pro Git).
Remote-tracking branches
These are local bookmarks showing where each remote branch stood the last time you connected.
Their names follow the form remote/branch, such as origin/main. You can’t move them yourself, because Git moves them whenever it talks to the remote.
A fetch that brings down a new remote branch gives you only the pointer. To work on it, create a local branch from it with git checkout --track origin/serverfix.
That local branch is a tracking branch, tied to a remote one. The remote branch it follows is its upstream branch, which you can also set by hand with git branch -u origin/serverfix.
An upstream branch and a remote named upstream are different things. One is a branch relationship, the other is just a remote name.
git branch -vv shows how far each branch is ahead or behind, but only as of your last fetch, because it never contacts the server. Run git fetch --all first for current numbers.
How to Connect a Local Repository to a Remote Repository
Until a remote exists, the local repository has no idea where to send commits. The fix is to create an empty repository on the host, add its URL with git remote add, and push your first branch.
- Create an empty repository on the host and copy its URL.
- In the project folder, run
git remote add origin <url>. - Run
git remote -vto verify the new remote. - Push the first branch with
git push -u origin main, which also records the upstream branch.
The command takes two arguments, a name and a URL. Pro Git’s examples use origin for the main server and short names such as pb for a collaborator’s copy.
These steps all use git remote subcommands, and the same family handles every later change.
Only step one happens in the browser. On GitHub, creating the repository is the one piece of the job done outside the terminal.
Cloning an existing remote skips steps two to four and sets up origin for you.
Changing, renaming, and removing a remote
- To change the URL, run
git remote set-url origin <new-url>. This is how you switch between HTTPS and SSH. - To rename, run
git remote rename origin destination. git remote rm destinationdeletes the remote and its remote-tracking branches from your local repository.
Removing a remote never touches the server. The hosted repository stays exactly as it was, according to GitHub Docs.
Common errors
| Error message | Cause | Fix |
|---|---|---|
| fatal: remote origin already exists | A remote with that name is already configured | Pick another name, rename the old remote, or remove it |
| fatal: No such remote | The name given to set-url does not exist | Check the spelling against the remote list |
| Could not rename config section | The old remote name does not exist | List remotes, then retry with the right name |
How Do You Authenticate With a Remote Repository?
The URL you added decides it. HTTPS remotes take a personal access token, and SSH remotes take a key pair. A token works only with HTTPS URLs and a key only with SSH URLs.
| Aspect | HTTPS | SSH |
|---|---|---|
| Credential | Personal access token in the password prompt | Private key on your machine, public key on the host |
| Setup | Create a token, cache it with a credential helper | Generate a key pair, upload the public key |
| Firewalls | HTTP and HTTPS ports are commonly open | Depends on the network allowing SSH |
| Anonymous read | Possible | Not possible, every reader needs SSH access |
| Common failure | Expired token or stale cached password | Permission denied (publickey) |
The two sources lean different ways on the default. Pro Git calls SSH ubiquitous and easy to set up, while GitHub’s own examples assume HTTPS and label it recommended.
For a hosted remote, HTTPS with a credential helper is the lower-friction start. SSH pays off once keys already live on the machine.
Personal access tokens over HTTPS
GitHub stopped accepting account passwords for Git operations on August 13, 2021, at 09:00 PST, according to its changelog. The token now goes into the password prompt. The username is still required, even though it isn’t what authenticates you.
GitHub recommends fine-grained tokens, which can be limited to specific repositories, over classic tokens, which reach every repository you can access. A walkthrough on creating a GitHub token covers the settings path.
One limit to know about. Only classic tokens have write access to public repositories you don’t own or belong to, and GitHub removes classic tokens that sit unused for a year.
SSH keys
SSH replaces the prompt with a key pair. The host stores your public key, and the private key never leaves your machine.
Adding the public key to your GitHub account is the required step after generating the pair.
The classic failure is Permission denied (publickey). It means the host holds no public key matching the one your machine offered.
Credential helpers
- With no helper, Git prompts on every connection. That’s the default.
- The cache helper keeps credentials in memory and purges them after 15 minutes by default.
- The store helper writes them to a plain-text file that never expires.
- osxkeychain and Git Credential Manager keep them in the macOS keychain or the Windows Credential Store.
Pick one with git config --global credential.helper cache. Avoid the store helper on shared machines, since the password sits in cleartext in your home directory (Pro Git).
GitHub’s documentation points people to GitHub CLI or Git Credential Manager before a hand-made token.
When Does a Remote Repository Not Fit or Fail?
A remote adds nothing to a solo project that stays on one machine. Elsewhere the usual trouble is a rejected push or an authentication error, with stale references turning up later. Each has a known fix.
Solo and offline work
If you are the only person on a project, you will probably never need a remote, according to the Tower Git ebook.
Add one when a second machine or a second contributor needs the history.
Rejected pushes
A push is refused when someone else pushed to the same branch first. GitHub’s documentation shows a non-fast-forward rejection with the line “failed to push some refs”, and Git refuses so you don’t lose history.
- Run
git fetch origin. - Merge the remote branch into yours with
git merge origin/main. - Push again.
git pull performs the first two steps at once. If both sides edited the same lines, the merge stops, and resolving merge conflicts in Git is the next job.
Authentication errors
- A password typed where the token belongs
- A token that expired or was revoked
- A classic token used against an organization that blocks classic tokens, which returns a 403
- An old password still cached in the system keychain
- A token paired with an SSH URL, or a key paired with an HTTPS one
Stale references
Remote branches deleted on the server linger locally. git remote show origin marks them as stale, and git remote prune origin removes them.
A server that moved leaves the stored URL pointing at nothing, so repoint the remote or remove it.
Remote Repository FAQ
Is a remote repository the same as GitHub?
No. GitHub is one host among many.
GitLab, Bitbucket, Azure DevOps, Gitea, or a bare repository on your own SSH server fill the same role. Git only needs a reachable URL.
Is a fork a remote repository?
Yes. A fork is a server-side copy of a repository on the host, and it gets its own URL like any other.
Clone it and it behaves as a normal remote for pushes, fetches, and pulls.
Does Git sync with the remote automatically?
No. Git moves data only when you run fetch, pull, or push, and nothing runs in the background.
Until the next network command, your local view of the remote stays frozen at the last contact.
How can I create a remote repository on my own server?
Run git init --bare project.git on a server you can reach over SSH. Collaborators then clone it with git clone user@server:project.git, as Pro Git documents.
Every contributor needs SSH access to that machine, even for read-only work.
What does git ls-remote do?
It lists the references on a remote, such as branches and tags, without downloading any data.
For branch details plus tracking information, git remote show followed by the remote name goes further.
How do I back up a remote repository?
Every clone already holds the full commit history, so each contributor’s machine is a working copy of it. For a deliberate backup, add a second remote on a different host and push to both.
On a self-hosted server, backups remain your responsibility.
What to Configure First on a Shared Remote Repository
Settle access rights before the second contributor pushes. A token can never exceed its owner’s access, so rights set the ceiling for everything else (GitHub Docs).
Per-person rights come first, read-only by default. Next are fine-grained tokens scoped to the repository, each with an expiry date. A second remote on a different host comes last.
Scoped tokens narrow the ceiling, and the second remote covers loss on the host itself.
Expiring tokens trade convenience for a smaller exposure window, and each needs renewing before its date.
As of October 1, 2026, GitHub’s documentation lists gaps that keep classic tokens necessary for some work, and says it is closing them. Once they close, the case for a classic token narrows, though a few REST API endpoints still accept only classic tokens.
With access settled, a Git workflow decides who pushes to which branch.
- MongoDB Cheat Sheet - October 20, 2026
- Adding AI Video Generation to a Software Product: Architecture, Cost Guardrails and QA - October 20, 2026
- Show Hidden Characters, Spaces, and Line Endings in Notepad++ - October 19, 2026
