Fork and pull request workflow in Git - Deep Dive

Overview - Fork and pull request workflow

What is it?

The fork and pull request workflow is a way to contribute changes to a project by copying it (forking), making changes in your copy, and then asking the original project to include your changes through a pull request. This method allows many people to work on the same project safely without directly changing the original code. It is commonly used in open-source projects to manage contributions from many developers.

Why it matters

Without this workflow, many people working on the same project could accidentally overwrite each other's work or introduce errors. It provides a clear, safe way to review and discuss changes before they become part of the main project. This keeps the project stable and organized, even with many contributors worldwide.

Where it fits

Before learning this, you should understand basic Git commands like clone, commit, and push. After mastering this workflow, you can learn about advanced collaboration tools like GitHub Actions or continuous integration to automate testing of pull requests.

Mental Model

Core Idea

Forking creates your own copy to safely make changes, and pull requests ask the original project to review and include those changes.

Think of it like...

It's like borrowing a recipe book from a friend, writing your own version of a recipe in your copy, and then asking your friend if they want to add your improved recipe back into their book.

Original Repo ──┐
                 │
             Forked Repo (Your copy)
                 │
          Make changes here
                 │
          Create Pull Request
                 │
          Original Repo reviews
                 │
          Merge changes if approved

Build-Up - 7 Steps

1

Foundation

Understanding what a fork is

Concept: A fork is a personal copy of someone else's project stored in your own account.

When you fork a project, you create a separate copy that you fully control. This copy is independent, so changes you make do not affect the original project until you ask to merge them.

Result

You have your own project copy where you can experiment freely.

Knowing that a fork is your own safe space helps you understand how collaboration can happen without risk to the original project.

2

Foundation

Basics of pull requests

Concept: A pull request is a formal way to ask the original project to include your changes.

After making changes in your fork, you create a pull request. This shows your changes and lets the original project owners review, discuss, and decide whether to merge them.

Result

Your changes are visible to the original project and can be merged after review.

Pull requests create a communication channel between contributors and maintainers, ensuring quality and collaboration.

3

Intermediate

Making changes in your fork

🤔Before reading on: do you think you can push changes directly to the original project or only to your fork? Commit to your answer.

Concept: You make changes in your fork by cloning it locally, editing files, committing, and pushing back to your fork on the server.

1. Clone your fork to your computer. 2. Create a new branch for your changes. 3. Make edits and commit them. 4. Push the branch to your fork on the server. Example commands: $ git clone https://github.com/yourname/project.git $ git checkout -b feature-branch # edit files $ git add . $ git commit -m "Add new feature" $ git push origin feature-branch

Result

Your changes are saved in a new branch on your forked repository.

Understanding that your fork is a full repository lets you use all Git features safely before proposing changes.

4

Intermediate

Creating and managing pull requests

🤔Before reading on: do you think a pull request automatically merges your changes or requires approval? Commit to your answer.

Concept: A pull request must be created on the hosting platform and reviewed before merging.

After pushing your branch, go to the original project's website (like GitHub). There, you create a pull request from your branch to the original project’s main branch. You can add a description explaining your changes. The project maintainers will review and discuss it.

Result

A pull request is open for review and discussion but not merged yet.

Knowing that pull requests are proposals, not automatic merges, helps you appreciate the review process that keeps projects stable.

5

Intermediate

Keeping your fork up to date

🤔Before reading on: do you think your fork updates automatically when the original project changes? Commit to your answer.

Concept: Your fork does not update automatically; you must sync it manually to stay current.

To keep your fork updated: 1. Add the original project as a remote called 'upstream'. 2. Fetch changes from upstream. 3. Merge or rebase those changes into your fork. Commands: $ git remote add upstream https://github.com/original/project.git $ git fetch upstream $ git checkout main $ git merge upstream/main $ git push origin main

Result

Your fork’s main branch matches the original project’s latest state.

Understanding manual syncing prevents conflicts and keeps your work compatible with the original project.

6

Advanced

Handling pull request feedback

🤔Before reading on: do you think you must create a new pull request for every change requested, or can you update the existing one? Commit to your answer.

Concept: You can update your existing pull request by pushing new commits to the same branch.

If maintainers request changes: 1. Make the changes locally on the same branch. 2. Commit and push them to your fork. 3. The pull request updates automatically with your new commits. This allows continuous improvement without opening multiple pull requests.

Result

Your pull request reflects the latest changes and feedback.

Knowing that pull requests are dynamic encourages iterative collaboration and smoother reviews.

7

Expert

Avoiding merge conflicts in pull requests

🤔Before reading on: do you think merge conflicts happen only when two people edit the same line, or can they happen in other cases? Commit to your answer.

Concept: Merge conflicts occur when changes overlap or contradict, and resolving them requires careful syncing and communication.

