I found this very strange, that all around the Internet there are lot of articles on how to do some extended techniques using git. But nowhere can find short, simple and easy recommendations on how to use GitHub to work on shared project.
This article is effort to describe typical workflow on shared project using git on GitHub.
What do we have?
To work on project you must have GitHub account and must have installed git on your working computer.
Create fork of project using web-interface.
So you’ll get forked project in your repositories list.
If your account name at GitHub is
johndoe, you’ll get new repo called
git clone https://github.com/johndoe/mixxx.git.
You can do everything you want with forked project. You can do any changes with it. That can’t hurt main (parent) project.
To get ability to work on project on local computer you must clone forked (on previous step) project.
As for me, that is very useful to hold all clones from different repositories in one folder like
~/Projects/working_copies. So we need to get into that folder (
cd ~/Projects/working_copies) and apply command:
git clone https://github.com/johndoe/mixxx.git
This command will create new directory
mixxx within all source codes got from
Of course, we want to update our repository’s codebase from parents’ one. So we need to “link” parents repository to ours:
git remote add upstream https://github.com/mixxxdj/mixxx.git
By default you are on
master branch. You can check it using command
This command outputs list of available branches. Near one of branches there must be asterisk (*) — it means that you are on that branch.
If you are not at
master branch, you can switch by next command:
git checkout master
And immediately update this branch according to (probably) new changes in parents’ repository:
git fetch upstream // got changes from upstream git merge upstream/master // merge branch upstream/master with current (local master)
To upload all changes to your remote repository (do update of remote repo), you need to:
provide login and password.
In this manner we can work on project adequately. Lots of developers advise do not touch
master branch and do all changes into separate branch.
For switching between branches you can use
git checkout branch1
To create new branch (named
newBranch by copying that branch you are standing on now):
git checkout -b newBranch
So, when you have local clone you must create new branch, named for example
git checkout -b johndoe_fixes
Further, you must work on project at this branch. Here you must do all your commits.
For example, fix all changes with some message:
git commit -a -m "Fixes a ton of bugs..."
Your branch is only local branch (there is no such branch on your remote repo), you need upload this brunch to your remote repo:
git push origin johndoe_fixes
provide login and password.
If you have already done all steps described above then you can see fork at GitHub site in your repos. That fork will have branch
You can choose that branch and track all changes. Also, here you can make request (to developers of parent project) to merge your changes with parent project. This procedure calls “pull request”. To avoid ambiguity, here “pull” means that developers of parent project will do
git pull to your branch (got your changes and merge with parent’s master branch), of course, if your changes are adequate and will look good to developers.
To make pull-request you need open GitHub site -> your repo -> choose your branch -> on right vertical menu click “Pull requests”.
Pull requests -> New pull request -> Edit.
Here, you must choose (if not was not chosen automatically) base fork: parents repo and its master branch: head fork: your repo, compare: respective branch —
Do not forget comment your changes well.
After successful pull request, your branch will get on code review. Watch you e-mail box. Developers can discuss your changes. Be ready to have responsibility for your changes.
If your changes deserve to be merged with main project — your branch will be merged with master branch.
Quick review of all commands:
- Fork project А on GitHub — into own projects (fork got address B).
git clone B
git remote add upstream А
git remote checkout master
git fetch upstream
git merge upstream/master
git checkout -b newBranchFeatures
git commit -a -m "Added new features"
git push origin newBranchFeatures
- Pull request.
Have a nice commits and successful builds!