Basics of GitHub collaboration : A layman’s guide

Photo by Yancy Min on Unsplash

Disclaimer : This tutorial is designed to give the reader a basic working knowledge on how to work on a collaborative project using git. The article is based on the author’s personal experience and thus it may contain some technical errors/misconceptions (the reader should never hesitate to bring such issues to the author, whenever found). One should not completely rely one this document only, the author highly recommends to go through other git tutorials available on the net.

Basic setup : In this tutorial I will present a demonstration of how you can work on a collaborative project on GitHub, with a basic example. I wrote this tutorial while working on a Image Processing project https://github.com/Subhasishbasak/emoji_analysis, to encourage people who are new to git and its application. You need to have your own GitHub account first. Now suppose you want to collaborate to an existing GitHub repository, for e.g Subhasishbasak/emoji_analysis. There are two ways you can do that,

1. fork

Git Fork means you just create a copy of the repository to your own GitHub profile. Here you can experiment whatever you like without affecting the main source of that project.

• In this approach you WILL NOT be listed as a direct collaborator to the project.
• Go to the repository using : https://github.com/Subhasishbasak/emoji_analysis and click on fork.

forking a repository

• This will create a copy of this repository in your own GitHub profile.
• Now you can clone (described later, see section 3) the FORKED repository locally to your machine and start your experiments.
• You can share your work with the main repository by creating a pull request(described later).

2. Direct collaborator

To be a direct collaborator to the repository, first you are need to be added as collaborator, which can be done only by the owner the main repository. You will receive an email letting you know that you are added and will be listed
as a collaborator.

• In this approach you will work as a direct collaborator (listed on the repository).
• Once added as a collaborator, go to the repository using : https://github.com/Subhasishbasak/emoji_analysis

cloning a repository

• Click on Clone or download and copy the link for Clone with HTTPS. DON’T FORK.
• Now you can clone (described later, see section 3) the MAIN repository locally to your machine and start your experiments.

Clone

Now, the following steps demonstrate how to clone a repository. Cloning a repository makes a copy of the repository locally in your machine, so that you can make changes to it and push it back to the repository whenever
required. Firstly install git following any standard tutorial.

Steps to follow :

Once you are ready with your git installation and have the clone link copied from the repository, just follow the simple the steps.

• Select a working directory and cd into it.

$ git clone https://github.com/Subhasishbasak/emoji_analysis.git
$ cd emoji_analysis

cloning a repository

• And now you’re ready to collaborate!

Collaborate

Once you have the repository in your local machine, you can now start your work. For collaborating in GitHub you need to know 5 basic commands,

• git status : to check the current status of your local repository and the remote main repository.
• git pull : suppose your partner has made some changes in the repository after you cloned it. This command will fetch all the current changes to your local repository. (to be used cautiously, described later)
• git add : suppose you have made a local change. This command will ”add” the change LOCALLY in your repository.
• git commit : after ”add”-ing the change you need to commit the changes.
• git push : after ”commit”-ing the changes you can push it to the remote MAIN repository.

The following demonstration shows how you can create a dummy file and push your changes to the main repository. Follow the sequence carefully.

• Check status : Always run status a check before & after you start doing anything. This is really helpful to avoid mistakes! just run ..

$ git status

For our case we haven’t yet done any changes so it will say,

>> On branch master
   Your branch is up to date with ‘origin/master’.
   nothing to commit, working tree clean

This means there is no difference between your local repository at the current time compared to when you last pull-ed / clone-d it/ push-ed all changes. (things will be clear, just bear with me).

• Pull : Once you are assured that there is nothing to commit, ONLY THEN you do a pull. This will fetch all the changes that are done after the last time you pull-ed / clone-d repoitory. For our case, let there are no changes done so we’ll get something like this,

$ git pull
>> Already up to date.

This means your local repository is up to date with the remote main repository. It is always recommended to pull all the changes before making some new commit.

• Make the changes : Now we create a new python file named kiddo.py, which prints ”Hello kiddo”; inside the code directory of the local repository. Once you create the file check status and you get the newly created file as Untracked files written in RED.

git add

Now we are just left to : add –> commit –> push

• Add: just run code,

$ git add kiddo.py

and check the status. Now it will show the file names just added in GREEN as Changes to be committed.

• Commit: just run the code with a suitable message. “-m” is used to add the message/comment.

$ git commit -m “kiddo file added”

and check status. It will say,

>> On branch master
   Your branch is ahead of ‘origin/master’ by 1 commit.
   (use “git push” to publish your local commits)
   nothing to commit, working tree clean

git commit

• Push : The last step is to push your changes to the remote repository.

$ git push

And finally it is done. You can see the changes you just made at the on the remote repository.

If you have understood till this you are ready to collaborate, but wait…wait…..wait…
By this time you might be thinking , what if several collaborators modify the same file and push together? OR what
if someone else already changed the file I am modifying ? Certainly, it will create a mess. Thus one should follow certain rules to before implement the chain add–>commit–>push, to avoid conflicts with the other collaborators.

The solution is branching. I personally found this tutorial very helpful for understanding the concepts. To understand branching you can visit https://medium.com/@jonathanmines/the-ultimate-github-collaboration-guide-df816e98fb67.

In this tutorial I have shared my experiences on the GitHub collaboration basics and explained the chain of add → commit →push, which is very basic but also serves as the building block of the main workflow using git. One should always keep in mind that this is just the tip of the iceberg. There is a whole lot of things you can do using git. Keep exploring !

Do not hesitate to contact me if you have any suggestions, comments.