To avoid conflicts: - Regularly sync your fork with the original project. - Rebase your feature branch onto the latest main branch before pushing. - Communicate with maintainers if your changes overlap with others. Example rebase commands: $ git fetch upstream $ git checkout feature-branch $ git rebase upstream/main $ git push --force-with-lease origin feature-branch

Result

Your pull request merges cleanly without conflicts.

Understanding how conflicts arise and how to resolve them prevents delays and frustration in collaboration.

Under the Hood

When you fork a repository, the hosting service creates a full copy under your account, including all branches and history. Your fork is a separate Git repository with its own remote URL. Pull requests are metadata objects on the hosting platform that link your fork’s branch to the original repository’s branch. They do not transfer code until merged. The platform tracks changes, comments, and merge status, coordinating the review process.

Why designed this way?

This design allows open collaboration without risking the original project’s stability. Forks isolate changes, and pull requests enable controlled integration. Alternatives like direct pushes risk accidental overwrites. The fork and pull request model scales well for large communities and preserves project integrity.

┌───────────────┐       Fork       ┌───────────────┐
│ Original Repo │ ───────────────▶ │ Forked Repo   │
└───────────────┘                  └───────────────┘
        ▲                                │
        │ Pull Request                   │ Push changes
        │                                ▼
┌───────────────┐                  ┌───────────────┐
│ Maintainers   │ ◀────────────── │ Contributor   │
│ Review &     │    Review &      │ Work locally  │
│ Merge PR     │                  └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think pushing to your fork automatically updates the original project? Commit to yes or no.

Common Belief: Pushing changes to your fork automatically updates the original project.

Reality: Pushing to your fork only updates your copy; the original project stays unchanged until a pull request is merged.

Why it matters: Believing this causes confusion when changes don't appear in the original project, leading to wasted time and frustration.

Quick: Do you think you must create a new pull request for every change you want to make? Commit to yes or no.

Common Belief: Every change requires opening a new pull request.

Reality: You can update an existing pull request by pushing new commits to the same branch in your fork.

Why it matters: Misunderstanding this leads to cluttered pull requests and harder reviews.

Quick: Do you think your fork updates automatically when the original project changes? Commit to yes or no.

Common Belief: Your fork automatically stays up to date with the original project.

Reality: You must manually sync your fork to get the latest changes from the original project.

Why it matters: Failing to sync causes merge conflicts and outdated work.

Quick: Do you think merge conflicts only happen when two people edit the exact same line? Commit to yes or no.

Common Belief: Merge conflicts only occur if two people edit the same line of code.

Reality: Conflicts can happen when changes affect nearby lines or file structures, not just the same line.

Why it matters: Underestimating conflict causes unexpected merge failures and delays.

Expert Zone

1

Pull requests can be used not only for code but also for documentation, configuration, and even design files, enabling broad collaboration.

2

Using rebase instead of merge to update your feature branch keeps history linear and easier to understand, but requires careful use to avoid rewriting shared history.

3

Some projects use protected branches and require pull request approvals and passing automated tests before merging, adding quality gates to the workflow.

When NOT to use

This workflow is less suitable for small teams working on private projects where direct push access is safe and faster. In such cases, a shared branch workflow or feature branching without forks is simpler and more efficient.

Production Patterns

In large open-source projects like Linux kernel or popular libraries, contributors fork the repo, work on feature branches, and submit pull requests. Maintainers use automated checks and code reviews to ensure quality before merging. Continuous integration systems run tests on pull requests to catch errors early.

Connections

Code Review

Pull requests are a formalized way to perform code review.

Understanding pull requests helps grasp how code review processes improve software quality by enabling discussion and feedback before merging.

Version Control Branching

Forking and pull requests build on the concept of branching to isolate changes.

Knowing branching fundamentals clarifies how forks and pull requests manage parallel work streams safely.

Collaborative Writing

Similar to how multiple authors suggest edits on a shared document, pull requests allow proposing changes for group approval.

Recognizing this connection shows how collaboration principles apply across software and other creative fields.

Common Pitfalls

#1 Pushing changes directly to the original project without permission.

Wrong approach:

git push origin main

Correct approach:

git push origin feature-branch (in your fork) and create a pull request

Root cause:

Misunderstanding that you need permission to push directly to the original repository.

#2 Not syncing your fork before starting work, causing conflicts later.

Wrong approach:

git clone your fork and start working immediately without fetching upstream changes

Correct approach:

git remote add upstream https://github.com/original/project.git
git fetch upstream
git merge upstream/main

Root cause:

Not realizing your fork can become outdated compared to the original project.

#3 Creating multiple pull requests for small iterative changes instead of updating one.

Wrong approach:

Open new pull request for every small fix

Correct approach:

Push new commits to the same branch to update the existing pull request

Root cause:

