Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Remote and Upstream Tracking: init, clone, and Branch Relationships

An upstream is a config line, not a copy of a branch. Why pull refuses to run, what a shallow clone breaks, and how origin and upstream differ in a fork.

~4 min readGit
#Git#Remote#Branching#CLI
3D illustration of a local repository cube connected by a cable to a cloud remote cube

Quick Summary

A Git repository is a set of refs pointing at commits, plus a config that says which remote ref each local branch follows. git init creates the refs; git clone creates them from a remote and records origin; git remote add records a URL without touching history. An upstream is not a copy of a branch — it is a line in .git/config mapping refs/heads/main to refs/remotes/origin/main, and almost every confusing push or pull message comes from that line being absent or pointing somewhere unexpected.

git push -u origin main does two things: it pushes, and it writes branch.main.remote and branch.main.merge. Without them git pull refuses to run with "no tracking information", and git push falls back to push.default=simple, which refuses when branch names differ.

Since Git 2.28, init.defaultBranch decides the first branch name; before that it was a hard-coded master with a hint printed on every init. In a new repository on 2.40+, git init -b main is the explicit way to avoid inheriting a laptop-wide setting.

Basic Syntax & Core Signatures

bash
# New repository with an explicit initial branch git init -b main git init --bare /srv/repos/app.git # server side, no working tree git config --global init.defaultBranch main # set once, applies everywhere # Clone variants git clone https://github.com/org/app.git git clone --depth 1 --branch release/2.4 https://github.com/org/app.git git clone --single-branch --branch main git@github.com:org/app.git app-main git clone --recurse-submodules --shallow-submodules git@github.com:org/app.git # Remotes git remote add origin git@github.com:me/app.git git remote add upstream https://github.com/original/app.git git remote set-url origin git@github.com:me/app-renamed.git git remote rename origin upstream git remote remove old-origin git remote -v git remote prune origin # delete stale remote-tracking refs git remote set-head origin -a # refresh origin/HEAD to the remote's default branch # Tracking branches git push -u origin feature/login # push and set upstream git branch --set-upstream-to=origin/main main git switch --track origin/release/2.4 # create local branch from a remote branch git switch -c local-name origin/remote-name git branch -vv # show upstream and ahead/behind
bash
# Fetch vs pull: fetch never touches your working tree git fetch --all --prune git fetch origin main:refs/remotes/origin/main git pull --ff-only # refuse to create a merge commit git pull --rebase # replay local commits on top git config --global pull.ff only

git push -u is a convenience for the first push of a branch only. Subsequent pushes need no arguments once branch.<name>.remote and branch.<name>.merge exist.

Key Comparison Table

CommandReadsWritesWorking tree
git initnothing.git/ skeletonCreated, empty
git cloneremote refsfull history, origin, tracking refsChecked out
git clone --depth 1one commitshallow boundary in .git/shallowChecked out
git fetchall remote refsremote-tracking refsUntouched
git pullremote branchfetch, then merge or rebaseChanged
git pushlocal refsremote refsUntouched
git remote pruneremote ref listdeletes stale tracking refsUntouched
RefWhat it isMoves when
mainLocal branchYou commit, merge, reset
origin/mainRemote-tracking branch, local copy of where origin was at last fetchgit fetch, git push
origin/HEADSymbolic ref naming the remote's default branchgit remote set-head -a
upstream/mainSame, for a second remotegit fetch upstream
HEADCurrent commit, usually via the current branchswitch, checkout, commit

Practical Edge Cases & Deep Dives

1. Cloning into an existing directory

git clone url . fails unless the directory is empty. The workaround that actually preserves files is init-then-fetch, which also lets you keep an existing .env:

bash
git init -b main git remote add origin git@github.com:org/app.git git fetch origin git switch -f -c main origin/main # -f discards conflicting local files

Check git status before the switch -f. Untracked files that collide with tracked paths will be overwritten by -f, and there is no prompt.

2. Shallow clones and later history

--depth 1 writes .git/shallow, and commands that need history — git log --follow, git blame across the boundary, git describe, merge-base for a rebase — fail or return wrong answers. Deepen rather than re-clone:

bash
git fetch --unshallow # full history git fetch --depth=50 # deepen to 50 commits git fetch --deepen=20 # go 20 more

CI pipelines that shallow-clone and then run git describe --tags fail with "No names found" for exactly this reason.

3. Fork workflows: origin versus upstream

The convention is origin = your fork, upstream = the project you forked. Pushing to upstream is normally a permission error, and pulling from origin gives you your own stale branch. The working loop syncs main from upstream and rebases your branch on it:

bash
git fetch upstream git switch main git merge --ff-only upstream/main git push origin main git switch feature/login git rebase main git push --force-with-lease origin feature/login

git remote set-head origin -a fixes a fork whose default branch was renamed upstream and now shows the wrong origin/HEAD target in git branch -r.

4. push.default, same-name branches, and the first-push asymmetry

With push.default=simple (the default since 2.0), git push refuses when the local branch name differs from the upstream branch name. git config --global push.default current makes git push create origin/<your-branch-name>, which is convenient for feature branches and dangerous on a shared repository where you intended to push to main.

git push -u origin HEAD is the branch-name-agnostic form: it pushes the current branch and sets upstream in one step. Use it in scripts instead of hard-coding main.

5. --force-with-lease and the remote you did not fetch

After a rebase, a plain --force overwrites whatever is on the remote, including a colleague's commit pushed since your last fetch. --force-with-lease refuses unless the remote ref still matches your remote-tracking ref:

bash
git fetch origin git rebase -i origin/main git push --force-with-lease origin feature/login

If the lease fails, someone else pushed. Fetch, inspect with git log HEAD..origin/feature/login, and decide whether to rebase again rather than forcing.

6. Changing protocols and hosts without re-cloning

An SSH-to-HTTPS switch, a repository rename, or a mirror move is a URL change plus a ref refresh:

bash
git remote set-url origin https://github.com/org/new-name.git git fetch --prune git remote set-head origin -a

Submodules keep their own remotes; .gitmodules must be updated and git submodule sync --recursive run, or the submodule keeps fetching from the old URL.

A remote whose URL is correct but unreachable is usually an SSH key or credential-helper problem, not a URL problem. GIT_SSH_COMMAND="ssh -v" git fetch origin shows the handshake, and git config --show-origin --get-all credential.helper shows which store is answering — two remotes with different hosts can end up using the same stored token, and the error names the host rather than the credential.

Common Git Operation Mistakes

SymptomCauseFix
"fatal: no upstream branch"Branch created locally, never pushed with -ugit push -u origin HEAD
"refusing to merge unrelated histories"Two git init histories joined--allow-unrelated-histories, or re-clone
git pull creates merge commits constantlyDefault merge strategy on a shared branchgit config --global pull.ff only
Shallow clone breaks blame or describeHistory truncatedgit fetch --unshallow
Push rejected after a rebaseRemote has diverged--force-with-lease after fetching
origin/HEAD points at a deleted branchDefault branch renamed on the remotegit remote set-head origin -a
Feature branch pushed to the wrong remoteupstream and origin swappedgit remote -v, then push -u origin
Master created instead of maininit.defaultBranch unsetgit branch -m master main, then update the remote

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.