Loading...
New webinar: "The Remote Job Search: My Microverse Journey" with graduate Paul Rail
Watch Now

Topics

A quick introduction to version control, Git, and Github

According to Atlassian, “​​version control, also known as source control, is the practice of tracking and managing changes to software code.”

With that in mind, Git is a distributed version control system that allows you to keep track of the changes made in the source code and all the people who have permission to do so. GitHub is a hosting service that allows you to manage Git repositories.

Git has three file states:

  1. modified - the file was changed but not committed to the database.
  2. staged - the file was changed and is set to go into the next commit.
  3. committed - the changes were stored in the database.

To stage the modified files, you should use git add. The most used options for add are:

  • `git add <path>` to stage a specific file or directory.
  • `git add .` to stage all files (except for the ones listed in the `.gitignore`).

To add ignored files, use `git add -f` (or --force).

Keep in mind that you can use `git status` to get a log of the files staged for the next commit. To upload all the committed local changes to the remote repository, you should use `git push`.

Why write a good commit message?

This is pretty straightforward - you should write good commit messages to save time. For instance, consider that you work in a team with _n_ amount of developers, and you all work on the same repo, constantly implementing new features and debugging when necessary.

At some point, you will face a bug that was introduced in the source code, not necessarily in the latest commit. If all commit messages are simply “add feature,” you will find yourself checking every single log and going through all the implemented changes, trying to understand the code until you eventually find the bug.

Whereas if you just keep good commit messages, you can easily find the buggy commit, understand what was implemented, and fix what needs fixing.

How to write a good commit message?

A good commit message should be two things: meaningful and concise. It should not contain every single detail, describing each changed line—we can see all the changes in Git—but, at the same time, it should say enough to avoid ambiguity.

Also, if there are so many changes in a single commit that writing an efficient short message sounds like mission impossible, you should consider breaking it into several commits.

For instance, consider that you added a bug fix and refactored two other components. But that same “fix” actually created a chain of other bugs. This means it would probably be necessary to revert it to the original state, losing all the refactored components. Even though it’s possible to recover the refactored components, it would take longer than necessary. Splitting the bug fix into its own commit with a specific commit message makes reverting easier down the line.

Git convention

Photo by Roman Synkevych

The Git documentation suggests a template for commit messages that includes a title, description, and footer.

{% code-block language="js" %}
[type] [optional scope]: [description]
[optional body]
[optional footer]
{% code-block-end %}

A `type` is a keyword that describes the task, for instance, `[fix]`, `[feat]`, `[chore]`, `[build]`. The `scope` refers to the module that is affected by the changes. The `description` is a short summary, ideally with less than 50 characters.

The `body` is a detailed text with 72 or fewer characters. You can read more about the 50/72 rule here.

Beware that the blank line separating the commit message title and the body is mandatory. Some commands, like rebase, can present an error if that blank space is omitted.

The `footer` is usually an external reference, like a Jira ID or issue number.

Git documentation also states that commit messages should use present tense and imperative mode:

Describe your changes in imperative mood, e.g., “make xyzzy do frotz” instead of “[This patch] makes xyzzy do frotz” or “[I] changed xyzzy to do frotz”, as if you are giving orders to the codebase to change its behavior

Git commit options

Now that you know a bit more about git and commit messages, let’s talk about the most used git commit options:

git commit -m “Your message”

The `-m’ allows you to write a commit message, that must be wrapped in quotations in that same command. Note that if you do not include the `-m’ you’ll be prompted to add a message. 

{% code-block language="js" %}
git commit -a
{% code-block-end %}

This command, or `git commit --all`, stages and commit files that have been modified and deleted. Note that newly added files, not yet committed, won’t be affected.

git commit --amend “Updated commit message”

If your message is not the issue, e.g., you just forgot to add a file, use:

{% code-block language="js" %}
git add <file_name>
git --amend --no-edit   
{% code-block-end %}

Note that `amend` should be used only if your last commit has not yet been pushed online. To edit older commits that have been pushed already, you could use `git rebase` (not recommended).

You can use more than one option at a time. For instance, `git commit -am` will stage all modified files and expect a message. 

Microverse’s commit message convention

A little disclaimer: More important than following strict rules or personal preferences on how and what to write in your commit messages is understanding that consistency is essential. For instance, if your workplace has a standard that uses past tense, long, and thorough commit messages, that’s what you should use.

With that being said, at Microverse, we go with: present tense, imperative, capitalized, and no period in the end (considering that most of our projects are relatively small, we usually just keep a title, with no body or footer). Here are some examples:

{% code-block language="js" %}
Right: Fix typo in README file
Wrong:
Fixed typo in README file. (past tense and period in the end)
Wrong:
fix typo in README file (not capitalized)
{% code-block-end %}

Commit to writing commit messages

Commit to writing commit messages
Photo by Marvin Meyer

Writing meaningful commit messages is an essential skill for every developer. It helps you to save time and maintain good communication with other collaborators. Even though there is no universal convention on how to write commit messages, you can use this article to guide you to figure out what works best for you and your team.

Apply For Remote Software Developer

You can watch a quick video walkthrough of this article from the author below.

Subscribe to our Newsletter

Get Our Insights in Your Inbox

Career advice, the latest coding trends and languages, and insights on how to land a remote job in tech, straight to your inbox.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.