Git Remote v Local

Introduction

Understanding the relationship between local and remote Git repositories is essential for effective collaboration and code management. This guide explains the differences between local and remote repositories, how they work together, and the commands you’ll use to interact with both.

🎥 Video Short: What Is The Difference Between Git and GitHub? (30 sec)

What is local vs remote? What is the difference in purpose for each?

Git is a distributed version control system, which means it operates with both local and remote components.

Local Repository

A local repository resides on your computer and contains:

The complete project history
All branches and tags
The working directory (your actual files)
The Git database (stored in the .git folder)

The local repository is where you perform most of your work: writing code, creating commits, switching branches, and organizing your changes.

Remote Repository

A remote repository is hosted on a server (like GitHub, GitLab, or Bitbucket) and serves as:

A central point for team collaboration
A backup of your project
A place to share your code with others
A platform for code review and project management

Remote repositories don’t contain working directories - they’re “bare” repositories focused on storing the Git database.

Diagram of Local and Remote Repositories

💡 Tip: Think of your local repository as your personal workspace and the remote repository as the team’s gathering point.

How does this relate to our overall Git workflow?

The typical Git workflow involves making changes locally, saving those changes as commits, and then synchronizing with a remote repository to share your work or get updates from your team.

Basic Workflow

Pull the latest changes from the remote repository
Create a new branch for your feature/fix
Make changes to your files in the working directory
Add changed files to the staging area
Commit your changes to your local repository
Push your commits to the remote repository
Create a pull request (on GitHub/GitLab/etc.) for code review
Merge your changes into the main branch

Sequence Diagram of Basic Workflow

⚠️ Note: Always pull before starting new work to avoid merge conflicts, and commit frequently to create logical, reversible checkpoints.

How do local and remote repos work together?

Local and remote repositories communicate through a set of well-defined operations that transfer commits back and forth.

Remote Tracking

When you clone a repository or set up a remote, Git creates “remote-tracking” branches that represent the state of the remote repository’s branches. These remote-tracking branches (like origin/main) help Git know what’s different between your local and remote repositories.

Git commit graph of remote tracking

The Sync Process

Fetch: Download objects and refs from the remote repository without merging
Merge/Rebase: Integrate remote changes into your local branch
Push: Upload your local commits to the remote repository

When you run git pull, Git actually performs a fetch followed by a merge.

Remote Configuration

Each remote repository is identified by a name (typically “origin” for the repository you cloned from) and a URL.

# List your remote repositories
$ git remote -v
origin  https://github.com/username/repo.git (fetch)
origin  https://github.com/username/repo.git (push)

# Add another remote
$ git remote add upstream https://github.com/original-username/repo.git

# Remove a remote
$ git remote remove upstream

Common commands used in relation to local v remote repos

Local Repository Commands

# Initialize a new repository
$ git init

# Check status of your working directory
$ git status

# Stage files for commit
$ git add file.txt
$ git add .  # Add all changes

# Create a commit
$ git commit -m "Add new feature"

# Switch branches
$ git checkout branch-name
$ git checkout -b new-branch  # Create and switch

# View commit history
$ git log
$ git log --oneline  # Compact view

Remote Repository Commands

# Clone a repository
$ git clone https://github.com/username/repo.git

# Download changes without merging
$ git fetch origin

# Download and merge changes
$ git pull origin main

# Upload local commits to remote
$ git push origin main

# Set up tracking relationship
$ git branch --set-upstream-to=origin/main main

# View remote branches
$ git branch -r

# View all branches (local and remote)
$ git branch -a

Examples of Typical Workflows

Starting a New Project

# Initialize locally
$ mkdir new-project
$ cd new-project
$ git init
$ touch README.md
$ git add README.md
$ git commit -m "Initial commit"

# Connect to remote and push
$ git remote add origin https://github.com/username/new-project.git
$ git push -u origin main

Contributing to an Existing Project

# Clone the project
$ git clone https://github.com/username/project.git
$ cd project

# Create a feature branch
$ git checkout -b feature/new-login

# Make changes, then commit
$ git add login.js
$ git commit -m "Implement new login system"

# Push the feature branch
$ git push -u origin feature/new-login

Common Questions

What happens when two people make changes to a remote repo at the same time?

When two people push changes to the same remote repository:

If they’re working on different files or different parts of the same file, Git will automatically merge the changes
If they’ve modified the same lines in the same files, Git will generate a merge conflict that needs manual resolution
The first person to push their changes won’t encounter any issues
The second person will need to pull (fetch and merge) before they can push

Sequence Diagram of Conflict Resolution

💡 Tip: To minimize conflicts, communicate with your team about who’s working on what, and pull changes frequently.

Can I work on the same project on multiple devices?

Yes, this is a perfect use case for remote repositories!

# On Device A
$ git commit -m "Finish feature X"
$ git push origin main

# Later, on Device B
$ git pull origin main  # Get the latest changes
# Continue working...

This workflow allows you to seamlessly switch between devices without manually transferring files.

Can I use Git without a remote repository?

Absolutely! Git is fully functional as a local-only version control system.

# Initialize a local repository
$ git init my-project
$ cd my-project

# Use Git commands normally
$ git add .
$ git commit -m "Save my progress"
$ git checkout -b experiment

Benefits of using Git locally:

Track changes over time
Create experimental branches
Roll back to previous versions
Document your work through commit messages

You only need a remote repository when you want to:

Collaborate with others
Back up your repository
Work from multiple devices
Share your code publicly

How can I check if my local repository is in sync with the remote?

You can use these commands to see the differences:

# Fetch latest changes without merging
$ git fetch

# Show difference between local and remote
$ git status

# See commit difference between local main and remote main
$ git log main..origin/main  # Commits in remote not in local
$ git log origin/main..main  # Commits in local not in remote

What’s the difference between `git fetch` and `git pull`?

# Fetch just downloads changes without merging
$ git fetch origin

# Pull both downloads AND merges in one step (fetch + merge)
$ git pull origin main

git fetch is safer as it doesn’t automatically modify your working branch
git pull is more convenient but can cause unexpected merge conflicts

Best Practices for Working with Remote Repositories

Pull before you start working: Always get the latest changes before starting new work
Push frequently: Share your commits regularly to avoid large divergence
Use branches: Don’t work directly on main/master to avoid conflicts
Write clear commit messages: Help your team understand your changes
Configure remotes correctly: Verify your remote URLs are correct

# Check your remote URL configuration
```bash
# Check your remote URL configuration
$ git remote -v

# Change a remote URL if needed
$ git remote set-url origin https://github.com/username/repo.git

Keep your repository structure clean: Don’t commit unnecessary files

# Create a .gitignore file to exclude files
$ echo "node_modules/" > .gitignore
$ echo ".env" >> .gitignore
$ git add .gitignore
$ git commit -m "Add gitignore file"