If you are unfamiliar with
git and/or GitHub, it can be overwhelming navigating all the different workflow models you can use to add code to a repository. I know this feeling well, as it took me a while to get used to new workflows after being used to the classic SVN (years ago in University).
This post will focus on the common fork and pull workflow model that is used by many GitHub repositories. It will provide the necessary
git commands and a short description for each step of the workflow, specifically for Git beginners who may be hesitant to contribute to GitHub.
💡 Definition: A repository is a central location that holds data. It’s mostly used to store and manage code, documents, images, videos, and other data types. Repositories can be either public or private and are often used by software developers to store and collaborate on projects.
Fork and Pull Workflow In a Nutshell
The “Fork & Pull” workflow is a way to contribute changes to an original repository using three easy steps:
- Step 1: create a personal copy (fork) of the repository,
- Step 2: edit the fork, and
- Step 3: submit a request (pull request) to the owner of the original repository to merge your changes.
Step 1: Create a Fork
💡 Definition: A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. Forks are commonly used to either propose changes to someone else’s project or to use someone else’s project as a starting point for your own idea.
Creating a fork on GitHub is easy – just click the “Fork” button on the repository page.
Here’s how forking the TensorFlow repository looks like — easy:
Step 2: Clone and Edit Fork
Once you have your fork, you can clone it to your local machine and edit it.
Here’s where you actually change or add code files, find and remove bugs, write comments for the code, or refactor everything.
💡 Definition: If you clone a Git repository, you essentially create an identical copy. You clone to work on your own local copy of the repository and sync changes back to the original repository. This is useful for keeping your local copy up to date with the latest changes and for contributing changes back to the original repository.
Step 3: Push Changes to Fork and Perform Pull Request
When you are done, you push your changes back to the fork on GitHub.
💡 Definition: A Git push operation is the process of sending changes from a local repository to a remote repository. The changes are applied to the remote repository. And your local repository is synchronized with the remote repository.
Lastly, you submit a pull request to the owner of the original repository.
💡 Definition: A pull request is a request to merge a branch into the main branch of a repository. It is used to propose changes and request feedback from other contributors, who can accept or reject the changes based on their review.
If there are no merge conflicts, the owner can simply click the “merge” button to accept your changes.
Six Steps to Pull Request
To create a pull request, you need to:
- Fork the repository on GitHub.
- Clone your fork to your workspace with the
- Modify the code and commit the changes to your local clone.
- Push your changes to your remote fork on GitHub.
- Create a pull request on GitHub and wait for the owner to merge or comment your changes.
- If the owner suggests changes, push them to your fork, and the pull request will be updated automatically.
What If Multiple Devs Work In Parallel?
If multiple developers work in parallel on the same repository, it may happen that they work on step 3 in parallel and try to push changes to the remote fork at the same time.
Here’s my drawing of this scenario. 😆
Add the original repository as a remote repository called “upstream”:
git remote add upstream https://github.com/OWNER/REPOSITORY.git
Fetch all changes from the upstream repository:
git fetch upstream
Switch to the master branch of your fork:
git checkout master
Merge changes from the upstream repository into your fork:
git merge upstream/master
If you are working on multiple features, you should isolate them from each other. To do this, create a separate branch for each feature.
- Use the command
git checkout -b BRANCHNAMEto create and switch to a new branch.
- Upload the branch to the remote fork with
git push --set-upstream origin BRANCHNAME.
- To switch between branches, use
git checkout BRANCHNAME.
- To create a pull request from a branch, go to the GitHub page of that branch and click the “pull request” button.
To update a feature branch:
- Switch to the feature branch:
git checkout my-feature-branch
- Commit all changes:
git commit -m MESSAGE
- Update the feature branch by rebasing it from the master branch:
git rebase master
Why I Wrote This
I wrote this short tutorial to help contributors to our real-world practical project to build a P2P social network for information dissemination that is structured like a big brain. Users are neurons. Connections are synapses. Information Impulses spread through neurons “firing” and travel over synapses in a decentralized way:
👉 Recommended: Peer Brain – A Decentralized P2P Social Network App
If you like the tutorial and you want to contribute to this open-source social network app, feel free to try out this workflow yourself on this GitHub repository! ⤴️
The Fork and Pull Workflow is a popular collaboration model used during software development.
In this workflow, a user forks a repository from an original (=upstream) repository, then develops and maintains a separate copy of the codebase on their own fork.
Users can then make changes to their own version of the repository, commit them, and push them up to their own fork. If the user wants to contribute their changes back to the upstream repository, they can then create a pull request. This allows the upstream maintainer to review the changes and determine if they should be merged into the main codebase.
The Fork and Pull Workflow is so popular for collaboration on a common code base because developers can work independently on the code and synchronize on the upstream repos in a well-structured and organized way.
This workflow also benefits upstream maintainers, as they don’t have to manage multiple contributions coming in from multiple sources.
👉 Recommended: Peer Brain – A Decentralized P2P Social Network App
While working as a researcher in distributed systems, Dr. Christian Mayer found his love for teaching computer science students.
To help students reach higher levels of Python success, he founded the programming education website Finxter.com that has taught exponential skills to millions of coders worldwide. He’s the author of the best-selling programming books Python One-Liners (NoStarch 2020), The Art of Clean Code (NoStarch 2022), and The Book of Dash (NoStarch 2022). Chris also coauthored the Coffee Break Python series of self-published books. He’s a computer science enthusiast, freelancer, and owner of one of the top 10 largest Python blogs worldwide.
His passions are writing, reading, and coding. But his greatest passion is to serve aspiring coders through Finxter and help them to boost their skills. You can join his free email academy here.