---
# System prepended metadata

title: GitFlow Guide

---

# GitFlow Guide
GitFlow is a way of structuring pull requests and branches, that intends to simplify the branching workflow in a larger project.

## The main branches
- **`master`** 
    - Where tags are pushed (release tags)
    - represents the stable environment
    - sometimes named `main`
- **`develop`** 
    - Where new additions and non-urgent fixes are added
    - sometimes named `dev`

## Supporting branches
> Unlike the main branches, these branches always have a limited life time, since they will be removed eventually.

### Branches based from develop
- **`feature/[name]`** 
    - Branches with this prefix contains features
    - merged to develop
    - Ex: `feature/control-localization`
- **`bugfix/[name]`** 
    - Branches with this prefix contains unreleased bug fixes
    - merge to develop
    - Ex: `bugfix/required-validation-not-working`
- **`release/[name]`** 
    - Branches with this prefix are created to prepare an upcoming release
    - merge to develop and master
    - you should perform version bumbing if required
    - the name must be the new version number
    - the version should be minor or major update for features and patch for bugfixes
    - Ex: current version 1.0.0 > major update > `release/2.0.0`
    - Ex: current version 1.0.0 > minor update > `release/1.1.0`
    - Ex: current version 1.0.0 > patch update > `release/1.0.1`

### Branches based from master
- **`hotfix/[name]`**
    - Branches with this prefix are urgent to get to the stable environment to fix bugs
    - merge to develop and master
    - Considered as a patch version
    - name could be patch version
    - Ex: current version 1.2.3 > `hotfix/1.2.4`

# Semantic Versioning
Given a version number MAJOR.MINOR.PATCH, increment the:
1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format.

You can't skip versions
- 1.0.0 > 1.0.1 ✔ - patch update
- 1.0.0 > 1.1.0 ✔  - minor update
- 1.0.0 > 2.0.0 ✔  - major update
- 1.0.0 > 1.0.2 ❌  - skip patch
- 1.0.0 > 1.2.0 ❌  - skip minor
- 1.0.0 > 3.0.0 ❌  - skip major
- 1.0.0 > 1.1.1 ❌  - skip patch 1.1.0
- 1.0.0 > 2.0.1 ❌  - skip pathc 2.0.0
- 1.0.0 > 2.1.0 ❌  - skip minor 2.0.0

---

# GitFlow in action

## Init new git repo
```ps1=
git init -b main    # init git with default branch called main
git checkout -b dev # create dev branch
```

## Init in existing repo
1. Make sure to complete any old branches and clean the repo
2. Remove all branches except `main`
3. Create `dev` branch from main
4. Add latest version number as a tag on the main (Ex: 3.0.2)

## Create new feature
1. Create new branch `feature/[name]` from dev
2. Complete all changes (as much commits as you want)
3. Merge to dev (local merge or using a pull request)
4. Delete `feature/[name]` branch

## Create new bugfix
1. Create new branch `bugfix/[name]` from dev
2. Complete all changes (as much commits as you want)
3. Merge to dev (local merge or using a pull request)
4. Delete `bugfix/[name]` branch

## Create new release
1. After making some changes to dev `feature` or `bugfix`
2. Create new branch `release/[version]` from dev
3. Bump version number if needed and commit
4. Merge to main (local merge or using a pull request)
5. Merge to dev (local merge or using a pull request)
6. Add a tag with release version to main
7. Delete `release/[version]` branch

## Create new hotfix
1. Create new branch `hotfix/[version]` from main
2. Complete all changes (as much commits as you want)
3. Merge to main (local merge or using a pull request)
4. Merge to dev (local merge or using a pull request)
5. Add a tag with patch version to main
6. Delete `hotfix/[version]` branch

## References
- https://nvie.com/posts/a-successful-git-branching-model/
- https://github.com/petervanderdoes/gitflow-avh
