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.