Recap — The Remote Mental Model

# The Remote Mental Model A remote is just another Git repo, somewhere else (GitHub, GitLab, an internal server, even a folder). Most commands you know work between your local repo and remotes. ## What's a remote ```bash git remote -v # origin git@github.com:you/repo.git (fetch) # origin git@github.com:you/repo.git (push) ``` `origin` is the default name for the remote you cloned from. It's just a convention; the name is arbitrary. You can have multiple remotes: ```bash git remote add upstream git@github.com:org/repo.git # now: origin (your fork) + upstream (the original) ``` Common when forking on GitHub: origin = your fork; upstream = source repo. ## Local vs remote-tracking branches Two kinds of local refs: ### Local branches ```bash git branch # * main # feature ``` You commit on these. ### Remote-tracking branches ```bash git branch -r # origin/main # origin/feature # upstream/main ``` These are READ-ONLY mirrors of the remote's branches. Updated when you `fetch`. You can't commit on them directly. ```bash git branch -a # both local and remote-tracking ``` ## The three commands ### Fetch — download but don't merge ```bash git fetch # update all remote-tracking branches from origin git fetch upstream # specific remote ``` Updates `origin/main`, `origin/feature`, etc. to reflect the remote's current state. Your LOCAL branches don't change. Safe; non-destructive; just gives you info. ### Pull — fetch + merge ```bash git pull origin main # fetch origin/main + merge it into current branch git pull # uses tracking config (most common) ``` Equivalent to: ```bash git fetch origin git merge origin/main ``` Pulls AND updates your current branch. Can cause merge conflicts. ### Push — upload your commits ```bash git push origin main # push current commits on main to origin git push # uses tracking config ``` Sends commits from your local branch to the remote. Fails if: - The remote has commits you don't (out of sync). Solution: pull first. - You don't have permission to push to that branch (e.g., protected branch). ## Tracking branches A local branch can "track" a remote branch — meaning push/pull know where to go. ```bash git switch -c feature # work, commit git push -u origin feature # -u sets up tracking # subsequent: git push (no args needed) ``` Without `-u`, you'd need to specify `origin feature` every time. ```bash git branch -vv # shows tracking info # * main abc123 [origin/main] Latest commit # feature def456 [origin/feature] My feature ``` ## The pull/push dance The common workflow: ```bash # Start of day: sync with remote git switch main git pull # bring main up to date # Create feature branch git switch -c feature/new-thing # work, commit, work, commit # Push to remote git push -u origin feature/new-thing # Later: sync feature with main (option 1: merge) git switch main git pull git switch feature/new-thing git merge main # bring main's changes into feature # OR (option 2: rebase, next module) git rebase main # When ready: open PR, get reviewed, merge. ``` ## Pull strategies ```bash git config --global pull.rebase false # default: merge (creates merge commits) git config --global pull.rebase true # rebase your local commits on top of remote git config --global pull.ff only # only fast-forward; refuse if would create merge commit ``` `pull --rebase` keeps history linear; `pull` (merge) shows the divergence. Both valid; team preference. ## What if push fails ``` ! [rejected] main -> main (non-fast-forward) error: failed to push some refs to ... hint: Updates were rejected because the tip of your current branch is behind ``` Translation: remote has commits you don't. Options: 1. `git pull` then push — brings remote changes; potentially creates merge commit. 2. `git pull --rebase` then push — rebases your commits on top of remote; linear history. 3. `git push --force` — DANGEROUS; overwrites remote (rejecting their commits). Only on personal branches. NEVER `--force` push to `main` or any shared branch. ## Removing tracking & cleanup ```bash git remote remove old-remote git branch -d -r origin/deleted-branch # remove stale remote-tracking git fetch --prune # auto-remove gone-on-remote refs ``` For a cleaner local: ```bash git config --global fetch.prune true # auto-prune on every fetch ``` ## SSH vs HTTPS ```bash # HTTPS (works everywhere, needs token in 2026) git clone https://github.com/you/repo.git # SSH (requires key setup; more convenient long-term) git clone git@github.com:you/repo.git ``` SSH: set up once, use forever. HTTPS: needs personal access token for push since 2021. For convenience: generate SSH key, add public key to GitHub, use SSH URLs. ## Common remote mistakes 1. **`git push --force` to shared branch.** Overwrites others' work. 2. **Push