Documentation

Many teams use Git flow (read more here and here) as their branching strategy and development workflow. It is commonly explained using a colorful chart that shows the master and develop branches as vertical lines with the feature branches to one side and relase and hotfix branches between them.

If you run 'git log --graph' on a repo or when you look at the graph in a UI tool like SourceTree, the chart looks nothing like the git flow graph. The straight vertical line is not necessarily the master or develop branch. It is very hard to see if everyone is correctly following the branching pattern or if something odd has happened.

Git Flow Chart draws your commits as the chart explaining git flow. This will give much better insight in the current state of the repository, showin the feature branches as straight lines branching from develop and merging back when finished. Color coding indicates whether a commit is on a feature branch, a release branch or on develop or master.

For better insight in what is part of a specific feature branch, you can click any commit to highlight all commits and branch lines that are part of its ancestry. This is especially useful when you have many parallel feature branches. Of course, you can also click through to the standard Stash commit details.

How to use

Git Flow Chart offers two models: you can use our web service if you have your repositories stored in GitHub or install our add-on if you are using Atlassian Stash to host your Git repositories. We are still working on support for Bitbucket.

Using GitHub

You can log in to our service using your GitHub credentials. You will be asked to authorize Git Flow Chart to access your account information. Once logged in you will see a list of your repositories and you will be able to draw the chart by clicking on a repository. Please make sure that you read our Privacy Policy prior to using our service.

Using Atlassian Stash

You can install the Git Flow Chart add-on using the Universal Plugin Manager from the Stash administration screen. After installation, a new navigation item called "Git Flow Chart" becomes available when browsing a repository.

How it works

The Git Flow Chart will create the initial tree graph using the most recent commits. While scrolling down the page, the graph will automatically collect more details as soon as it detects that it cannot draw the parent of one of the visible commits. A progress indicator is shown while loading new information and updating the graph. Please note that, depending on the complexity of the commit history, the UI might freeze while rebuilding the graph.

If you wish to zoom in on the inheritance tree of a specific commit, you can click on the commit message. This will highlight the commit and it's known parentage. You can undo the selection by clicking on the highlighted commit.

Because building the Git Flow Chart is complex, the information displayed might sometimes seem a bit odd. Please read the FAQ to see if there is anything you can do to improve the correctness of the graph.

Frequently Asked Questions

Can I use Git Flow Chart when we don't (strictly) follow git flow?

Yes, no problem. If you don't always use feature branches or if you branch your feature branches off from master and don't use a develop branch, Git Flow Chart will still give you better insight in the state of your repo than most charts. If you commit everything on master and your flow is basically linear, there is not much value to the chart.

Does Git Flow Chart support non-standard naming conventions?

Currently only the Atlassian Stash add-on supports non-standard naming conventions. By default, the chart uses 'develop' for the develop branch and 'feature/', 'release/' and 'hotfix/' prefixes. If you are using the Atlassian Stash add-on, you can change these defaults in the repository settings screen.

Why is the chart not 100% correct?

Git does not keep track of the history of branches. Branches are a moving label pointing to the HEAD (current) revision of the branch, but git keeps no historic information of which commits have been the HEAD of a branch in the past. So if you want to draw the develop branch as a line, you are essentially guessing. The last commit is certain, but whenever a commit has multiple parents, we have to make an educated guess on which parent was on develop and which commit was a merged in feature or release branch. If you keep strictly to git flow, there must be one 'true' develop line, but it can be hard to decide which it is. Git Flow Chart uses many hints in these decisions, including the commit messages on merges. It helps to keep the unchanged commit messages as git would suggest them.

My master branch is not correct

In git flow, the master branch is normally easier to isolate than the develop branch, because all of the release tags must be on it. The algorythm assigns large weight to tags that look like a release tag. By default, it uses the form x.x[.x[.x]] where x can be one or more digits.

If you are using the Atlassian Stash add-on, you can enter an appropriate regular expression in the repository settings screen if your release tags are composed differently.

I see multiple develop branches. How come?

This may seem strange, but is actually normal. If multiple developers work on the repo at the same time, they don't always have their local develop branches synchronized. When they commit on develop and later pull/push, they will have multiple develop lines, joining again at the implicit merge that happened when they pulled. Git Flow Chart tries to recognize these situations and will draw multiple develop lines. When it fails to recognize this situation, part of the develop branch might appear like a feature branch.

The chart draws commits on develop that were on a feature branch when I made them

In general, see the previous FAQ ('Why is the chart not 100% correct?'). Specifically, when a feature branch is merged back to develop using fast-forward merging, the commit is actually on two branches: on the feature branch AND on develop. Git Flow Chart picks develop over the feature branch in these cases. So a feature branch with only one commit that is immediately merged back using fast-forward will appear as a direct commit on develop.

The javascript code is on GitHub, is Git Flow Chart Open Source?

No, it is not. If you are using the code in a commercial instance of Atlassian Stash, you will need to purchase a license. Atlassian does have great offers for Open Source projects or Academic users. If you are using the Git Flow Chart web service, you can find pricing information here.

However, we do want to share the code and allow you to inspect, study and contribute improvements. For that reason, the core code of Git Flow Chart is hosted on GitHub. It is a javascript library and comes with unit tests and a standalong HTML page that allows you to test improvements locally. Feel free to fork!