Introduction to Gitflow

0.- Overview #

GitFlow is a branching model for Git, designed by Vincent Driessen, that defines a clear structure for managing feature development and releases in a more organized way. It’s particularly popular in large projects and teams because it helps manage complexity and promotes parallel development. Here’s an introduction to GitFlow:

0.1.- Benefits of GitFlow #

Clear Structure: GitFlow provides a well-organized way to manage feature development, releases, and hotfixes.
Parallel Development: Multiple features can be developed simultaneously without interfering with each other.
Isolated Releases: Release branches allow teams to prepare releases without disrupting ongoing development work.
Safe Hotfixes: Hotfixes can be applied quickly without disrupting other branches.

0.2.- Drawbacks of GitFlow #

Complexity: GitFlow introduces several branches and processes, which can be complex for smaller teams or projects.
Overhead: The model adds overhead in managing multiple branches, especially if the team or project size doesn’t justify it.

1.- Basic Gitflow #

GitFlow is a workflow that builds on the basic principles of Git, introducing well-defined branch structures and practices for working with them. It organizes work into different branches, each serving a specific purpose in the development cycle.

1.1.- Key Concepts and Branches in GitFlow #

GitFlow defines several types of branches, each with a distinct role:

main Branch:

This branch holds the production-ready code.
The main branch should always reflect the state of the latest release.
Direct commits to main are avoided; instead, changes are merged from other branches.

develop Branch:

This is the integration branch for features and the source for releases.
All new features and updates are merged into develop.
Once a feature is complete, it’s merged into develop, where it’s tested and prepared for a future release.

Feature Branches:

Created from: develop
Merged into: develop
Naming convention: feature/feature-name
Feature branches are used to develop new features or enhancements.
These branches are short-lived and are deleted after they are merged into develop.

1.2.- Gitflow iteration example #

Using a calculator app as an example, we will go through all the stages of gitflow, asuming two people are contributing to the same project at the same time.

Repository creation: We create the project and upload it to our git hosting of choice. As the repository gets initialised, a first branch “main” and an initial comit gets created.
Development Start: We create from the “main” branch the “develop” branch. In here we won’t make any code/content changes. The “develop” branch works as a spinal column for the project.
Calculator Output: We create our first feature branch “feature/IO“. In here we will do only the development related to the feature. In this case, the first comit is of the output of the calculator
Calculator Input: To finish the feature IO, we do another comit containing the input code for our calculcator
Feature/IO finished: Once a feature gets finished, we merge it to the “develop” branch. Notice that we haven’t touched the “develop” branch with any comits. We do content changes & comits on feature branches, and when finished we incorporate them into the “develop” branch
Integer multiplication: Now the development team splits development and parallelize work. “Person A” creates a new branch “feature/Mult” and makes a comit with the code for multiplication with integers.
Integer division: “Person B” creates a new branch “feature/Div” and makes a comit with the code for division with integers.
Decimal division: “Person B” continues on branch “feature/Div” and makes a comit with the code for division with decimals.
Feature/Div finished: “Person B” finishes the work on branch “feature/Div” and merges it to “develop“.
Merge from develop: “Person A” notices new work on the “develop” branch and merges it to the “feature/Mult” branch to have the lastest changes.
Decimal multiplication: “Person A” continues on branch “feature/Mult” and makes a comit with the code for multiplication with decimals.
Feature/Mult finished: “Person A” finishes the work on branch “feature/Mult” and merges it to “develop“.
v 1.0: The team has finished the first development cycle, builds the app, and creates a release version on the “main” branch. Notice how in the “main” branch we did no development work or any merges. In this branch only must go completely finished & tested work coming from “develop“.

2.- Advanced Gitflow #

When using gitflow on bigger teams or on public repositories, it’s recomended to use more types of branches and a few common tools.

2.1.- Advanced branches in Gitflow #

Release Branches:

Created from: develop
Merged into: main and develop
Naming convention: release/release-name (e.g., release/v1.0)
When develop reaches a stable state and a new version is ready, a release branch is created.
This branch is used for final bug fixes and preparing for the release (e.g., updating version numbers, documentation).
Once everything is finalized, the release branch is merged into both main and develop.

Hotfix Branches:

Created from: main
Merged into: main and develop
Naming convention: hotfix/hotfix-name
Hotfix branches are used to quickly address critical issues in the production code.
After the fix is implemented, the branch is merged into both main and develop to ensure the fix is included in future releases.

2.2.- Merge/Pull request #

Allows merging into protected branches
Prevents from merging conflicts
Needs to be approved by a team member
Merges are done only by an administrator

2.3.- Releases & Tags #

Releases are complete versions of a repository, compiled and ready for production use. They usually contain:

The compiled project
Any necessary libraries
A copy of the source code
Changelog since the last release

Tags are a “generic” version of a release. Usually a tag is the production version number (1.0, 1.1, 1.2)