Github Triangular Workflow
Our GitHub workflows follows a triangular pattern. The project begins with a fork of the original repository (upstream), referred to as the (origin) repository. Development will be conducted on a local clone of the forked repository (origin). Any changes made will be committed back to the forked repository (origin). When ready to contribute, a pull request will be submitted from the forked repository (origin) for review, and upon approval, the pull request will be merged into the (upstream) repository.
Follow the below steps to implement this workflow for your projects.
Github
On your GitHub account, create a fork of the repository you would like to work on. In this guide, it will be referred to as (yourfork).
Local
Clone a copy of your forked repository on Github to your local computer:
1
git clone [email protected]:<your-username>/yourfork.git
Remotes
Since you have cloned the repository from your fork, the origin remote should look like this:
1
2
3
git remote -v
origin [email protected]:<your-username>/yourfork.git (fetch)
origin [email protected]:<your-username>/yourfork.git (push)
To keep your local repository in sync with the main developer repository, add an upstream remote with the following command:
1
2
3
4
5
6
git remote add upstream [email protected]:<developer-name>/<repository-name>.git
git remote -v
origin [email protected]:<your-username>/yourfork.git (fetch)
origin [email protected]:<your-username>/yourfork.git (push)
upstream [email protected]:<developer-name>/<repository-name>.git (fetch)
upstream [email protected]:<developer-name>/<repository-name>.git (push)
Now, to sync your local branch with the developer repository, run the following from your (main) branch:
1
2
git checkout main
git pull upstream main
You can omit upstream main from the git pull command by setting your main branch to always track the (upstream) repository. To achieve this, run the following command once from your (main) branch:
1
2
3
4
git branch --set-upstream-to=upstream/main
git remote set-branches upstream master
git config remote.upstream.tagopt --no-tags
Now, the following command syncs your local main branch with the (upstream) repository:
1
git pull
Branches
Before you start working on changes, create a new branch:
1
2
3
4
git checkout main
git pull
git checkout -b new-feature
$ # You are now in the new-feature branch.
Commits
When running git commit try to use a good explanation of the changes in the commit message.
Updates
Push your branch back to your forked repository (origin) and set it to track with -u:
1
2
git checkout new-feature
git push -u origin new-feature
You can omit origin and -u new-feature parameters from the git push command with the following two Git configuration changes:
1
2
git config remote.pushdefault origin
git config push.default current
The first setting saves you from typing origin every time. And with the second setting, Git assumes that the remote branch on the GitHub side will have the same name as your local branch.
After this change, you can run git push without arguments:
1
git push
Then go to the repository page and it should prompt you to create a Pull Request from a branch you recently pushed. You can also choose a branch manually.
Pull Requests
From your forked repository on Github you can submit a pull request to the developer repository if you would like to contribute.