Git Branching for beginners

At first, diving into open-source development can seem like a convoluted Herculean task. So, you are here because you have just made up your mind to make open source contributions, either for GSoC or just for fun, but anyway, you being here is a big step towards anything because in the end knowledge is what that matters.

Up until this point, you must have

1. Created your GitHub account.
2. Decided an organisation and project to work on.
3. Forked the repository and made a local clone of it.
4. And you are scratching your brain as this ‘branching’ thing kills your progress.

Now, suppose the name of the organisation is ABC and you are working on a project called XYZ. Let’s proceed step by step from here

Forking the project

To work on XYZ, you need to fork it first. To put it in simple words, forking means getting a copy of the project in your GitHub account. All the changes that you wanna make or the features you wanna add, you will make them in this forked repo first, and then create a pull request (or PR) from here. (more on this later)

Cloning the forked repo

After cloning XYZ from ABC’s GitHub, you need to create a local repo of your forked XYZ. This is done by cloning. To clone your forked repo to your computer, do

$ git clone <link>.git

At this moment if you do

$ git branch

you’ll see a master branch only (or sometimes development branch depending on the project). This is the branch that should be kept updated with the original ABC’s XYZ repo.

From this point on, you need to remember two terms
1) Upstream — the original ABC’s XYZ repo (www.github.com/ABC/XYZ.git)
2) Origin — your forked repo of ABC’s XYZ (www.github.com/YourUsername/XYZ.git)

Making changes

The best practice says that you first create an issue in the ABC’s XYZ repo and mention whether it’s a bug report or a feature request. Then proceed with your changes.

To start making changes or developing patches, you need to first create a new branch. To create a new branch, do

$ git checkout -b branch-name

The branch-name format varies from organisation to organisation but generally, it’s of the form XXX-issue where XXX is the issue number. Let’s say our issue number is 145, and the topic is ‘fixing typos’, so my branch will be called ‘145-fixes-typo’.

At this moment, you will be in your new branch. The changes and the local commits you make in this branch won’t be reflected in the master branch of your local repo.

Suppose, you edited a file called example.py and you are done. Now you need to add it and commit it.

$ git add example.py
$ git commit -m "Fix typo in example.py"

After the above commands, your changes will be committed to the branch 145-fixes-typo. So if you navigate to the master branch, you won’t see the changes there. That’s the beauty of version control!

To see this yourself, navigate to master branch

$ git checkout master

And voila! It’s the same!

Now, you need to remember some branching commands —

git branch -> shows all the branches
git checkout -b py -> creates a branch named py
git checkout py2 -> switches to branch py2

Pushing Changes

So, your changes are committed to your local repo’s 145-fixes-typo branch and now you want to push the changes to the ABC’s XYZ repo. First of all, you need to push this branch to your forked repo (i.e, the origin), (www.github.com/YourUsername/XYZ.git)

To push the branch,

$ git push origin 145-fixes-typo

Git will then ask your username and password. Enter it and then open your forked repo in a web browser. You’ll see a light brown bar to create a pull request.

Creating a Pull Request

Pull request tell you about the changes you’ve made to the repo and it indicates to the maintainers the changes you want to push to the repository. In a PR, the maintainers can see the difference your code has made and decide if it’s worth merging or not.

To make a PR, click ‘Create Pull Request’ in that light brown bar. Then you’ll see the name of your commit appear there. Click ok and you are ready to go!

Wait for the maintainers to merge the PR and you are done!