A Detailed Guide to Git Pulls and Remote Updates
A "pull" is the process of retrieving updates from a remote repository and merging them into a local branch. Pulling allows team members to synchronize their changes and keep their local code in sync with the remote repository. Understanding the difference between "pull" and "fetch" is crucial for team collaboration.
1. Basic Concepts of Pull
(1) What is a pull?
A pull is a combination of two operations:
- fetch: Download updates from a remote repository
- merge: Merge the remote branch into the current branch
graph TB
A[Remote Repository<br/>Remote] -->|git fetch| B[Remote Branch Replica<br/>origin/main]
B -->|git merge| C[Current Branch<br/>main]
A -.->|git pull = fetch + merge| C
style A fill:#d4edda
style B fill:#fff3cd
style C fill:#c3e6cb
6. Detailed: pull vs fetch
| Action | Description | Impact |
|---|---|---|
| pull | fetch + merge | modify the current branch |
| fetch | Download updates only | Do not modify the current branch |
(3) The Purpose of Pulling
- Sync Code: Retrieve the latest changes made by team members
- Update Branch: Keep the local branch in sync with the remote branch
- Get Label: Download a new label from a remote source
- View Updates: See what's changed remotely
2. Basic Pull Operations
(1) Pull the current branch
▶ Example: Pulling Updates
BASH
# Pull updates from the current branch
git pull
# Output：
# remote: Enumerating objects: 5, done.
# remote: Counting objects: 100% (5/5), done.
# remote: Compressing objects: 100% (3/3), done.
# remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
# Unpacking objects: 100% (3/3), 285 bytes | 285.00 KiB/s, done.
# From https://github.com/user/repo
# a1b2c3d..d4e5f6g main -> origin/main
# Updating a1b2c3d..d4e5f6g
# Fast-forward
# file.js | 1 +
# 1 file changed, 1 insertion(+)
(2) Pull the specified branch
▶ Example: Pulling a Specific Branch
BASH
# Pull a specified remote branch
git pull origin main
# Pull a remote branch into a local branch with a different name
git pull origin remote-branch:local-branch
# Pull updates from all remote branches
git pull --all
# Pull and view details
git pull --verbose
(3) Pre-pull Inspection
▶ Example: Pre-pull check
BASH
# View differences between local and remote versions
git fetch
git diff main origin/main
# View new commits on the remote repository
git log main..origin/main
# Output：
# d4e5f6g (origin/main) feat: Add a New Feature
# h7i8j9k fix: FixBug
# View the files to be pulled
git diff --name-only main origin/main
# Output：
# src/auth.js
# src/user.js
# Confirm before pulling
git pull
3. Pull Strategy
(1) Pull using merge (default)
▶ Example: merge pull
BASH
# Use by defaultmergePull
git pull
# Equivalent to
git fetch
git merge origin/main
# A merge commit will be created after the pull.（If there is a fork）
git log --oneline --graph
# Output：
# * a1b2c3d Merge branch 'main' of https://github.com/user/repo
# |\
# | * d4e5f6g (origin/main) Remote commit
# * | h7i8j9k Local commit
# |/
# * k9l0m1n Base commit
(2) Pulling using rebase
▶ Example: Rebasing a pull request
BASH
# UsagerebasePull
git pull --rebase
# Output：
# remote: Enumerating objects: 5, done.
# From https://github.com/user/repo
# a1b2c3d..d4e5f6g main -> origin/main
# First, rewinding head to replay your work on top of it...
# Fast-forwarded main to d4e5f6g.
# View History（Linear，No merged commits）
git log --oneline --graph
# Output：
# * h7i8j9k Local commit
# * d4e5f6g (origin/main) Remote commit
# * k9l0m1n Base commit
(3) Merge vs. Rebase Pull
graph TB
subgraph mergePull
A1[Local Commit] --> M1[Merge Commit]
B1[Remote Commit] --> M1
end
subgraph rebasePull
A2[Remote Commit] --> B2[Local Commit<br/>after rebase]
end
style M1 fill:#fff3cd
style B2 fill:#d4edda
Merge Pull:
- Preserve the complete history
- Generate a merge commit
- There is a fork in the history graph
Rebase:
- Maintain a linear history
- No merged commits
- The historical chart is clearer
4. Resolving Pull Request Conflicts
(1) Conflicts occur during a pull
▶ Example: Pull Conflicts
BASH
# The same file was modified both locally and remotely
git pull
# Output：
# remote: Enumerating objects: 5, done.
# From https://github.com/user/repo
# a1b2c3d..d4e5f6g main -> origin/main
# Auto-merging file.js
# CONFLICT (content): Merge conflict in file.js
# Automatic merge failed; fix conflicts and then commit the result.
(2) Resolving Pull Conflicts
▶ Example: Resolving Conflicts
BASH
# View Conflict Status
git status
# Output：
# You have unmerged paths.
# (fix conflicts and run "git commit")
#
# Unmerged paths:
# (use "git add <file>..." to mark resolution)
# both modified: file.js
# View Conflict Details
cat file.js
# Output：
# <<<<<<< HEAD
# Local Changes
# =======
# Remote Content Editing
# >>>>>>> d4e5f6g
# Editing Files to Resolve Conflicts
# Keep the necessary content
# Mark the conflict as resolved
git add file.js
# Complete the merger
git commit
# Push to Remote
git push
(3) Cancel Pull
▶ Example: Cancel a pull
BASH
# Pull conflict，I want to cancel
git merge --abort
# Or
git reset --merge
# RegardingrebasePull
git rebase --abort
5. Detailed Explanation of Pull Options
(1) Common Pull Options
| Option | Description | Use Case |
|---|---|---|
--rebase |
Pull using rebase | Maintain a linear history |
--no-rebase |
Pull using merge |
Preserve full history |
--ff-only |
Fast-forward merges only | Ensure no forks |
--force |
Force pull | Overwrite local changes |
--all |
Pull all remote | Update all remote |
--dry-run |
Simulate Fetch | Preview Fetched Content |
▶ Example: Using the "Pull" option
BASH
# Only fast-forward merges are allowed
git pull --ff-only
# Output（If you can't fast-forward）：
# fatal: Not possible to fast-forward, aborting.
# Simulated Pull
git pull --dry-run
# Pull all remote repositories
git pull --all
# Set the Default Pull Method
git config pull.rebase true # Use by defaultrebase
git config pull.rebase false # Use by defaultmerge
git config pull.ff only # Fast-forward only
(2) Pull from a specific remote
▶ Example: Pulling from a specific remote
BASH
# Pullorigin
git pull origin
# Pullupstream
git pull upstream main
# Pull a specific branch
git pull origin feature
# Pull and Set Upstream
git pull --set-upstream origin feature
6. Detailed Comparison: pull vs fetch
(1) Using fetch
▶ Example: Using fetch
BASH
# Get Remote Updates（Do not merge）
git fetch origin
# Output：
# remote: Enumerating objects: 5, done.
# From https://github.com/user/repo
# a1b2c3d..d4e5f6g main -> origin/main
# * [new branch] feature -> origin/feature
# View Remote Branches
git branch -r
# Output：
# origin/main
# origin/feature
# View Remote Updates
git log origin/main
# Compare Differences
git diff main origin/main
# Manual Merge
git merge origin/main
# Orrebase
git rebase origin/main
(2) When to Use fetch
graph TB
A[Need to check for remote updates] --> B[Usagefetch]
B --> C[View Differences]
C --> D{Merge or Not?}
D -->|Yes| E[Manualmerge/rebase]
D -->|No| F[Keep the current state]
style B fill:#d4edda
style E fill:#c3e6cb
When to use fetch:
- View remote updates but do not merge them immediately
- Remote changes require review
- Want to selectively merge updates
- I have unsubmitted work and don't want to cause any conflicts
When to use pull:
- Confirm that you want to sync remote updates
- Local workspace is clean
- Quickly sync the latest code
(3) fetch + merge vs pull
▶ Example: Comparing the Two Methods
BASH
# Method1：Directlypull
git pull origin main
# Method2：fetch + merge（Safer）
git fetch origin
git diff main origin/main # View Differences
git merge origin/main # Merge after confirmation
# Method3：fetch + rebase
git fetch origin
git diff main origin/main
git rebase origin/main
7. Best Practices for Pull Requests
(1) Daily Pull Workflow
▶ Example: Recommended Workflow
BASH
# 1. Pull the latest code before starting work
git checkout main
git pull --rebase origin main
# 2. Create a feature branch
git checkout -b feature/new-feature
# 3. Develop and Submit
git add .
git commit -m "feat: Add a New Feature"
# 4. Fetch updates again before pushing
git fetch origin
git rebase origin/main
# 5. Push
git push origin feature/new-feature
(2) Best Practices for Resolving Pull Conflicts
▶ Example: Conflict Resolution Process
BASH
# Pull conflict
git pull
# 1. View Conflicting Files
git status
# 2. Using Tools to Resolve Conflicts
git mergetool
# 3. Or edit the file manually
# 4. Test Code
npm test
# 5. Mark the conflict as resolved
git add .
# 6. Complete the merger
git commit
# 7. Push
git push
(3) Keep Branches in Sync
▶ Example: Scheduled Synchronization
BASH
# Regularly Synchronize Remote Updates
git fetch origin
# View the status of all branches
git branch -vv
# Output：
# * main a1b2c3d [origin/main: behind 3] feat: Add Feature
# develop d4e5f6g [origin/develop: ahead 2] Fix: FixBug
# feature h7i8j9k [origin/feature] WIP: New Features
# Synchronize a Branch That Is Behind
git checkout main
git pull
# Or sync all branches
git pull --all
❓ FAQ
Q What is the difference between
pull and fetch?A
git pull = git fetch + git merge will download the updates and merge them into the current branch. git fetch only downloads the updates without modifying the current branch, which is safer.Q When should you use
--rebase to pull?A Use this when you want to keep the commit history linear and avoid merge commits. A rebase will reorder local commits so they appear on top of remote commits, resulting in a clearer history.
Q What should I do if a conflict occurs during a pull?
A To resolve conflicts in a file, use
git add to mark the conflict as resolved, then git commit to complete the merge. If you do not want to resolve the conflict, you can use git merge --abort to cancel the pull.Q How do I see what new commits are on the remote?
A First,
git fetch to download the update, then use git log HEAD..origin/main to view the new remote commits, or use git diff HEAD origin/main to view the differences.Q What should I do if I get an "unrelated histories" error when pulling?
A This means that the local and remote repositories have no shared history (e.g., they were initialized separately). Using
git pull --allow-unrelated-histories allows you to merge unrelated histories.📖 Summary
- A pull is the process of retrieving updates from a remote repository and merging them into the local repository (fetch + merge)
- Basic pull:
git pullPull updates from the current branch - Pull strategy: "merge" pulls while preserving the full history; "rebase" pulls while maintaining a linear history
- Pull conflicts: Edit the file to resolve the conflicts, mark them as resolved, and then commit
- pull vs. fetch: fetch only downloads without merging, making it safer and more controllable
- Best Practices for Pulling: Pull before starting work, pull before pushing, and sync regularly
📝 Exercises
-
Basic Exercise: Create a commit in your local repository and push it to the remote repository. Then, clone the repository to another location, make changes, and push them. Return to the original repository and pull the updates to experience the complete pull process.
-
Advanced Exercise: Compare a merge pull with a rebase pull: Create commits on both the local and remote repositories, perform a pull using each method, and observe the differences in the graph history.
-
Challenge: Simulate a pull conflict scenario: Make changes to the same location in the same file both locally and remotely; when you pull, a conflict occurs; manually resolve the conflict and complete the merge.
