For those wanting to use git along with Github.
First rule: git and Github are different things. Git is a tool that manages git repositories. Github is the name of an online service which hosts several git repositories.
Let's assume that you want to contribute to qBittorrent.
- Make sure that you have installed git on your PC. This guide will be based on command line.
- Go to github and create an account.
- Navigate to qBittorrent's Github page.
- There you'll find an option to "fork" the repository. What this does? It clones all the qbt repository into a new repository owned by you. So now there are basically 2 repos that interest you. The official one your "cloned" one.
- Github gives a URL on how to clone locally a git repo that it hosts. Here is an important thing: Choose to clone locally your OWN (cloned) repo and not qBittorrent's official repo. For all purposes of contribution treat your own repo as the "official" and forget for a moment the true official one(qBittorrent). So now, locally you do all the changes you want and when done you push the changes to your own github-hosted repo. Because you have write access to your own github-hosted repo, you can perform any operation on it via the git tool(ie create and delete remote branches...)
- When you clone a repo locally, the git client adds an alias for it's URL. That alias is by default called "origin".
- But while I work on something the official repo might have additional
commits, how do I rebase on them?
Well, after you clone your repo locally you have to add qBittorrent's official
repo URL into your local git as an alias. You do this by issuing(while into
your repo)
git remote add <alias> <URL>eg alias can beupstream. Let's say that for the moment qBittorrent doesn't have any additional commits but you want to start hacking on your copy.
Second rule: NEVER hack on the same branches as the official ones. If you aren't experienced with git you'll create chaos and frustrate your self.
What do you do? Create another branch that you will work. Take for example
the "master" branch.(I assume that this is your current branch). Do a
git checkout -b <branchname> Keep the branch name short and descriptive.
This will create a new branch that will be based on the commits of the current
branch that you have locally.
Start hacking on it and commiting changes as you see fit.
In the meantime new commits have appeared in the official qBittorrent master branch.
What do you do?
Switch to your master branch by doing git checkout master. (git will
complain if you have uncommited changes).
Now, while on the master branch, you need to download the extra commits.
Just do git pull upstream master. (upstream is the alias you gave to the
official qbt repo as mentioned above). This will download the extra commits
locally. Now you have to incorporated them into your "hacking" branch.
There are 2 possibilities here.
a. the extra commits didn't touch any of the files you were working on.
All you have to do is git checkout <branchname> to go to your hacking
branch. Then git rebase master. It will add the extra commit to their original
order and then ontop replay your commits.
b. the extra commits touched the same files you were working on.
YOu basically issue the same commands as in a. However, the rebase may fail
you'll need to manually resolve the conflicts. Usually git is smart enough
to auto resolve minor conflicts.
Let's say you finished your hacking effort and you want to get your changes
merged into the official repo. How do you do that?
First you'll need to push your hacking branch into your remote repo(the one
you own on gihub, the one that is a clone of qbt). Just do git push origin <branchname>
Branchname is the name of the local branch you were hacking on.
After that you login into your github account via the browser and go to
your repo. Github will let you make a "Pull request" for your new branch.
This pull request will appear in the official qBittorrent repo. After that,
if it is accepted github will merge the commits from your repo into the official
qBittorrent repo.