Happy #Hacktober everybody!
In light of the open-source season I thought I’d put together a guide to help people get up to speed with git better. Feel free to expand on what I write, my goal will be to convert everything into a blog post in the future.
What is git?
Git is a version control system that allows multiple people to develop code alongside each other at the same time.
There are some key terms for git that we’ll use as this guide continues:
Issues
Issues (example) are typically a github term (often referred to as work items outside of github) and are items of work that are outstanding on a project, however they are often used for raising bug reports or requests for assistance on a project that isn’t working as well.
Clone
When you want to download a git repository/project you clone it to your machine. You do this with:
git clone projectname.git
For example:
git clone https://github.com/codingo/VHostScan.git
This downloads a copy of the git repo, and all pushed (published) branches within it to your machine in a directory for you to work in (for exmaple, the following would download into ./VHostScan.
Branches
When you work in git you work in a branch. A branch is essentially a stream of work that can be independent from another branch. The “production” branch for a project is nearly always called “master” or “stable” and only working versions of code can be pushed to this branch.
After cloning a repository you can see what branch you are currently in with:
git branch
And you can view all branches in a project (locally and remote) with:
git branch -a
To change branches you “checkout” the branch you want to work on. If you checkout an existing branch you will change to it. If you want to work in a new branch, you checkout with the new branch name. You do this with:
git checkout <branchname>
It’s best practice to title a branch with your username, and a quick description of what you’re working on. For example, if I was working on VHostScan and adding a coloured terminal feature I would checkout as follows:
git checkout codingo-coloured-terminal
Commits
As you work on features you need to commit changes. These are hard points in time that you can revert to later, so I tend to think of them as save points and as I finish a feature I will make a commit. The main mistake I see is people committing too little. You can see an example commit log here. Clicking any of these commits shows the changes that were made in that commit.
Typically, if I finished a feature such as “reverse lookups” I’d commit that change before I started the next one.
You can do that by first adding all your current changes to the repo:
git add .
And then committing with a brief, but well explained commit name:
git commit -m <commit msg>
In this case:
git commit -m "Added reverse lookups"
Push
After you’ve made and committed your changes locally you will want to push your changes to the remote repo (in this case on github). You can push one commit at a time, or multiple changes. Typically I tend to push changes once I want to surface them to the public and make them visible. Since we’ve checked out a new branch and aren’t working in the master branch (never work directly out of master!) this won’t impact new visitors.
To push your changes you use:
git push
You will sometimes receive an error about pending remote changes. This means that somebody else has made changes remotely on your branch and you need to sync these changes before you can push your new one. I’m not going to dig too much into merging here, so for now, in most cases you can do:
git pull
To pull the new changes into your repository and then attempt to do your git push again.
Pull Requests
Once you have made your changes and committed them to your remote repository you will want to put int a pull request. A pull request is a request asking for your branch to be merged with another one. In the majority of projects this is saying “take the changes from my forked repo and make them a part of the public master”. The best way as a beginner is to do this in the github website. You can do this by clicking “New Pull Request” on the pull requests page of a project (example).
Questions / comments? Let’s open a dialog!
This post serves as a starting point. Have questions/comments about git? Let’s chat!
