So far, everything you've done with Git has happened inside one repository on your computer. Real projects live in several places at once: your laptop, a teammate's computer, and a shared copy on a server such as GitHub. Each of those other copies is called a remote.
Git keeps track of what each remote looked like the last time you talked to it, using special remote-tracking branches such as origin/main. Three commands move work between your repository and a remote: git fetch downloads new commits, git pull downloads and combines them with your work, and git push uploads your commits.
Understanding how these fit together removes most of the confusion people feel about "ahead", "behind", "diverged" and "rejected". This lesson focuses on Git's side of the story; the GitHub push and pull lesson covers creating the repository on GitHub and signing in.
Remotes
A remote is simply a name for another repository's address:
git remote -v
git remote add origin https://github.com/samlee/portfolio.git
git remote rename origin github
git remote remove old-server- origin is the conventional name for the main remote, and
git clonesets it up for you. - upstream is the usual name for the original project when you've forked it.
- A repository can have several remotes, for example your fork and the original project.
Remote-tracking branches
When you fetch from a remote, Git updates remote-tracking branches such as origin/main. They're read-only bookmarks showing where each branch was on the remote at your last fetch. You can look at them, compare with them and merge them, but you don't commit to them directly.
Your local main usually has origin/main set as its upstream. That relationship is what lets git status say:
Your branch is ahead of 'origin/main' by 2 commits."Ahead" means you have commits the remote doesn't; "behind" means the remote has commits you haven't integrated yet. When both are true, the branches have diverged.
fetch versus pull
git fetchdownloads new commits and updatesorigin/main, but doesn't touch your own branches or files. It's always safe.git pullisgit fetchfollowed by integratingorigin/maininto your current branch, by merging or, if configured, rebasing.
Fetching first lets you look before you combine: git log --oneline main..origin/main lists the commits waiting for you, and git diff main origin/main shows the changes. Many experienced developers fetch often and pull deliberately.
Pushing branches
git push -u origin feature-login # first push; set the upstream
git push # later pushes
git push origin --delete feature-login-u (--set-upstream) links your local branch to the new remote branch, so plain git push and git pull know where to go afterwards. A push is rejected if the remote has commits you don't have; pull first, combine the work, then push again. Delete a remote branch once its pull request has been merged, and run git fetch --prune to remove stale remote-tracking branches from your list.
Git Remotes Syntax
Remote commands
git remote -v
git remote add <name> <url>
git fetch [--prune]
git pull
git push -u origin <branch>
git push origin --delete <branch>
git branch -vv # show upstreams, ahead/behind
git log main..origin/main # commits you don't have yetGit Remotes Summary
- A remote is a named address of another repository;
originis the usual main one. - Remote-tracking branches like
origin/mainrecord the remote's state at your last fetch. git fetchdownloads safely;git pullfetches and integrates into your branch.git push -u origin branchpublishes a branch and sets its upstream.- Ahead, behind and diverged describe your branch compared with its upstream.
Git Remotes Examples
Each example shows the code, the output it produces and what each part does.
Fetch, look, then merge
git fetch
git status
git log --oneline main..origin/main
git merge origin/mainFrom https://github.com/samlee/portfolio
9d41e07..b38e0f5 main -> origin/main
On branch main
Your branch is behind 'origin/main' by 2 commits, and can be fast-forwarded.
b38e0f5 Update README with screenshots
a17c4d2 Fix footer link on mobile
Updating 9d41e07..b38e0f5
Fast-forward
README.md | 6 ++++++
footer.html | 2 +-
2 files changed, 7 insertions(+), 1 deletion(-)Line-by-line explanation
- Line 1Download new commits; only origin/main moves.
- Line 2status compares main with its upstream and reports that you're behind.
- Line 3List exactly which commits you'd be bringing in.
- Line 4Integrate them. That's what git pull would have done in one step.
Ahead, behind and upstreams at a glance
git branch -vv dark-mode 52ac9e1 [origin/dark-mode: ahead 1] Add dark colour scheme
* main b38e0f5 [origin/main] Update README with screenshots
spike 0f3e1a9 Try a new layoutLine-by-line explanation
- Line 1-vv shows each local branch, its upstream and how far ahead or behind it is. dark-mode has one commit to push, main is in sync, and spike has no upstream at all.
Publishing and cleaning up a branch
git switch -c footer-links
git commit -am "Add social links"
git push -u origin footer-links
# ...pull request merged on GitHub...
git switch main
git pull
git branch -d footer-links
git push origin --delete footer-links
git fetch --prunebranch 'footer-links' set up to track 'origin/footer-links'.
Deleted branch footer-links (was a51f8c2).
To https://github.com/samlee/portfolio.git
- [deleted] footer-linksLine-by-line explanation
- Line 3The first push of a new branch uses -u to set its upstream.
- Lines 5 to 6After the merge, update main.
- Lines 7 to 8Delete the branch locally and on the remote.
- Line 9--prune removes remote-tracking branches that no longer exist on the server.
Common Git Remotes Mistakes
Thinking fetch updates your files
git fetch
# "why haven't my files changed?"git fetch
git merge origin/main # or simply: git pullPushing a new branch without -u
git push
# fatal: The current branch footer-links has no upstream branch.git push -u origin footer-linksForce-pushing after a rejected push
git push --forcegit pull
git pushGit Remotes in Real Projects
Remotes in team workflows
Open-source contributors usually have two remotes: origin for their own fork and upstream for the original project, and they regularly git fetch upstream to stay current. Continuous integration servers clone and fetch repositories on every push, and deployment tools watch a remote branch such as main and release whatever is pushed there.
Git Remotes FAQ
How do I change the URL of a remote?
Run git remote set-url origin <new-url>, for example when a repository is renamed or you switch from HTTPS to SSH. Check the result with git remote -v. Your branches and history aren't affected.
What does "Your branch is ahead of 'origin/main' by 2 commits" mean?
You have two commits on your local main that the remote doesn't have yet. Run git push to send them. If it says "behind", the remote has commits you don't have, and git pull will bring them in.
How do I work on a branch that only exists on the remote?
Run git fetch, then git switch feature-name. If exactly one remote has a branch with that name, Git creates a local branch that tracks it, so git pull and git push work straight away. You don't need to create the branch yourself first.
Why does git branch -r still show branches deleted on GitHub?
Remote-tracking branches are only updated when you fetch, and a normal fetch doesn't remove them. Run git fetch --prune to delete the ones whose branches are gone. git config --global fetch.prune true makes every fetch do this automatically.
Can a repository have more than one remote?
Yes. Add another with git remote add backup <url> and refer to it by name, as in git push backup main or git fetch upstream. Contributors to open-source projects usually have origin for their own copy and upstream for the original project.
Git Remotes Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Complete the command that downloads new commits without changing your files.
git What is origin/main?
What does git pull do?
git status says "Your branch is ahead of 'origin/main' by 3 commits." What should you do to share them?
What's safer than git push --force when you must update your own rebased branch?
Git Remotes Quiz
5 questions to check what you learned.
Which command lists your remotes and their URLs?
- git remote list
- git remote -v
- git origin
- git show remotes
What does "diverged" mean?
- Your branch has been deleted
- Both your branch and its upstream have commits the other doesn't have
- You have no remote
- The branch has conflicts
What does
-udo ingit push -u origin feature?- Updates all branches
- Undoes the push
- Sets origin/feature as the upstream of your local feature branch
- Uploads untracked files
What does
git fetch --prunedo?- Removes remote-tracking branches that no longer exist on the remote
- Deletes your local branches
- Shrinks the repository
- Removes old commits
What does
git log main..origin/mainshow?- Your commits that aren't pushed
- Every commit in the repository
- Commits on both branches
- Commits on origin/main that your main doesn't have yet