☕ Git-Flow: an introduction
Tags: git, beginners, gitflow, versioning
Published: 2020-06-08 16:53:52

🇪🇸 [Version en español](https://dev.to/fernando_ayon/git-flow-lo-esencial-3bgf)
🇫🇷 [Version française](https://dev.to/fernando_ayon/git-flow-premiers-pas-e93)

Got a new job or in your current one they are planning to implement Git-Flow and you don't know what the fuss is all about?

You've come to the right place. In this post I'll break it down for you, however, if you already know it and just want to tinker around with it, you can just skip to [the tutorial](#tutorial).


# 🧐 The Context

In a few words, [Git](https://git-scm.com/) is a version control system, an essential tool to handle the life cycle of the development of an application.

So far so good, classic Git, but problems start showing up when handling teamwork: you and your team might decide to just work on the main branch of the project and create some secondary branches on special occasions, but what happens when there is a lot of work or several people must work in the same function at the same time?


## 📓 [Git-Flow](https://nvie.com/posts/a-successful-git-branching-model/)

When working as a team, it is necessary to define conventions or good practices so that everyone knows how to work together. Git-Flow is one of many so-called *workflows*, quite popular for its practicality and relatively quick learning, it is a way to organize the branches of the project repository.

You have probably already seen this image or a similar one when searching the term Git-Flow on the Internet:
![*Visible confusion*](https://dev-to-uploads.s3.amazonaws.com/i/8uwtwsr8ktejnuh4rad6.jpg) *A picture is worth a thousand words, or in this case a couple thousand more*

It seems and is complicated at first glance, but when you know the different branches used and the reason for their existence, you will see that the handling is quite logical.


### 🌳 Branches

As we saw in the image, Git-Flow uses several branches to organize the development:

- master
- develop
- feature
- release
- hotfix


#### 🌴 master & develop

If you have used Git before, you will be familiar with the `master` branch. In this new context, this branch is "untouchable", no one from the team should make any changes directly to it, nor create new branches from it, with one exception that we will review later.

When creating a new project, or when starting to use Git-Flow, the `develop` branch must be created from` master`, and like `master`, it will be a "long-lived branch", that is, it will never be deleted and will be parallel to `master`.

As its name implies, the `develop` branch serves as the basis for working on all new project features and fixes, which is why it is considered the main branch.

Once all the new project functions & bugfixes have been completed and `develop` is on a rather 'stable' state, we should `merge` develop in `master`.

The `master` branch should always reflect an 'production' state, so it is important that we do not make changes directly to it, since every time there is a new `commit`, we should `tag` it to define the new version and publish it. In this context the `master` branch is sometimes referred to as the 'integration' branch.


#### 💯 feature

The `feature` branches are those that we dedicate completely to the development of each of the new *planned* functions to be added to the project in the next version. They come always from `develop` and we must `merge` 'em back to `develop`.

Following Git-Flow best practices, when creating a new `feature` branch, we must always add the prefix `feature/`, in this way we can maintain a good organization and just by looking at the active branches we can quickly identify the work in progress.

At the same time, it is important to name the `feature` branches in a descriptive way to identify the purpose of the branch:
```
❌ feature/new-method
✔️ feature/add-support-for-json-parsing
```

The important thing about feature branches is that they only live during development and that they should disappear once we have done the `merge` in `develop` or that they are discarded if the function is no longer necessary.

NOTE: the prefix `feature/*` is the default, but if you or your team deem it necessary, you can adapt the prefix to anything else, for example `function/*`


#### ⭐ release

The `release` branch is used to regroup the functionalities and corrections made, to prepare for the release of the version in development. This branch starts from `develop` and must be `merged` in both `develop` and `master`.

The perfect time to create a `release` branch is when the `develop` branch *looks* as much as possible to what we want to have in production, it provides then a moment to make last minute corrections that we may have forgotten, or to make changes of the project that do not necessarily need a whole branch to be carried out, for example to increase the version number.

Following Git-Flow, `release` branches also have a prefix, `release/*` or `release-*`, usually followed by the version number or name they represent, for example: `release/1.2.0` or `release/5.0` or `release/1.0.0-rc.1+build.123`.

The advantage of having a release branch is that work can continue in `develop` and we can create other new `feature` branches, since the planned work is already in the release one and will ~~should~~ not have major changes.


#### 🛠️ hotfix

The `hotfix` branches come from `master` and must be `merged` back in `master` and `develop`. They are used to make quick or critical corrections to the project, in order to publish a new version as soon as possible.

NOTE: If you create a `hotfix` branch but there is already a `release` branch, instead of doing the `merge` in `develop`, it must be `merged` in `master` and `release` instead.


#### ⚔️ hotfix vs bugfix

In some projects we can see that in addition to the `hotfix` branches, sometimes we have some branches with the `bugfix` prefix. The difference between these two types of branches is that the `bugfix` ones behave like `features` and the `hotfix` ones behave like `releases`.

In other words, we can use the `bugfixes` to make minor bug fixes that can wait for the release of the development version, while the `hotfixes` cannot wait and should be published as soon as the development has been approved.
```
✔️ bugfix/fix-some-thingy-that-almost-nobody-uses-and-its-not-really-important
✔️ hotfix/fix-clic-on-top-right-corner-of-login-button-sets-the-users-computer-on-fire
```


### ✏️ Tutorial <a name="tutorial"></a>

For this tutorial and in order to simplify it, I will use the Git-Flow console plugin of [Peter van der Does] (https://github.com/petervanderdoes/gitflow-avh), but you can also see the equivalent [classic Git commands] (https://gist.github.com/JamesMGreene/cdd0ac49f90c987e45ac) to Git-Flow commands.

1. Initialize Git-Flow in the project

    ```
    # Initialize Git in the project, create the develop branch and
    # configure the prefixes of the other branches.
    # Then, switch to the develop branch
    git flow init
    ```
    ![git flow init](https://dev-to-uploads.s3.amazonaws.com/i/5ush55zzd9oaqorna9pf.gif)

2. Starting to work on a new feature

    ```
    # Creates a new feature/* branch and starts pointing to it
    git flow feature start <feature-name>
    ```
    ![git flow feature start](https://dev-to-uploads.s3.amazonaws.com/i/dw1ll43xgdzzncqpxxt2.gif)
    We can see how the console tells us the actions performed and that we can start working on the new branch.

3. Finish a feature

    ```
    # The name of the feature is optional, not really necessary if
    # you are already on the branch.
    # Changes to develop, performs a merge of the feature to develop
    # And deletes the feature branch
    git flow feature finish <feature-name>
    ```
    ![git flow feature finish](https://dev-to-uploads.s3.amazonaws.com/i/7twy4bwoq6r4m2dr7edc.gif)

    NOTE: All these actions are performed in your local repository, nothing is done in the distant one, unless you `push` the branches. Always remember to `push` when you finish your features, to update `develop`.

4. Prepare for the new version

    ```
    # Creates a new release/* branch from develop y change the pointer to it
    git flow release start <version-name>
    ```
    ![git flow release start](https://dev-to-uploads.s3.amazonaws.com/i/xa9tsuaqyghc0lzxzya4.gif)

    NOTE: Right after updating the version number of your project it is a good time to publish the release branch in `origin`.

5. Finishing the release

    ```
    # Checks out the master branch
    # Merges the release in master
    # Creates the version tag using the name of the release branch
    # Checks out the develop branch
    # Merges the release in develop
    # Deletes the release branch
    git flow release finish
    
    # Don't forget to push!
    git push origin master
    git push origin develop
    git push --tags
    git push origin :release/1.2.0 (if the release was in the distant repo)
    ```
    ![git flow release finish](https://dev-to-uploads.s3.amazonaws.com/i/9wnd7eyv1kd44hrtgkkl.gif)

6. Creating a hotfix

    ```
    # A hotfix branch may be created from a specific commit or from the last commit if not specified.
    # Creates a hotfix branch and checks it out
    git flow hotfix start <hotfix-name> [<commit>]
    ```
    ![git flow hotfix start](https://dev-to-uploads.s3.amazonaws.com/i/zk7rio07c4kouvbfkxej.gif)

7. Finish a hotfix

    ```
    # Same behavior as the release branches
    # You can also specify the option -T or --tagname
    # to create the tag correctly if the name of your
    # hotfix branch is not a version number.
    git flow hotfix finish [<-T version-name>]
    ```
    ![git flow hotfix finish](https://dev-to-uploads.s3.amazonaws.com/i/foisegiro6knb6bse4ag.gif)


## Next steps

For the next article, we will talk about other strategies, but if you want to learn more about Git-Flow at the moment, here are some sources that I used for this article.

[A successul Git branching model](https://nvie.com/posts/a-successful-git-branching-model/): The original article from the author of Git-Flow
[Git-Flow cheat sheet](https://danielkummer.github.io/git-flow-cheatsheet/): The essential Git-Flow cheat sheet
[GitFlow considered harmful](https://www.endoflineblog.com/gitflow-considered-harmful): A simpler alternative to Git-Flow and the subject of my next article.