GitAdding a Remote

Adding a Remote

Adding a remote tells your local Git repository about another copy of itself living elsewhere — usually on GitHub, GitLab, or a server you control. After adding the remote you can push to it, fetch from it, and treat its branches as first-class references.

The command

Bash
git remote add <short-name> <url>

  • <short-name> — a label you choose. Conventionally origin for the main remote, upstream for the upstream of a fork.

  • <url> — the location of the remote — an HTTPS URL, SSH URL, or path.

Example 1: Connect a brand-new local repo to GitHub

Bash
# You did 'git init' and made some commits locally.
# Now create an empty repo on GitHub (don't add README).

# Tell Git where to push
git remote add origin git@github.com:you/my-new-project.git

# Push and set upstream
git push -u origin main

# Future pushes:
git push
Example 2: Add an upstream to a fork

Bash
# You forked the project on GitHub and cloned YOUR fork
git clone git@github.com:you/awesome-lib.git
cd awesome-lib

# Add the canonical repo as 'upstream'
git remote add upstream https://github.com/original-author/awesome-lib.git

git remote -v
# origin    git@github.com:you/awesome-lib.git (fetch)
# origin    git@github.com:you/awesome-lib.git (push)
# upstream  https://github.com/original-author/awesome-lib.git (fetch)
# upstream  https://github.com/original-author/awesome-lib.git (push)
Example 3: Multiple deployment targets

Bash
git remote add production deploy@prod.example.com:project.git
git remote add staging    deploy@staging.example.com:project.git

git push staging main
git push production main
HTTPS vs SSH URLs

  • HTTPS (https://github.com/...) — works through firewalls, authenticated by Personal Access Token. Easier for beginners.

  • SSH (git@github.com:...) — uses your SSH key. No passwords, no token expiry. Preferred by most experienced developers.

Switching protocols after the fact

Bash
git remote set-url origin git@github.com:user/repo.git
Verifying the remote works

Test connectivity without changing anything

Bash
git ls-remote origin
# Lists all branches and tags on the remote
# If you see them, the remote is reachable AND you're authenticated
Common errors

  • fatal: remote origin already exists — you already have an origin. Use git remote set-url origin <url> to update it, or pick a different short name.

  • Permission denied (publickey) — SSH key isn’t on the remote host. Generate one or switch to HTTPS.

  • could not resolve host — typo in the URL or no internet. Re-check.

  • Repository not found — wrong URL, or the repo is private and you lack access.

Choosing a short name

  • origin — the conventional name for the “main” remote.

  • upstream — the canonical repo when you’re working from a fork.

  • production, staging — deployment targets.

  • backup, mirror — secondary copies for redundancy.

Short names are just labels
You can call your remote anything: `hub`, `home`, `github`, `gitlab`. The convention `origin` is purely cosmetic — Git does not treat it specially.
One-liner setup for a new repo

From empty folder to pushed-to-GitHub in 5 commands

Bash
git init -b main
echo "# My Project" > README.md
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:you/my-project.git
git push -u origin main
Tip
After adding a remote, always run git remote -v to confirm the URL looks right. A typo in the URL produces confusing errors much later.