On using Git [TUTORIAL]

Well, this is obviously a Github page so I kinda have to know how to use Git, I'll give you that but this is more like a kinda tutorial for people that might not be familiar with it, so if you've been trying to learn how to use Git or you're just curious as hell then keep reading this.

Since I've been using it, at first out of curiosity and later on to manage my thesis project implementation and managing the project I was collaborating on my previous job, I've found it incredibly usefull for software development and I really wish that I knew it earlier on my "career", so...

What is Git?

According to the Git official page, "Git is a free and open source distributed version control system designed to handle everything from a small to very large projects with speed and efficiency", it was designed by Linux creator Linus Torvalds.

How to use it?

Well, obviously before you can use Git you need to install it on your computer, the process for this actually depends on the operating system you're on, if you're using a Linux distribution this is easier since Git is most likely to be on your distribution's software repository and you can install it using a package manager. Whether or not you're a Linux nerd like myself you should find this guide usefull for installing Git on your system.

Now that you've installed Git on your computer the next thing you need to do is "introduce yourself" to Git, this is needed so Git can "sign" your operations like this:

Author: Your Name <username@domain.com>

This is achieved by doing this on a terminal:

$ git config --global user.name "Your Name"

$ git config --global user.email username@domain.com

NOTE: By the way, pretty much everything we're doing from this point it's going to be done using Git's command line interface, yes... Using a terminal (I did mention that I'm a Linux nerd).

Creating a new Git repository

Now, you need to choose the project you want to place under Git revision control, whether it's an existing project or a new one this is done as follows:

$ cd /path/to/project/folder
$ git init

Now that you have a Git repository initialized on your project's folder you may create or modify any file that integrates your project, next you need to tell git which are those files as follows (you need to do this everytime a new file is created and you want Git to track it):

$ git add file_1 file_2 ... file_n (in case you want Git to track some specific files)

$ git add . (in case you want Git to track every file in the folder)

This will make Git take a snapshot of the contents of those files and store them in a temporary staging area called the "index".

NOTE: If you want Git to automatically ignore certain types of files, for example the .o files generated by compiling C code, you must create a file named .gitignore, where you can list the types of files you want to be ignored by Git, you can read more about it here.

Making changes

Once you've modified your project's files and, for example, finished a feature you've been working on you need to update the new file contents to the index (using git add as stated before) so you can permanently store those changes in the repository by commiting them:

$ git commit

This will prompt you for a commit message, Git will open whatever you've set as your default text editor (if you haven't set this it will most likely be either nano or vi) with a commit message template which you can edit to describe the changes made by your commit. If you're more of a vim/emacs kind of guy you may configure git to use your prefered editor by using git config:

$ git config --global core.editor vim

Alternatively, instead of running git add beforehand, you can use:

$ git commit -a

This will add automatically any modified (but not new) files to the index and commit all in one step.

NOTE: At any point you can see what changes have been made to the tracked files using git diff, you can also get a brief summary of the current state of your repository using git status or even view the history of your changes using git log.

Project branches

A Git repository can maintain multiple branches of development, branches are usefull to implement "experimental" features which you're not sure if you can even do or because you don't want to mess with the current "stable" state of your project. To create a new branch named "experimental", use:

$ git branch experimental

Now, if you run git branch you'll get a list of all the existing branches with an asterisk marking the branch you're currently on (the "master" branch is the default branch of development for your project). To switch to your new "experimental" branch run:

$ git checkout experimental

Now that you're on your experimental branch you can modify any file that you want and make as many commits as you need and none of these actions will affect your "master" branch. If you want to integrate the changes you made on your "experimental" branch into the "master" branch switch back to your "master" branch and then merge the changes made in the "experimental" branch:

$ git merge experimental

If the changes don't conflict, you're done! All of the new changes will be on your "master" branch. If there are conflicts, Git will mark the problematic files showing the conflict, if you now run git diff you can see them. Once you've edited the files and solved the conflict you need to commit those changes to finish the merging, at this point you could delete the "experimental" branch as follows:

$ git branch -d experimental

This command ensures that the changes in the "experimental" branch are already merged into the current branch. If you started an "experimental" branch and then realized that it was a bad idea you can delete this branch without merging the changes using:

$ git branch -D experimental

Tagging

Git has the ability to tag specific points in history as being important. Tipically, people use this feature to mark release points (such as v1.0 and so on). Git uses two main types of tags: lightweight and annotated. A lightweight tag it's just a pointer to a specific commit, annotated tags are checksummed; contain the tagger name, email and date; have a tagging message and can even be signed and verified with GPG.

You can create an annotated tag by using:

$ git tag -a v1.0 -m "Releasing v1.0"

The -m option specifies a tagging message, while the -a option specifies that this is an annotated tag.

To create a lightweight tag use the same command as before without the -a and -m options:

$ git tag v1.0

Both of this commands will tag the latest commit, if you want to tag a specific commit you need to specify that commit checksum (or part of it) at the end of the command:

$ git tag -a v1.0 -m "Releasing v1.0" 9fceb02

Using a remote server

Up until this point, all the actions described are done in a local repository and this is usefull when you're developing a project on your own, however, if you need (or want) to collaborate with other developers or just keep your projects in a Git repository hosting service like Github you need to add a remote server to your Git repository. This can be done by using:

$ git remote add shortname remote.repository.url

This will add a new remote server to your Git repository identified by shortname, you can list all of the remote servers configured on your Git repository by running:

$ git remote -v

Now that you configured remote servers on your Git repository you can get data from a remote repository by running:

$ git fetch remote_shortname

This will go out to that remote repository and pull down all the data from that remote repository that you don't have yet. After this you could merge those changes to your local repository's current branch by running:

$git merge FETCH_HEAD

Alternatively, you can use:

$ git pull remote_shortname

This will automatically fetch and then merge a remote branch into your current branch.

You can also send your local changes to a remote repository by using git push as follows:

$ git push remote_shortname brach_name

NOTE: This will only work if you have write access to that remote repository and if nobody else has pushed in the meantime, if that's the case your push will be rejected, you'll have to pull down those changes first, merge them into yours and then you'll be allowed to push.

Finally, you can also clone remote repositories by using:

$ git clone remote.repository.url

---

As you can see, Git is a tool that provides us with some very usefull features when developing software projects, whether you do it alone or with a team. In this post I only covered what I consider to be the basics of Git, if you're interested in knowing it more deeply I invite you to read its documentation.

Finally, I'd like to share the Github's Git cheat sheet, I found it incredibly usefull when I was learning the basics myself.

Happy coding!