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.

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
# 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# 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 onlygit 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
| Command | Reads | Writes | Working tree |
|---|---|---|---|
git init | nothing | .git/ skeleton | Created, empty |
git clone | remote refs | full history, origin, tracking refs | Checked out |
git clone --depth 1 | one commit | shallow boundary in .git/shallow | Checked out |
git fetch | all remote refs | remote-tracking refs | Untouched |
git pull | remote branch | fetch, then merge or rebase | Changed |
git push | local refs | remote refs | Untouched |
git remote prune | remote ref list | deletes stale tracking refs | Untouched |
| Ref | What it is | Moves when |
|---|---|---|
main | Local branch | You commit, merge, reset |
origin/main | Remote-tracking branch, local copy of where origin was at last fetch | git fetch, git push |
origin/HEAD | Symbolic ref naming the remote's default branch | git remote set-head -a |
upstream/main | Same, for a second remote | git fetch upstream |
HEAD | Current commit, usually via the current branch | switch, 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:
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 filesCheck 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:
git fetch --unshallow # full history
git fetch --depth=50 # deepen to 50 commits
git fetch --deepen=20 # go 20 moreCI 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:
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/logingit 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:
git fetch origin
git rebase -i origin/main
git push --force-with-lease origin feature/loginIf 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:
git remote set-url origin https://github.com/org/new-name.git
git fetch --prune
git remote set-head origin -aSubmodules 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
| Symptom | Cause | Fix |
|---|---|---|
| "fatal: no upstream branch" | Branch created locally, never pushed with -u | git 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 constantly | Default merge strategy on a shared branch | git config --global pull.ff only |
| Shallow clone breaks blame or describe | History truncated | git fetch --unshallow |
| Push rejected after a rebase | Remote has diverged | --force-with-lease after fetching |
origin/HEAD points at a deleted branch | Default branch renamed on the remote | git remote set-head origin -a |
| Feature branch pushed to the wrong remote | upstream and origin swapped | git remote -v, then push -u origin |
| Master created instead of main | init.defaultBranch unset | git branch -m master main, then update the remote |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.