git-workshop/02_multiplayer/01-remotes/README.md

Module 12: Working with Remotes

Learning Objectives

By the end of this module, you will:

• Understand what remote repositories are
• Clone a repository from a remote source
• Push local commits to a remote repository
• Pull changes from a remote repository
• Understand the difference between fetch and pull
• Manage remote branches
• Work with remote tracking branches

Challenge Description

You're joining a team project that's already hosted on a remote server. You need to clone the repository, make changes, and synchronize your work with the remote.

Your task is to:

1. Clone the remote repository
2. Create a new branch for your feature
3. Make changes and commit them locally
4. Push your branch to the remote
5. Fetch updates that were made by teammates
6. Merge remote changes into your branch

Key Concepts

What is a Remote Repository?

A remote repository is a version of your project hosted on a server (like GitHub, GitLab, or Bitbucket) or another location. It allows teams to collaborate by sharing code.

Common Remote Operations

Clone: Create a local copy of a remote repository

Remote Server                     Your Computer
    [repo] -----------------> [local copy of repo]

Push: Send your local commits to the remote

Your Computer                     Remote Server
  [commits] -----------------> [repo updated]

Pull: Get changes from remote and merge into your branch

Remote Server                     Your Computer
    [commits] ---------------> [branch updated]

Fetch: Get changes from remote but don't merge yet

Remote Server                     Your Computer
    [commits] ---------------> [stored locally, not merged]

Origin vs Upstream

• origin: The default name for the remote you cloned from
• upstream: Often used for the original repository when you've forked it
• You can have multiple remotes with different names

Remote Tracking Branches

When you clone a repository, Git creates remote tracking branches:

• origin/main - tracks the main branch on origin
• origin/feature - tracks the feature branch on origin

These are read-only local copies that show the state of remote branches.

Useful Commands

# Clone a repository
git clone <url>
git clone <url> <directory-name>

# View remotes
git remote
git remote -v  # Show URLs

# Add a remote
git remote add <name> <url>

# Remove a remote
git remote remove <name>

# Rename a remote
git remote rename <old-name> <new-name>

# Push to remote
git push origin <branch-name>
git push -u origin <branch-name>  # Set upstream tracking

# Pull from remote (fetch + merge)
git pull
git pull origin <branch-name>

# Fetch from remote (no merge)
git fetch
git fetch origin

# See remote branches
git branch -r
git branch -a  # All branches (local and remote)

# Delete remote branch
git push origin --delete <branch-name>

# Update remote tracking information
git remote update
git remote prune origin  # Remove stale remote tracking branches

Verification

Run the verification script to check your solution:

.\verify.ps1

The verification will check that:

• You cloned the repository correctly
• Your feature branch exists and has commits
• Changes were pushed to the remote
• You fetched and merged remote updates
• Your branch is up to date

Challenge Steps

1. Navigate to the challenge directory
2. You'll find a simulated "remote" repository
3. Clone it: git clone remote-repo local-repo
4. Navigate into your clone: cd local-repo
5. Create and switch to a feature branch: git switch -c add-feature
6. Make changes to the project (add a new feature to app.js)
7. Commit your changes
8. Push to remote: git push -u origin add-feature
9. Simulate teammate changes (run the provided update script)
10. Fetch updates: git fetch origin
11. View remote changes: git log origin/main
12. Merge remote main into your branch: git merge origin/main
13. Run verification

Tips

• git clone automatically sets up the remote as "origin"
• git push -u sets up tracking so future pushes can just use git push
• Use git fetch to see what's changed before merging
• git pull = git fetch + git merge
• Always pull before pushing to avoid conflicts
• Use git branch -a to see all local and remote branches
• Remote branches are read-only; you work on local branches
• origin/main is a remote tracking branch, main is your local branch

Push vs Pull vs Fetch

Git Push

Uploads your local commits to the remote:

git push origin main

Use when: You have local commits ready to share with the team

Git Pull

Downloads and merges remote changes:

git pull origin main

Use when: You want to update your branch with remote changes Equivalent to: git fetch origin + git merge origin/main

Git Fetch

Downloads remote changes without merging:

git fetch origin

Use when: You want to see what's changed before merging Safer than pull because it doesn't automatically merge

Common Remote Workflows

Daily Work Flow

# Start of day: get latest changes
git switch main
git pull origin main

# Create feature branch
git switch -c my-feature

# Do work, make commits
git add .
git commit -m "Add feature"

# Before pushing, update with latest main
git switch main
git pull origin main
git switch my-feature
git merge main

# Push your feature
git push -u origin my-feature

Collaboration Workflow

# Teammate pushed changes to main
git fetch origin
git log origin/main  # Review changes
git merge origin/main  # Merge into current branch

# Or use pull (fetch + merge in one step)
git pull origin main

Syncing Fork (with upstream)

# Add original repo as upstream
git remote add upstream <original-repo-url>

# Get latest from upstream
git fetch upstream
git switch main
git merge upstream/main

# Push to your fork
git push origin main

Handling Push Rejection

If push is rejected because remote has changes:

# Remote has commits you don't have
git push origin main
# Error: Updates were rejected

# Solution 1: Pull first (creates merge commit)
git pull origin main
git push origin main

# Solution 2: Pull with rebase (cleaner history)
git pull --rebase origin main
git push origin main

What You'll Learn

Working with remotes is fundamental to team collaboration. Understanding the difference between local and remote branches, knowing when to push/pull/fetch, and managing synchronization are core skills for any developer. While this module uses a local "remote" for learning, the concepts apply directly to GitHub, GitLab, and other hosting services. Mastering remotes enables you to work effectively in distributed teams and contribute to open source projects.