Lesson 07 beginner

Git Remote

Working with remote repositories: clone, origin and remote-tracking branches, fetch versus pull, pushing and upstreams, ahead and behind, several remotes for forks and mirrors, pushing to remote groups (Git 2.55), and shallow and partial clones for big repositories.

So far Orbit has lived only on your laptop. A remote is another copy of the repository that you exchange commits with, usually on GitHub, GitLab or a company server. Git never syncs automatically: you decide when to download (fetch, pull) and when to upload (push). Understanding exactly what each of those does removes most of the fear people have of Git.

Cloning

git clone copies a whole repository, history included, and sets up a remote called origin that points back to where it came from:

$ git clone git@github.com:orbit-dev/orbit.git
Cloning into 'orbit'...
remote: Enumerating objects: 1240, done.
Receiving objects: 100% (1240/1240), 2.31 MiB | 8.10 MiB/s, done.
$ cd orbit
$ git remote -v
origin  git@github.com:orbit-dev/orbit.git (fetch)
origin  git@github.com:orbit-dev/orbit.git (push)

The URL can use SSH (git@github.com:...) or HTTPS (https://github.com/...). Lesson 2 explains how to authenticate with either.

Connecting an existing repository

If you started with git init, create an empty repository on the hosting service (without a README, so histories do not clash) and connect it:

$ git remote add origin git@github.com:orbit-dev/orbit.git
$ git push -u origin main

Other remote commands you will need:

$ git remote rename origin github
$ git remote set-url origin https://github.com/orbit-dev/orbit.git
$ git remote remove old-server
$ git remote show origin          # branches, upstreams and what is out of date

Remote-tracking branches

When you fetch, Git records where each branch of the remote was at that moment as a remote-tracking branch: origin/main, origin/feature/search. They are read-only bookmarks. You never commit on them; Git moves them each time you talk to the remote.

$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/fix/login-timeout

Your local main and origin/main are two different pointers. That is why you can be “ahead” or “behind”.

Fetch versus pull

CommandDownloads new commitsChanges your branch and files
git fetchYes, updates origin/*No
git pullYesYes: fetch, then merge (or rebase) into the current branch

git fetch is always safe. It lets you look before you integrate:

$ git fetch
$ git status
On branch main
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
$ git log --oneline main..origin/main     # what is new on the remote
$ git diff main origin/main               # and what it changes
$ git merge --ff-only origin/main         # now integrate

git pull does both steps at once. It is convenient when you trust what is coming, which is most of the time on main.

Pushing and upstreams

$ git switch -c fix/login-timeout
$ git commit -am "Raise login timeout to 30 seconds"
$ git push -u origin fix/login-timeout

-u sets the upstream: it links your local branch to origin/fix/login-timeout, so later a plain git push and git pull know where to go, and git status can report ahead and behind. With push.autoSetupRemote true (lesson 2), the first git push of a new branch sets the upstream for you.

$ git status -sb
## fix/login-timeout...origin/fix/login-timeout [ahead 1]
$ git branch -vv
* fix/login-timeout 8c2e01a [origin/fix/login-timeout: ahead 1] Log timeout value
  main              90bd114 [origin/main] Bump Node.js to 24

When push is rejected

$ git push
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:orbit-dev/orbit.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

Someone pushed before you. Git never overwrites their commits silently. Bring them in, then push again:

$ git pull --rebase
$ git push

Git 2.56 also catches a common typo. If you type git push origin/main (with a slash), Git now suggests git push origin main instead of failing with a confusing error.

Deleting remote branches and pruning

$ git push origin --delete fix/login-timeout   # delete the branch on the remote
$ git fetch --prune                            # forget remote branches deleted by others

With fetch.prune true set, every fetch prunes automatically. After pruning, git branch --delete-merged (lesson 4) can clean up the local branches too.

Several remotes: forks and mirrors

When you contribute to a project you cannot push to, you fork it on the hosting service and clone your fork. Add the original as a second remote, traditionally called upstream, to stay in sync:

$ git remote add upstream https://github.com/orbit-dev/orbit.git
$ git fetch upstream
$ git rebase upstream/main
$ git push origin main

Git has long supported remote groups for fetching from several remotes at once. Since Git 2.55 you can push to a group too, which is handy for keeping a mirror in sync:

$ git remote add backup git@gitlab.example.com:orbit/orbit.git
$ git config remotes.everywhere "origin backup"
$ git fetch everywhere
$ git push everywhere main

Pushes to a group run one remote after another, and --atomic cannot be used with a group.

Big repositories: shallow and partial clones

For CI jobs and huge repositories, you rarely need every version of every file:

$ git clone --depth 1 https://github.com/orbit-dev/orbit.git      # only the latest commit
$ git clone --filter=blob:none https://github.com/orbit-dev/orbit.git  # all commits, file contents on demand

A shallow clone (--depth) is the fastest for a build that only needs the current code, but commands like git log and git blame see only the truncated history. A blobless partial clone (--filter=blob:none) keeps the full history and downloads file contents only when you check them out, a good choice for developers on large monorepos.

Quick reference

TaskCommand
Copy a repositorygit clone <url>
List remotesgit remote -v
Add a remotegit remote add <name> <url>
Download without changing your branchgit fetch / git fetch --prune
Download and integrategit pull / git pull --rebase
First push of a branchgit push -u origin <branch>
Ahead and behindgit status -sb / git branch -vv
Delete a remote branchgit push origin --delete <branch>
Push to a remote group (2.55)git push <group> <branch>
Fast clone for CIgit clone --depth 1 <url>

Exercise

You want to see what teammates pushed to main without changing any of your files yet. What do you run?

  1. git pull
  2. git push –dry-run
  3. git fetch, then git log main..origin/main
  4. git clone the repository again
Show answer

Answer: C. git fetch only updates remote-tracking branches like origin/main. Comparing main..origin/main lists the new commits. git pull would merge them into your branch immediately.

Exercise

git push is rejected with “Updates were rejected because the remote contains work that you do not have locally”. What is the right next step?

  1. git push –force to replace the remote branch
  2. Integrate the remote commits with git pull –rebase (or git pull), then push again
  3. Delete your local branch and clone again
  4. Rename your branch and push it under a new name
Show answer

Answer: B. Someone pushed first. Pulling brings their commits into your branch, and then your push becomes a fast-forward. Forcing would delete their work.

Exercise

A CI job only needs to build the latest commit of a repository with 15 years of history. Which clone is the best fit?

  1. git clone –depth 1
  2. git clone –mirror
  3. git clone –filter=blob:none
  4. git clone –bare
Show answer

Answer: A. –depth 1 downloads only the latest commit, which is the fastest for a one-off build. A blobless clone still downloads the full commit history, and mirror or bare clones copy everything.

Key takeaways

  • A remote is another copy of the repository; origin is the default name for where you cloned from.
  • origin/main is a read-only bookmark of the remote branch, updated when you fetch.
  • git fetch downloads safely; git pull downloads and integrates into your branch.
  • git push -u sets the upstream; a rejected push means you must integrate others’ work first.
  • Use extra remotes for forks and mirrors, remote groups to push to several at once (2.55), and shallow or partial clones for big repositories.

FAQ

What is the difference between origin and upstream?

Both are just names. By convention, origin is the repository you cloned, often your fork, and upstream is the original project you forked from. Git gives no special meaning to either name.

Why does git status say I am up to date when the remote has new commits?

git status compares with your local copy of origin/main, which only changes when you fetch. Run git fetch first, then git status reports the real situation.

Should git pull merge or rebase?

For branches where you do not commit directly, use git pull --ff-only so nothing unexpected happens. On feature branches, git pull --rebase keeps history linear. Set your default with pull.rebase or pull.ff.

How do I see which remote branch my branch tracks?

Run git branch -vv. The upstream appears in square brackets with ahead and behind counts. Change it with git branch --set-upstream-to=origin/<branch>.

Can I push the same repository to GitHub and GitLab?

Yes. Add both as remotes and push to each, or define a remote group and push to the group (Git 2.55). Some teams instead configure one remote with two push URLs using git remote set-url --add --push.

What are git fetch –all and git pull –all for?

git fetch --all updates the remote-tracking branches of every configured remote. git pull always integrates into the current branch only; Git never updates all your local branches at once.

↑ ↓ navigate Enter open Esc close