Git gud

So what the heck is Git

Git is the most popular version control system (VCS) out there. In very general terms, a VCS is a system that keeps track of files and actions in a project, serving both as a changelog and as a backup. Want to roll back to a previous version of a file? Git has you covered. Want to roll back your whole project prior to a massive bug? Git has you covered. The point of git? Git has you covered.

The place where all your files are stored is called a repository. With git, this repository is downloaded by all members working on the project, giving it a decentralised structure: if you delete your copy, not all is lost. This stays true even if the repository is hosted on a central main server. The point of decentralisation? Git has you covered.

Wow, filesize pls

Git doesn't actually store a copy of all versions of all your files: it stores the differences between different versions of the files, which helps keeping filesize down but also to see the exact changes. But enough with the backstory, let's see how we can use it.

Gimme git

Sure. The only cost is checking out the installation guide. Once you have your shiny copy of git, let's get started with using it.

Basic basics

Git may seem scary at first and you may think it's all about command line interfaces (CLI) and you gotta remember stuff. Luckily that isn't true. This isn't some high school exam, you can have this guide or any git documentation open all day any day. You can even lean back in your chair! You will naturally pick up the basic commands and logic as you use them, but try to sit straight to also pick up good posture.

If you're still concerned, Git also has graphical user interfaces (GUI) and most of the work will be done with integrations in your favourite code editor. Yes that is correct, unless you want to feel like a hacker, you will only need the CLI when something goes very wrong.

Creating a repository

In case you are using the command line, creating a new git repository or converting an existing folder into one is as easy as typing git init in the directory (fancy word for folder) on your machine.

Checking out a repository

Repositories can be either local or hosted on a server. Checking a repository out means creating a copy of it elsewhere. It is often referred to as "cloning".

If the git repository is local, you can make a copy of it using git clone /path/to/repository. If however you want to get a local copy of a remotely hosted repository, you can get it using git clone remote-link. There are two types of remote links:

  • HTTPS urls: https://host.name/path/to/repository
  • SSH links: username@host:/path/to/repository

Cloning a repository over SSH often requires you to set up SSH keys, but all main git host platforms have their easy to follow guides on how to set up these keys.

Git isn't a spy

Git isn't watching your files by default, which means it doesn't track changes to your files unless you tell it to. If you want git to know about your files, you need to add them to the Index, commonly known as staging area. There, git stores the cumulative changes made to the file since the last checkpoint in git's history.

Since you wouldn't want to record every single time you save a file, as not every save is a meaningful step in your project, files in the staging area aren't stored in the git history (Index has its own temporary history). When your files reach a state that you would like to record, you commit these files. Committing the files saves the staged changes to the git history, where they will stay for good.

Letting git know

You can tell git to watch a file using git add <filename> or git add . to add everything in the directory to the watchlist.

Again, since since git doesn't update its history on each file save (like OneDrive for example) you commit your changes using the git commit -m "Commit message" command. This saves the changes with the message you have set.

It's a good idea to have simple and clear commit messages, so that you can later understand and find changes in the git history.

Letting the world know

Committing files saves them in your local copy, however if you are working with remote repositories you have to upload your changes somehow. This is done via the git push command. The full syntax for this command is git push <repository> <branch> but more on that later. If you haven't configured specific remote repositories, the default is "origin". The default branch is "master".

On that note, if you haven't cloned from a remote repository, you can add the remote repository using git remote add origin <server>, where "server" is the HTTPS or SSH link. Replacing "origin" allows you to create and name multiple remote repositories such as "upstream", but that falls out of the basics.

Getting updates

Sometimes the remote repository gets updated as you are working on the local copy. In that case you can update your local copy using git pull. When you pull, you tell git to fetch files and merge them.

Sometimes conflicts happen when git is trying to merge files into your local repository. Such issues may also happen when you are pushing into a repository. What to do in these cases is a topic for later.

More stuff

Branching

Where git truly shines, is in it's implementation of branching. Branching is the concept of experimenting with new ideas or working on different versions, without ever affecting your main files. If it didn't work out, delete it, if you like what you made, merge it back with the main files.

Git branching example

To make a new branch and then switch to it, use the command git switch -c branch_name. To simply switch between existing branches, omit the -c option. You can delete a branch using git branch -d branch_name.

You have now created a branch on your local machine, however neither the remote repository nor others may access it unless you push it. To push a branch, you can use the command git push origin branch_name, assuming you haven't changed your remote repository's name from "origin" to something else.

Merging

Merging is all about combining files and branches. To merge another branch into your active branch you do git merge <branch>. Make sure you're in the branch you want files to be merged to, and not the branch you want files merged from.

Sometimes, when the changes made to files are incompatible, a merge conflict will occur. In these cases you will have to resolve them by choosing for each conflicting section which variant you would like to keep. This is usually done from within an editor and not CLI.

Once you have solved the conflicts, dont forget to mark the files as merged using git add <filename> which we are already familiar with.

We saw earlier that git only stores differences in between files, not copies of each file. These differences can be viewed in the git diff format, and they are best viewed in an editor or using the web UI. To view differences in between branches from the CLI, such as before merging after fetching for example, use git diff <source_branch> <target_branch>. More about the diff command here.

Logging

Since git is all about tracking, there needs to be a way to see all the git history. This is called the git log and you can view it by using....git log. The log is very useful when you need to get the hash of a particular commit, in order to get more information about it.

A useful command to get the changes from a particular author is using the --author=name option. There are many many options to the log command so you're better off using git log --help than reading them here.

Tagging

Tags can help you in finding a particular commit, and to keep even better track of files. For example, it is good practice to tag all released or release ready versions with a release number, kind of like Minecraft. You can tag a particular commit using git tag tagname hashid, where hashid is the first 10 characters of the commit's hash. The ID isn't necessary for the current commit.

Signing

If you're paranoid, or just fancy, you can sign your commits and tags using a GPG key. This identifies the commits to your email and checks them with your online account's key (GitHub, GitLab, Bitbucket, ...).

Below are links to how to generate and add GPG keys to the three major platforms:

What next

Wow that was a long read, but you made it through. You should now know how to use or at least have an overview of the basic git command and tools, and can start using them for work, school, fun, in bed, .... Learn git by using git, and soon you'll dabble in more advanced concepts. If you're interested in working with the Yuuto project, be sure to check out the workflow guide, or the knowledgebase for more in-depth git info.

There are a lot of great guides out there, and it's a good idea to have a git cheatsheet open when starting out with git. If something goes wrong, check out the documentation, other guides or forums. And don't hesitate to ask in the development server.


Some useful resources: