If you aren’t sure how to use Git or GitHub, it can be a little tricky or challenging to start contributing to open source projects.
This post should help cover the essential information you need to start making contributions to GitHub projects.
In this post, I’ll cover how to clone a remote repository located on GitHub, create a new branch, make changes to an existing file, stage those changes, commit those changes and then push those changes back to the remote repository.
First you have to select a GitHub repository to work on! If you’d like to use a test repository, have a look at octocat/Spoon-Knife on GitHub.
You can click the “fork” button on that page, that will essentially copy everything in there to your profile. i.e. it will copy everything from octocat/Spoon-Knife to your-username/Spoon-Knife.
You could either work on a forked repository or just create a new one under your profile. It doesn’t matter, we aren’t doing anything serious. The point is, you need to have a repository under your account for testing purposes. That’s all.
Cloning brings the remote repository to your local machine, so that you can work on it, change/add/remove files, etc. But before cloning, please have a look at SSH authentication in GitHub. I’ll not be explaining that in this post and will assume that your machine is authenticated to GitHub via SSH.
Once you are ready, go to the GitHub repository, click on code, switch to SSH and copy the repository’s address.
Then open terminal on your computer and type in
git clone <repository> replacing
<repository> with the copied address and hit enter. It shall clone the repository to you local machine.
Creating A Branch
After cloning the repository using the terminal, you will find a new folder on your computer. You can move into it using
cd <folder-name> where cd command stands for change directory.
Next you can type in
git status to see which branch you are on and what’s the status of the current repository.
We don’t want to do all that, we want to create a new branch and then make changes to the files under that new branch. This can be done by typing in
git checkout -b <branch-name>. This will create a new branch and switch to it.
You can now try commands like
git status or
git branch to see which branch you are on right now.
You can now make changes to the files. For example, if there’s a file in the repository called readme.txt, you could open it using a code or text editor and change the contents of the file (add, update or remove content in the file).
Once you are done making the changes, go back and type in
git status. You will see some changes waiting to be staged and committed.
You can stage the changes using
git add command. It can be used as
git add . to stage all new changes (which includes changes to existing files plus any new files that were created).
If you need to stage changes to a specific file, type in
git add <filename>. And if you want to be more granular in your selection of what to stage, use
git add -p.
This is something I use on a regular basis. It helps me choose which portions of my code to stage for my current commit.
All the stages changes can now be committed using
git commit command. This will open up a text editor in terminal, it could either be nano or vim.
In this text editor, the first line you type would be the commit title. The second line should be empty. And anything from third line onward will be recognized as commit body/description.
Once you are done writing the commit title and description, you will need to save and exit the editor and your commit will be successful.
Note: If you switch into the vim text editor, you will need to type in
i key to switch mode to insert text, only then you can type in things. Escape key will get you out of insert mode. To exit without saving, type in
:q and enter. To save and exit, type in
:wq and enter.
If you switch into the nano text editor, the instructions will be pretty clear as they’ll be displayed on the screen. You can type in directly without any mode changes and exit by typing in
ctrl+x which then asks you whether you want to save your changes or exit without saving.
Now you can push changes to GitHub repository by typing in
git push origin <branch-name>. This will push your committed changes to GitHub.
If you visit GitHub now, you will get an option to create a pull request. What’s a pull request? It basically means you are requesting a code reviewer to review your committed changes and “pull” those changes into the master or main branch.
Bonus information: You may be wondering what’s “origin” here. Origin is simply a label for the repository you cloned. You can check this by
cd‘ing into your project folder and typing in
git remote -v. Remotes can be added and removed by
git remote add <remote> <location> and
git remote remove <remote>. Don’t worry about this if it seems complicated.
You’ll need to pull changes from the remote repository to your local repository from time to time as the remote repository could continue to get updates from other contributors and your local repository could get behind.
To catch up with the latest changes (i.e. to fetch and merge the changes from the remote branch to your local branch) you’ll need to type in
git pull or
git pull origin <branch-name>.
That’s all in this post. It gives you a basic idea of the flow that almost every developer follows on a day to day basis. If the details are confusing, just have a look at the first diagram of this post to get a visual understanding of this process. Thanks.