# 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

```bash
# 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:

```bash
.\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:
```bash
git push origin main
```
Use when: You have local commits ready to share with the team

### Git Pull
Downloads and merges remote changes:
```bash
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:
```bash
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
```bash
# 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
```bash
# 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)
```bash
# 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:
```bash
# 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.