Git: 2. Git Fork workflow
The Forking Workflow is fundamentally different than other popular Git workflows. Instead of using a single GitHub.com repository to act as the “central” codebase, it gives every contributor their own GitHub.com repository under their personal profile. This means that each contributor has not one, but two Git repositories: a private local one and a public one on the web. The Forking Workflow is most often seen in public open source projects.
The main advantage of the Forking Workflow is that contributions can be integrated without the need for everybody to push to a single central repository, avoiding unecessary conflicts. Contributors push to their own repositories on GitHub.com, and only the project maintainer can push to the official repository. This allows the maintainer to accept commits from any contributor without giving them write access to the official codebase.
Complete feature branches will be purposed for merge into the original project maintainer's repository. The result is a distributed workflow that provides a flexible way for large, organic teams (including untrusted third-parties) to collaborate securely. This also makes it an ideal workflow for open source projects.
As in other Git workflows, the Forking Workflow begins with Canada-ca/blogue-canada-ca-blog. But when a new contributor wants to start working on the project, they do not directly clone the Canada-ca/blogue-canada-ca-blog repository.
Instead, they fork the Canada-ca/blogue-canada-ca-blog repository to create a copy of it on GitHub.com ([contributor]/blogue-canada-ca-blog). This new copy serves as their personal public repository—no other contributor are allowed to push to it, but they can pull changes from it (we’ll see why this is important in a moment). After they have created their GitHub.com copy, the contributor performs a git clone to get a copy of it onto their local machine. This serves as their private development environment, just like in the other workflows.
When they're ready to publish a local commit, they push the commit to their own public repository ([contributor]/blogue-canada-ca-blog) —not the official Canada-ca/blogue-canada-ca-blog. Then, they file a pull request with the main repository, which lets the project maintainer know that an update is ready to be integrated. The pull request also serves as a convenient discussion thread if there are issues with the contributed code. The following is a step-by-step example of this workflow.
- A contributor 'forks'
Canada-ca/blogue-canada-ca-blog. This creates[contributor]/blogue-canada-ca-blogon their own GitHub.com account. - Then the new
[contributor]/blogue-canada-ca-blogis cloned to their local system. - A Git remote path for
Canada-ca/blogue-canada-ca-blogrepository is added to the local clone. - A new local feature branch is created (
feature/2021-05-07-my-great-new-post). - The contributor makes changes on the new branch.
- New commits are created for the changes.
- The branch gets pushed to the
[contributor]/blogue-canada-ca-blog. - The contributor opens a pull request from the new branch to the
Canada-ca/blogue-canada-ca-blogrepository. - The pull request gets approved for merge and is merged into the
Canada-ca/blogue-canada-ca-blog
To integrate the feature into the Canada-ca/blogue-canada-ca-blog codebase, the maintainer pulls the contributor’s changes into their local repository, checks to make sure it doesn’t break the project, merges it into their local main branch, then pushes the main branch to the Canada-ca/blogue-canada-ca-blog repository on the server. The contribution is now part of the project, and other contributors should pull from the Canada-ca/blogue-canada-ca-blog repository to synchronize their local repositories.
All of these personal public repositories are really just a convenient way to share branches with other contributors. Everybody should still be using branches to isolate individual features. In the Forking Workflow, they are pulled into another contributor’s local repository.
All new contributors to a Forking Workflow project need to fork the Canada-ca/blogue-canada-ca-blog repository.
Next each contributor needs to clone their own public forked repository. They can do this with the familiar git clone command.
Assuming the use of Bitbucket to host these repositories, contributors on a project should have their own Bitbucket account and they should clone their forked copy of the repository with:
git clone https://[email protected]/user/repo.git
Whereas other Git workflows use a single origin remote that points to the central repository, the Forking Workflow requires two remotes—one for the Canada-ca/blogue-canada-ca-blog repository, and one for the contributor’s personal server-side repository. While you can call these remotes anything you want, a common convention is to use origin as the remote for your forked repository (this will be created automatically when you run git clone) and upstream for the Canada-ca/blogue-canada-ca-blog repository.
git remote add upstream https://bitbucket.org/maintainer/repo
You’ll need to create the upstream remote yourself using the above command. This will let you easily keep your local repository up-to-date as the Canada-ca/blogue-canada-ca-blog codebase progresses.
In the [contributor]/blogue-canada-ca-blog repository they can edit code, commit changes, and create branches:
git checkout -b some-feature # Edit some code git commit -a -m "Add first draft of some feature"
All of their changes will be entirely private until they push it to their public repository. And, if the Canada-ca/blogue-canada-ca-blog project has moved forward, they can access new commits with git pull:
git pull upstream master
Since contributors should be working in a dedicated feature branch, this should generally result in a fast-forward merge.
Once a contributor is ready to share their new feature, they need to do two things. First, they have to make their contribution accessible to other contributors by pushing it to their public repository. Their origin remote should already be set up, so all they should have to do is the following:
git push origin feature-branch
This diverges from the other workflows in that the origin remote points to the contributor’s personal server-side repository, not the main codebase.
Second, they need to notify the project maintainer that they want to merge their feature into the Canada-ca/blogue-canada-ca-blog codebase. GitHub provides a “pull request” button that leads to a form asking you to specify which branch you want to merge into the Canada-ca/blogue-canada-ca-blog repository. Typically, you’ll want to integrate your feature branch into the upstream remote’s master branch.
To recap, the Forking Workflow is commonly used in public open-source projects. Forking is a git clone operation executed on a server copy of a projects repo. A Forking Workflow is often used in conjunction with a Git hosting service like Bitbucket. A high-level example of a Forking Workflow is:
- You want to contribute
Canada-ca/blogue-canada-ca-blog - Using GitHub.com you create a fork of the repo to github.com/[contributor]/blogue-canada-ca-blog
- On your local system you execute
git cloneon https://github.com/[contributor]/blogue-canada-ca-blog to get a local copy of the repo - You create a new
feature/2021-05-07-my-great-postbranch in your local repo - Work is done to complete the new feature and
git commitis executed to save the changes - You then push the new
featurebranch to your remote forked repo - Using GitHub you open up a pull request for the new branch against the original repo at Canada-ca/blogue-canada-ca-blog
The Forking Workflow helps the maintainer of Canada-ca/blogue-canada-ca-blog open up the repository to contributions from any contributor without having to manually manage authorization settings for each individual contributor. This gives the maintainer more of a "pull" style workflow. Most commonly used in open-source projects, the Forking Workflow can also be applied to private business workflows to give more authoritative control over what is merged into a release. This can be useful in teams that have Deploy Managers or strict release cycles.