GitoryxA Git remote is a reference to a copy of your repository hosted elsewhere — GitHub, GitLab, Bitbucket, or your own server. This guide explains how to add, inspect, rename, and remove remotes, and how remote tracking branches work.
You've initialized a local repository and written some commits, but you have no idea how to connect it to GitHub or push your work anywhere. Or you're trying to pull from a second remote and Git says it doesn't know where to look.
Remotes are the bridges between your local repository and the rest of the world. Understanding how to add, list, and manage them is essential for any collaborative workflow — whether you're pushing to GitHub, pulling from an upstream fork, or working with multiple team servers.
Common mistakes developers make with this:
git init, then being unable to pushorigin (your fork) with upstream (the original project)origin/main are just local snapshotsGitoryx: Gitoryx lists all your remotes in the sidebar, shows their tracking branches in the commit graph, and lets you fetch, pull, or push to any remote in one click.
A Git remote is a named reference to a repository hosted somewhere else — GitHub, GitLab, Bitbucket, or any server. The most common remote is origin, which Git creates automatically when you clone a repository.
Start by checking what remotes are already configured in your repo.
git remote -v
# origin git@github.com:user/my-project.git (fetch)
# origin git@github.com:user/my-project.git (push)If you cloned the repo, origin is already set. If you ran git init, there are no remotes yet.
Connect your local repo to a remote repository. origin is the conventional name for your primary remote.
git remote add origin git@github.com:user/my-project.git
# Verify:
git remote -vWhen working with a forked project, add the original repository as upstream so you can pull in updates from it.
git remote add upstream git@github.com:original-owner/my-project.git
# Fetch the upstream branches:
git fetch upstreamIf you need to rename an existing remote (e.g., from origin to github):
git remote rename origin githubRemove a remote that is no longer needed. This only deletes the reference — it doesn't delete anything on the remote server.
git remote remove upstream
See this workflow in Gitoryx. Remotes and their branches appear directly in the commit graph
Free downloadIf a repository moves, or you want to switch from HTTPS to SSH:
git remote set-url origin git@github.com:user/new-location.git
# Verify the change:
git remote -vgit remote show gives you a full picture of a remote: its URL, all tracked branches, and which local branches are configured to push/pull from it.
git remote show origin
# Output:
# * remote origin
# Fetch URL: git@github.com:user/my-project.git
# Push URL: git@github.com:user/my-project.git
# HEAD branch: main
# Remote branches:
# develop tracked
# main tracked
# Local branch configured for 'git pull':
# main merges with remote main
# Local ref configured for 'git push':
# main pushes to main (up to date)Run git remote show origin before pushing to an unfamiliar remote to confirm you're targeting the right branch.
Remote-tracking branches like origin/main are local read-only snapshots of what the remote looked like the last time you fetched. They update only when you run git fetch or git pull.
# See all remote-tracking branches
git branch -r
# origin/HEAD -> origin/main
# origin/develop
# origin/main
# Compare your local main with the remote snapshot
git log origin/main..main # commits you have locally but remote doesn't
git log main..origin/main # commits on remote that you don't have yet
# Update all remote-tracking branches without merging
git fetch --allorigin/main is NOT the same as main. It's a cached snapshot. Always git fetch before comparing branches.
After remote branches are deleted (e.g., after a merged PR), their local tracking references stick around. git remote prune cleans them up.
# See which remote-tracking refs are stale (dry run)
git remote prune origin --dry-run
# Actually remove the stale refs
git remote prune origin
# Combine fetch + prune in one command
git fetch --prune
# Or configure git to always prune on fetch:
git config --global fetch.prune truegit remote prune only removes your local tracking refs — it does NOT delete anything on the remote server. It's always safe to run.
When working on a fork, origin is your copy, upstream is the original. Pushing to upstream (if you don't have write access) fails; pulling from origin instead of upstream misses new changes from the source project.
Fix: Always confirm with git remote -v before pushing or pulling.
origin/main is a local snapshot of the remote branch. It only updates when you fetch.
Fix: Run git fetch origin to update all remote tracking branches before comparing or merging.
Git says 'The current branch has no upstream branch' when you try to push a branch for the first time.
Fix: Use git push -u origin <branch> the first time. The -u flag sets the tracking relationship.
Gitoryx — macOS & Windowsorigin is the default name Git gives to the remote from which you cloned. It's just a shorthand alias for the full remote URL. You can rename it or have multiple remotes with different names.
When you fork a project, origin is your personal fork and upstream is the original repository you forked from. You push to origin (your fork) and pull updates from upstream (the source). This is a naming convention, not enforced by Git.
git fetch downloads new data from the remote and updates remote tracking branches (like origin/main) but does not change your local branch. git pull does a fetch followed by a merge (or rebase) into your current branch.
Yes. You can add as many remotes as you need. Common setups include origin (your fork) and upstream (the original project), or multiple deployment targets like origin, staging, and production.
Use git push -u origin <branch-name>. The -u flag sets the tracking relationship so future git push and git pull commands know which remote branch to use.
A remote-tracking branch (e.g., origin/main) is a local, read-only snapshot of what a remote branch looked like the last time you fetched. It updates only when you run git fetch or git pull. Use git branch -r to list all remote-tracking branches.
Run git remote prune origin to delete local references to remote branches that no longer exist. Use git fetch --prune to do the same automatically every time you fetch. This is safe — it only removes local refs, not anything on the remote.
Run git remote set-url origin <new-url>. This is useful when switching from HTTPS to SSH, or when a repository moves. Verify the change with git remote -v.
Everything in this tutorial is faster and clearer with a visual Git client. Gitoryx is free, runs natively on macOS and Windows, and built for developers who want to move fast without breaking things.