Improving your Git workflow

#webdev #beginners #productivity #git

Whether you are on your own or with a team, having an efficient Git workflow can go a long way to boost your productivity.

For the past month, I've been consulting with a team that truly values the points I'll share with you today, and I've been able to see the positive effects they've had on a large-scale project.

Naming conventions

Git naming conventions are key. They allow you to understand the context of somebody's work in a matter of seconds and can help you filter through your team's work when well executed.

There isn't a perfect naming convention out there, but some of them, like Vincent Driessen's make a lot of sense and will clarify the mess that can be naming Git branches.

In short, other than your usual master and dev branches, your supporting branches can be of the following types:

Feature branches (feature-*): takes the form of a user story, or a feature that will be merged later on
Release branches (release-*): support the preparation of new product release, say a future rebranding of your website and will be eventually merged when ready
Hotfix branches (hotfix-*): your typical bug fix. You could, for example, branch off in order to fix a bug in production

But naming conventions also apply to commit messages. I truly recommend Chris Beam's "How to Write a Git Commit Message" in order to grasp the importance of carefully naming your commits. But I think the following guidelines are a good summary:

Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
Use the body to explain what and why vs. how

A good rule of thumb is to use the sentence: if applied, this commit will... and end it with your commit's title. If it makes no sense, you might want to reconsider it.

For example: if applied, this commit will remove all deprecated methods sounds great, whereas if applied, this commit will fix bug #123 doesn't.

Note: if you're using a tool such as Jira you could incorporate your ticket numbers in both your branch names and commit messages in order to make it easier to cross check.

Also, don't forget that these are just tips, and that at the end of the day you can always follow your own path. We'll all end up with some 'please work' commit messages here and there. 😄

Github labels

Github labels are another great way of filtering through your pull requests. So here are some labels I've found useful in the past and their meaning (when it isn't obvious):

Good first issue: especially great when your project is open-source and looking for new contributors. It's a great entry point for anyone too afraid to help out
Feature
Bug
Tech: means the associated pull request isn't about a client-facing feature. It could be about your project's eslint or storybook configurations for example
Critical: helps your team know which PRs are worth reviewing first, especially when on a tight deadline
Help wanted
In progress
XS, S, M, L and XL: represents the size of the PR at a quick glance. It's hard to determine how many lines changed will make up for any of these sizes, it's all up to you
Review needed
Reviewed

Labels can be changed by clicking on the following link in your pull requests page:

It's now as simple as clicking on "New label", setting a name, optional description and a color.

Protecting Git branches

You can limit branch manipulation by, for example, enforcing a required status before merging a given branch. This is great when you've set code review rules and don't want anyone to mistakenly merge a branch.

As admin of a project, go to Settings => Branches => Add rule and input the name of the branch you wish to protect.

You can chose from a number of rules, including:

Requiring X pull request reviews before merging
Requiring status checks to pass before merging, great when you have a robust CI process in place

Creating Git hooks

I'll quote the official docs for this one:

Git hooks are scripts that Git executes before or after events such as commit, push and receive. Git hooks are a built-in feature - no need to download anything.

Every Git repository has a .git/hooks folder with a script for each hook you can bind to. You're free to change or update these scripts as necessary, and Git will execute them when those events occur.

I'd recommend using awesome tools such as Husky in order to create them easily.

Automatically executing your tests and blocking a push if they fail will go a long way to avoid polluting your git history.

Honorable mentions

I'd like to mention something I use regularaly on personal projects such as Foodpicker, Banner Generator or Gitignore It (if you're curious, check out their Git history): 🎨 ⚡️ Gitmoji 🔥 🐛! It's a way of codifying your commit messages using emojis, this way you can understand the context of a commit at a glance. Some might dismiss it right away due to its colorful nature, but I've found it very useful to generate changelogs for example.

Some awesome tools such as gitmoji-cli and gitmoji-changelog make my Git experience smoother on a daily basis, so make sure to check them out if you're interested !

I hope you've learned a couple of things reading this article ! As always, I'd love for you to tweet at me @christo_kade if you have any questions 😄

Take care, and don't forget: always rebase locally ❤️

Top comments (11)

Benjamin Plouzennec • Aug 14 '19

In addition, with my old team we did wrote thoses practices into the definition of done of our project.
It gave us the possibility to reject a pull request because of bad commits.
It lead us to be more conscientious about our git workflow and history :)

Zakiah Ismail • Oct 17 '19

Great article! Thank you, Christopher! I'm starting to use the label thing in my team focusing on the status of each pull request such as (Abandoned, Blocked, Review Needed, Revision Needed). Do you automate the labeling part?

Christopher Kade • Oct 17 '19

Hey Zakiah, I'm glad you enjoyed the article ! We do not automate this part no, neither in their creation or the assignment.

Whenever we open a new PR we take the time to set the labels one by one as it's important not to mess it up.