Introduction

When we start to work with git, it's hard to understand how do you should work with branches correctly to avoid conflicts, have a nice and organized history and a project that it's easy to deploy and rollback if necessary.

In this article, I'll explain the bestgitflow that exists and why each of these parts are there.

The core concepts

To worik with gitflow we must understand 2 core concepts: branches and merging strategies.

There are 3 types of branches:

• The main "branches"
• The feature branches
• The task branches

And 3 types of merge strategies:

• Merge
• Squash
• Rebase

Branches

You can think of Git as a Tree, it has it's trunk and it's branches.

They are "copies" of the main system, so you can do all the changes that you want without altering the main content, so you can revert these changes, apply them other branches, and do a lot of cool stuff with it.

The main "branches"

I recommend to have only one main branch on your repository, and not adevelop andproduction branches. Why? Because branches areBRANCHES! Ramifications of something that can (but shouldn't) follow different paths of the original, and not something to save a persistent state and never change again.

I 100% against using branches forproduction or release versions (branches likev1.0.0 and similar), we have many other ways (correct ways!) to do it and we should avoid this workaround.

Git has support forrelease tags, which are pretty good to name your releases and know when something goes to production. They are kinda editable too, in case you need it, but it's always best to have immutable releases and release a fix if needed.

You also can useReleases in GitHub, that are very helpful to have a zip file with all your code, and also has lot's of integrations and automations.

So, to summarize:

• I recommend the use ofONE main branch, and for being a old timer, I call itmaster, but you can call itmain if you prefer.
• In this article, I'll be using GitHub Releases, but if you use other remote repository, you can understand it as git tags.

The feature branches

When we work in aTrue Agile environment, we have features planned that must be implemented, like a feature to allow the user to create an account, in Scrum, they call these things "User Stories".

At the beginning of every cycle (or "sprint" if you use Scrum), it's created a new branch from the main branch with the pattern:

// Patternfeature/<IDinlowercase>/<descriptioninlowercase>// Examplefeature/ant-1/create-account

This branch is created from the main branch and will group all the changes of this feature. After everything that the feature needs is merged and tested, the branch will be merged back to the main branch.

The task branches

Task branches are sort-lived branches that apply specific changes needed to create that feature, like small pieces of that feature.

They can be understood as "Jira Tickets" or "Issues".

They are created from the FEATURE branches and merged on them.

// Patterntask/<IDinlowercase>/<descriptioninlowercase>// Exampletask/ant-2/password-adapter

Other branches and their prefixes

As you could have noticed in the previous topics, feature and task branches have different prefixes, but follow the same patterns.

Every other branch that isn't the main branch will have some kind of prefix, and the existent prefixes are:

# Same level as feature brancheshotfixfeaturerefact# Same level as task branchestaskfixrefactchorecicd

You already knowfeature andtask, but let know the other ones.

hotfix: Created to fix something urgently, usually things broken from the previous release that needs to be fixed in order to publish a new release because rollback is not an option.

refact: Changing a feature that already exists in the system, without affecting its behavior. Therefact branch in the same level as afeature branch is used in order to refact a big portion of your system, a core feature, like user account creation, and not to refact a for loop.

fix: A bugfix that will follow the right flow of development, will be tested before merged, and will be merged with all the other things of the feature (what may take a while).

refact: Therefact branch in the same level as atask branch is used in order to refact small portions of your code, affecting its behavior or not. These branches must be part of a feature, and can change things like your internal API to send messages to topics, improve the performance of a for loop, etc.

chore: Update in a comment, a development script, README, things that doesn't affect the code.

cicd: Updates in the pipelines, configurations for deploying.

Merge strategies

Here I'll give a quick resume about the topic, but you can learn more in theofficial documentation.

The thing that we will focus on is:squashing before merging:

• Every task should have 1 commit when merging to a feature, so youMUST ALWAYS squash your commits before merging.
• Every feature should have 1 commit when merging to the main branch, so youMUST ALWAYS squash your commits before merging.

GitHub automatically squashes your commits for you if you configure it right:

But you can also do it with the CLI, seethe docs.

Extra tips

Commit message pattern

I useA simplified version of Clean Arch for my projects, from this i get thelayers, and the pattern that i use for the commit messages is:

// Pattern<prefix>(<scopeinlowercase>):<shortdescriptioninlowercase>// Examplestask(adapters):addfooadapterfix(usecases):fixusercreationchore(docs):adddetailstoreadmecicd(deploy):changedeploymethod

hotfix,feature,refact,task,fix use thelayers as thescope.

On the frontend web, you can use the names of the folders undersrc as thescope.

chore can usedocs,comments ornaming as thescope.

cicd can usedeploy,review ortests as thescope.

Commits that fix PR comments doesn't need a special pattern since they will be squashed, you can use justfix pr comments or some message that you can kinda understand.

Small teams

If you are working in a small team, there's no need to havefeature branches, you can work directly withtask branches, this will decrease the complexity of your system.

Advantages of this GitFlow

A nice and clean commit history

In your main branch you will be able to see all the features that your software have and the evolution of it.

In your PR history, you will be able to see all the feature branches (this history is even better if you use the right labels to filter your PRs!), and all the branches and changes related to them.

Standard

Everyone works in the same way because all of you have a standard to follow. It's easier to recognize patterns and understand the way that all teams work with git.

GitFlow usingthe best gitconfig

When usingthe best gitconfig, it's very, very easy to work with git:

# At the start of the cycle
git ckm
git cb feature/ant-1/create-account
# To start a task
git ck feature/ant-1/create-account
git pl
git cb task/ant-2/password-adapter
# When task finished
git acips task(adapters): add password adapter
# If you need to do any adjusts on your commit (even after the PR is created) you can run
git acaps task(adapters): add password adapter
# If there's comments on your PR and you need to fix them, create anoter commit
git acips fixprcomments
# Create the PR and it's done!
# To create another task, just start from "To start a task"

Conclusion

Thanks for reading, I think that this article has everything that you need to know to be able to work with Git. If you have any thoughts, please feel free to share them with us in the comments! 😄