Git In Five Minutes
I wish I had learned to use Git (and by that I mean using ALL of Git, not just commit and push) a lot sooner than when I actually did. Knowing Git isn’t an absolute necessity when you’re just working on your own personal project. But when contributing to open-source or to your company’s repo, it’s an essential skill if you want to avoid looking like a complete fool.
I’m gonna assume that you have at least a basic understanding of Git as whole. But before we dive in, a few words about Git interfaces…
Use a f*cking Git GUI
I’ve heard so many people say that the only real way to use Git is through the command line. That is simply not true. In fact, you’re much more likely to make mistakes that way, especially if you’re just beginning. A GUI provides you with a lot more visual information, and confirmation dialogs to prevent you from making stupid mistakes. Plus, you won’t have to spend hours browsing the man pages looking for the right flags to use.
I personally recommend Sourcetree by Atlassian (the same company behind Bitbucket and Jira; they also have great in-depth Git tutorials on their website).
Understanding the terminology
The first and foremost hurdle when starting to use Git seriously is understanding the jargon and all its confusing metaphors. It starts with understanding Git’s versioning areas (I came up with that name because I couldn’t find an official one online). Your source code, as is, independently of Git’s own metadata, is referred as the workspace / work directory. From there, you add (or stage) code to the index (also referred to as the staging area) before committing your changes on your local repository. Once changes are committed on your machine, you can push them to the server (i.e. origin, the remote repository, upstream).
Note that the workspace is the only place to actually contain your source files. Git only takes note of the changes that happen across each version. Git saves all its information in the .git folder, located in the root folder of your project.
Why would you want an index?
It seems kind of needlessly complicated, doesn’t it? Well, the idea is you might not want to version-control every file in your source code (i.e. local config files). You might also want to split your changes into multiple commits. Remember, Git’s main purpose is to enable collaboration between developers. That means your commits may (and will) be reviewed by other people. As such, it’s in your best interest to keep your commits as simple as possible. Keep your changes focused on a few files and on a single feature. This is where the index comes in. The index allows you to select which changes will go into your next commit and which don’t. You can stash whatever changes you want keep for later.
Fixing your mess: reset and revert
Chances are, when you’re starting out, you will mess up. Every. Damn. Time. That’s okay. Git provides you with the reset command for effectively erasing your last un-pushed commits and optionally returning them to the index. You can also reset specific files. revert, in turn, only creates a new commit that is the complete opposite of the specified commit, effectively canceling it. This is very useful for undoing changes that have already been pushed to the server.
Understanding branching models
Git’s true power comes from its powerful branching system. Your project may at anytime have multiple versions in the works. It may have various people and teams working on different features simultaneously. Imagine if whenever somebody from another team made a breaking change to the code, you lost the ability to compile the program also. That’s the problem branches aim to solve. There are many different models for working with branches, one of the most popular being Gitflow. But this is beyond the scope of this article. The main takeaway should be this:
- Production releases and development builds should be on separate branches.
- Nearly all work should be happen on feature branches i.e. small branches dedicated to a single task. This enables non-disruptive cooperation while keeping merge conflicts easy to reason about.
Merging versus rebasing
A picture is worth a thousand words:
One of the most important rules behind Git’s philosophy can be stated as follows: DON’T MODIFY PUBLIC HISTORY. EVER. The only exception for this rule is when you accidentally publish a private key (in which case there exists specialized software to help you). Rebasing results in cleaner-looking history by letting go of the “polluting” merge commit. But it does so at the cost of modifying history. If rebasing is used on a public branch, this could be very confusing for other developers. In case of doubt, use merge.
Writing good commit messages
There’s a whole etiquette to follow when writing commit messages. If you don’t, commands like log might start misbehaving and the ghost of Linus Torvalds may or may not begin to roam your house. The important rules are:
- The first line should be written in the imperative and give a brief description of the commit in 50 characters or less.
- If necessary, further paragraphs should be preceded by a blank line and provide a more detailed explanation of the changes and be wrapped at 72 characters.
You can read more about this here.
Understanding pull requests
So by now you might have heard of pull requests. “Pull requests are how you collaborate!”. Actually, pull requests aren’t even a feature of Git itself. They’re part of the hosting service you use i.e. GitHub, Bitbucket or GitLab. Pull requests can be made in two different ways. The logistics will depend on your repository privileges.
If you own the repository or you have been added as trusted collaborator, then you can freely push to the repo. Even then, for collaborative projects, it’s good practice to create a pull request when merging (“pulling”) branches. That’s because pull requests provide a place for other collaborators to discuss and review your changes.
If you’re just casually contributing to an open-source project, chances you don’t have push access to the repo. But no frets! Hosting services allow you to fork the repository, which is to say “clone it on the server-side”. This way, your account will possess a carbon copy of the project from which you can work. Once you’ve completed your feature / fixed your bug, it’s time to create a pull request! Make sure to read the repo’s CONTRIBUTING.md document if it exists. Look at pull requests others have made in the repo to get a feel of the kind of info you need to provide. Pick the right branch to merge into, conjure up the best of your writing skills and hit that big green button!
Now go out and make something great!
