I confess: I have a love-hate relationship with Git. I signed up for a GitHub account back in 2013 during college when I heard that it was all the rage among the cool coder kids… and never got around to using it. The command line was too bloody intimidating, and what was all this push pull merge branch stuff?
So I am ashamed to admit that spent my college and postgraduate days doing my own ‘version control’ by saving a billion copies of “Assignment_final”, “Assignment_final2”, “Assignment_final_for_real” on multiple devices and Google Drive (funny thing is, I wasn’t the only person in my class who did this, not by a long stretch). It was incredibly inefficient and downright stupid. I would’ve saved heaps of time if I’d invested some up front in learning Git.
This year, I finally made myself dig in my heels and commit to learning Git and by conjunction, GitHub (as I understand it, Git is the version control system and GitHub is the hosting service for Git repositories). I gritted my teeth, armed myself with a bunch of tutorials, and plunged into the unknown.
After a good deal of frustration, I managed to get some of my old coding projects up as repositories on GitHub. Shortly thereafter, I decided to apply for an Android development project in the Outreachy Dec ’15 program, which, surprise surprise, involved the use of GitHub for collaboration. Several bugfixes later, I think (or would like to think) I’ve finally gotten the basics of Git(Hub) down.
I noticed that a lot of the tutorials I found were extremely theoretical, which is good for someone who already has a basic grasp of Git and really wants to understand how it works under the hood, but not so good for someone who is completely new to it. The github.com website itself has a mini ‘getting started’ tutorial, which is pretty good, but it omits some important things IMO.
So I figured I should share my little Git(Hub) tutorial, partly for my own sake (I have a terrible memory!) as well as to hopefully help fellow Git(Hub) newbies.
First things first…
You don’t need to know command line to use the basics of Git(Hub). There are lots of people who manage their repositories solely by command line, but you don’t have to if you don’t want to. My main tools for managing my GitHub repositories are:
- The GitHub desktop client
- GitHub.com – the website where you can browse your own repositories and those of others. Your repositories are linked to your GitHub page. For instance, my GitHub page is https://github.com/misaochan and the repository I’m working on currently is https://github.com/misaochan/apps-android-commons
Sign up for an account at github.com. Download and install the GitHub desktop client. Now you are ready to start working on a repository.
Forking a repository
If you are contributing to open source, this repository likely already exists on someone else’s GitHub page. Go to that page and fork their repository. That will create your own repository that is a copy of the upstream repository. In my case the upstream repository’s URL is https://github.com/nicolas-raoul/apps-android-commons and my forked repository’s URL is https://github.com/misaochan/apps-android-commons.
Next, click the ‘Clone in Desktop’ button on the right hand side of your own repository page. This creates a local copy of the repository on your hard drive. Now you have 2 copies of your repository, the local copy (also called working copy) stored on your machine, and the remote copy (also known as the origin) stored online.
Building the project and setting up your VCS
GitHub repositories usually consist of uncompiled code, so you need to build the project once you have cloned a local copy of it. To do this, follow the instructions on the README.md of the upstream repository (scroll down on the main page to view this readme file). If your project has no build instructions, talk to the owner of the project.
Once you have built your project, you need to hook that project up with Git (I don’t think cloning in and of itself creates a link). Open the GitHub desktop client and drag the folder containing your project into the client. Follow the steps in the wizard and voila, your local copy is powered with the Git version control system and ready to go.
Before you make any changes to the code, create a branch. You do this by clicking the branch icon at the top of the desktop client and naming it. Now all your local code changes will be saved to this branch.
You can have multiple branches in your repository, and the default branch is called master. Normally you work on a certain feature or bug in one of the other branches (not in master). Later on you can merge branches back into master.
Once you have made a change to your code, you can commit it. This saves a snapshot of your code at a point in time to your remote repository (aka origin). If you set everything up correctly, your desktop client should automatically detect changes in your project folder (make sure you are in the ‘Changes’ tab). So committing is as simple as typing in a description of your code changes, and clicking commit.
An important thing to note is that you should commit in small, modular amounts. Don’t save everything for one large commit. The reason for this is that you can easily revert a commit (by clicking ‘Revert’ in your desktop client), but you cannot easily revert half-a-commit if you want to keep some of the changes you made and discard the rest. An interesting thing to note is that reverting a commit creates another commit in the project history. So everything you do is recorded. 🙂
Merging/submitting pull request
Once you are satisfied with your code changes, you have 2 major options.
- You are working alone, or not yet ready for your code to be pulled into the upstream repository but you are done with this bugfix/feature and want to work on another. In that case you should push the changes to your remote repository (by clicking ‘sync’ on the top right of the desktop client), then merge your branch with master.
- You are ready for your code to be pulled into the upstream repository. In this case you want to submit a pull request to the upstream repository. Click ‘submit pull request’ in the desktop client.
Also, if you are fixing a particular issue that has already been recorded in the ‘Issues’ list in the project page, type something like ‘fixes issue #4‘ in your pull request description. This automatically links your pull request to the issue.
If the owner of the upstream repository thinks your code is okay, he/she will merge your pull request into the upstream repository, which means that your code is now part of the upstream repo! Once that happens you should also merge your branch into the master branch of your own repo.
Keeping up to date with the upstream repository
There are multiple ways of doing this, but this is the simplest. In your desktop client, click ‘Update from upstream/master’. This pulls all of the changes from the upstream repo into yours. Be aware of which branch you are pulling from and into.
Using the command line
Occasionally, you will still need to use the command line for stuff that has not yet been incorporated into the desktop client. Click on the cogwheel and ‘Open in Git Shell’. This opens up a command prompt with your path already set to the project folder. Hooray, no need for cd-ing around!
So, these are some of the things I’ve learnt from my short stint with Git. 🙂 This learning is obviously still a work in progress, so feel free to comment and correct anything that needs correcting.