In GitKraken V0.5 we added support for GitFlow. In the process of doing so, we created a library that wraps NodeGit, which allows us to perform GitFlow commands with a single function call. The library is now open source and can save other developers time doing GitFlow operations in Node.js.

What is GitFlow?

GitFlow is a branching and merging strategy that can be used in any Git repo. It is a list of rules to keep a repo’s history organized, and it’s also used to make the release process, bug fixes, and feature creation easier.

In a repo that uses GitFlow, two branches will always be present: master and develop:

• master: the version in production
• develop: the version currently in development for the next release

Other supporting branches are specific types (i.e. feature, hotfix, or release branches) where each has its own rules for branching and merging.

As you can imagine, these rules can be tedious to implement and rule breakers are imminent. Luckily, the creator of the GitFlow method was aware of these issues and created a Git extension to automate the process of starting and finishing GitFlow branches. Developers here at Axosoft simply implemented this same idea; the difference being that we extended NodeGit rather than Git core.

How To Use It

Nodegit-flow starts with initialization.

const nodegit = require('nodegit-flow');
const config = nodegit.Flow.getConfigDefault();
nodegit.Flow.init(repo, config);

nodegit.Flow.init will add the following keys to the repo’s Git config:

• gitflow.branch.master
• gitflow.branch.develop
• gitflow.prefix.feature
• gitflow.prefix.hotfix
• gitflow.prefix.release
• gitflow.prefix.versionTag

These keys define the prefixes that GitFlow branches will have when starting a feature, hotfix, or release. They will also determine the local branch names nodegit-flow will associate with master and develop.

You can either choose to stick with the default config values provided with .getConfigDefault() or modify these values to fit your preference.

Here’s what your repo should look like after initialization.

Now let’s start a feature.

nodegit.Flow.startFeature(repo, 'myFeature');

We just created and checked out a branch called feature/myFeature that points to the same commit as develop. Now after creating a commit with vanilla NodeGit our graph will look something like this:

Once the feature is finished, it’s a one-liner to finish:

nodegit.Flow.finishFeature(repo, 'myFeature');

This has merged feature/myFeature into develop, checked out develop, and deleted feature/myFeature.

Nodegit-flow doesn’t only contain methods for features but also hotfixes, releases, and all other Git-flowy things.

By extending NodeGit to include GitFlow functions in a separate library, we give GitKraken a nice separation from GitFlow concerns, as well as offer a small example to developers who are curious about extending NodeGit.

While GitKraken is not open source, we regularly contribute to and publish tools that we use internally such as nodegit-flow. Other examples include NodeGit, libgit2, and Electron.