Lack of understanding that pull requests track branches, not single commits.

Key Takeaways

Forking creates your own safe copy of a project where you can freely make changes without affecting the original.

Pull requests are proposals to merge your changes back into the original project, enabling review and discussion.

You must manually keep your fork updated with the original project to avoid conflicts and outdated work.

Pull requests can be updated with new commits, allowing iterative improvements based on feedback.

Understanding this workflow is essential for collaborating on open-source projects and large teams safely and efficiently.

Practice

1. What is the main purpose of forking a repository in the fork and pull request workflow?

easy

A. To clone the repository locally without any changes

B. To delete the original project

C. To create a personal copy of the project to work on independently

D. To merge changes directly into the original repository

Solution

1. Step 1: Understand the concept of forking

   Forking creates a personal copy of the original project on your GitHub account, allowing you to work independently without affecting the original.

2. Step 2: Identify the purpose in the workflow

   This personal copy lets you safely make changes and experiment before proposing them back to the original project.

3. Final Answer:

   To create a personal copy of the project to work on independently -> Option C

4. Quick Check:

   Fork = personal copy for safe work [OK]

Hint: Fork means copy project to your account for safe changes [OK]

Common Mistakes:

• Confusing fork with clone
• Thinking fork deletes original
• Assuming fork merges changes automatically

2. Which command correctly pushes a new branch named feature1 to your forked repository?

easy

A. git push origin main

B. git push upstream feature1

C. git push fork feature1

D. git push origin feature1

Solution

1. Step 1: Identify the remote name for your fork

   By default, your fork is set as the remote named origin. The original repository is usually upstream.

2. Step 2: Use the correct push syntax

   To push a branch named feature1 to your fork, use git push origin feature1.

3. Final Answer:

   git push origin feature1 -> Option D

4. Quick Check:

   Push branch to origin (your fork) = git push origin branch [OK]

Hint: Push new branch to origin, not upstream [OK]

Common Mistakes:

• Using upstream instead of origin for push
• Pushing main branch instead of feature branch
• Using incorrect remote name like fork

3. After forking a repo and pushing a branch fix-bug to your fork, what is the next step to propose your changes to the original project?

medium

A. Directly push fix-bug branch to the original repository

B. Create a pull request from your fork's fix-bug branch to the original repo

C. Merge fix-bug branch locally without pushing

D. Delete your fork and clone the original repo again

Solution

1. Step 1: Understand the pull request purpose

   A pull request asks the original project to review and merge your changes from your fork's branch.

2. Step 2: Identify the correct action after pushing

   After pushing your branch to your fork, you create a pull request targeting the original repository's branch.

3. Final Answer:

   Create a pull request from your fork's fix-bug branch to the original repo -> Option B

4. Quick Check:

   Push branch then create pull request [OK]

Hint: Push branch, then open pull request to original repo [OK]

Common Mistakes:

• Trying to push directly to original repo without permission
• Merging locally without sharing changes
• Deleting fork before proposing changes

4. You forked a repo and created a branch update-docs. You pushed it but forgot to sync your fork with the original repo first. What problem might occur when creating a pull request?

medium

A. Merge conflicts due to outdated fork base

B. Your pull request will be automatically merged

C. Your branch will be deleted automatically

D. No changes will be visible in the pull request

Solution

1. Step 1: Understand syncing forks

   If your fork is behind the original repo, your branch may not include recent changes from the original.

2. Step 2: Identify the pull request impact

   This can cause merge conflicts when the original repo tries to merge your changes because the base is outdated.

3. Final Answer:

   Merge conflicts due to outdated fork base -> Option A

4. Quick Check:

   Outdated fork causes merge conflicts [OK]

Hint: Always sync fork before starting new branch [OK]

Common Mistakes:

• Assuming pull request merges automatically
• Thinking branch deletes itself
• Believing changes won't show without sync

5. You forked a project and created two branches: featureA and featureB. You pushed both branches to your fork. How do you create pull requests so the original repo can review and merge these features independently?

hard

A. Create separate pull requests for each branch targeting the original repo's main branch

B. Create one pull request combining both branches

C. Push both branches to upstream and wait for automatic merge

D. Merge featureB into featureA locally, then create a single pull request

Solution

1. Step 1: Understand pull request scope

   Each pull request represents changes from one branch to the original repo, allowing independent review.

2. Step 2: Apply to multiple branches

   To keep features separate, create one pull request per branch targeting the original repo's main branch.

3. Final Answer:

   Create separate pull requests for each branch targeting the original repo's main branch -> Option A

4. Quick Check:

   One pull request per branch for independent review [OK]

Hint: Make one pull request per branch for clear reviews [OK]

Common Mistakes:

• Combining branches in one pull request
• Pushing branches directly to upstream without PR
• Merging branches locally before PR