Categories
Uncategorized

GitHub Basics

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.

The basic flow that I use almost every other day.

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.

Forking

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

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.

Making Changes

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.

Staging Changes

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.

Committing Changes

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.

Pushing Changes

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.

Pulling Changes

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>.

Conclusion

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.

Leave a Reply

Your email address will not be published. Required fields are marked *