Tutorial GitFlow: ramificação para features, releases e hotfixes

Configurando o GitFlow

Antes de aproveitar o modelo estruturado de ramificação do GitFlow, você precisa instalá-lo na sua máquina e inicializá-lo no seu repositório. Felizmente, ambos os passos são simples.

Para usar o GitFlow, você já deve ter o Git instalado na sua máquina. Você pode saber mais sobre a instalação do Git no tutorial de instalação do Git.

Instalando o GitFlow

GitFlow é uma extensão do Git, então você precisa instalá-lo separadamente. Por padrão, ele não vem junto com o Git. O processo de instalação depende do seu sistema operacional.

Para instruções mais detalhadas de instalação do GitFlow, leia a documentação oficial.

Observação: embora a extensão GitFlow acima facilite o gerenciamento de branches de feature, releases e hotfixes com comandos simples, ela não é estritamente necessária. Você pode seguir o fluxo do GitFlow usando comandos padrão do Git— desde que seja consistente com as convenções de nomes e práticas de merge. A ferramenta apenas automatiza e impõe o processo, o que pode ser útil para times ou projetos maiores.

macOS

Se você usa Homebrew, o gerenciador de pacotes mais popular do macOS, rode:

brew install git-flow-avh

Linux (baseado em Debian/Ubuntu)

Se você usa um sistema baseado em Debian, como Ubuntu, use:

sudo apt-get install git-flow

Windows

No Windows, você pode instalar o GitFlow via Git for Windows e adicionar o Git Bash ao seu terminal.

Para verificar se o GitFlow está instalado, rode:

git flow version

Inicializando o GitFlow em um repositório

Como primeiro passo, você precisa ter um repositório Git inicializado antes de usar o GitFlow. Saiba mais em como inicializar e configurar um repositório Git.

Depois de instalar o GitFlow, você pode inicializá-lo em qualquer repositório Git existente com:

git flow init

O GitFlow vai pedir para você configurar algumas opções. Veja o que elas significam e como escolher as certas:

1. Nomes de branch: você definirá os nomes padrão.
1. Nome da branch de produção (padrão: master)
2. Nome da branch de desenvolvimento (padrão: develop)
2. Prefixos para branches de suporte: o GitFlow usa convenções de nomes para seus diferentes tipos de branch.
1. Branches de feature: feature/
2. Branches de bugfix: bugfix/
3. Branches de release: release/
4. Branches de hotfix: hotfix/
5. Branches de suporte: support/ (raramente usadas na prática)
6. Prefixo de tag de versão: v (por exemplo, v.1.2.0)

Os padrões funcionam bem para a maioria dos times, mas você pode personalizá-los para combinar com os padrões de nomenclatura da sua organização.

Exemplo de saída da inicialização:

git flow init

Which branch should be used for bringing forth production releases?
   - master
Branch name for production releases: [master]
Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Bugfix branches? [bugfix/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? [] v

Depois de inicializar, você pode fazer push da branch develop para o repositório remoto. Saiba mais sobre push e pull de branches no tutorial de Git Push e Pull.

Usando o GitFlow no desenvolvimento

Com o GitFlow inicializado no seu repositório, você pode começar a usar seu modelo de ramificação para gerenciar seu fluxo de desenvolvimento. O GitFlow oferece comandos de alto nível para trabalhar com features, releases e hotfixes, facilitando manter a estrutura e evitar o caos no Git.

Nos próximos subcapítulos, vamos ver o GitFlow na prática.

Criando branches de feature

As branches de feature são usadas para desenvolver novas funcionalidades sem afetar a base de código principal.

Você pode criar uma branch de feature executando:

git flow feature start <feature-name>

Esse comando cria uma nova branch a partir de develop chamada feature/<feature-name>. Você pode começar a desenvolver sua feature e fazer commits normalmente.

Finalizando branches de feature

Quando sua feature estiver concluída e testada, finalize com: 

git flow feature finish <feature-name>

Isso faz o seguinte:

• Faz merge da sua branch de feature na branch develop.
• Exclui a branch local feature/<feature-name>.

Se aparecerem conflitos de merge, resolva manualmente e conclua o merge usando o fluxo padrão de resolução de conflitos do Git.

Se você trabalha em times maiores, onde é preciso criar e revisar pull requests antes, não dá para usar diretamente o comando de finish do GitFlow; em vez disso, faça o seguinte:

1. Faça commit do seu trabalho e depois dê push da branch:

git push origin feature/<feature-name>

2. Crie um pull request de feature/<feature-name> para develop no GitHub, GitLab etc.
3. Peça revisão, rode os testes e obtenha as aprovações.
4. Após aprovado, faça o merge pela interface da plataforma e exclua a branch.

Se você quiser aprender mais sobre GitHub e como usá-lo, recomendo os cursos GitHub Foundations e GitHub Concepts. Em outros times, você pode seguir o fluxo padrão git flow feature finish, mas peça uma revisão da sua branch antes de fazer merge de volta em develop e rode testes nas alterações para garantir o bom funcionamento.

Criando branches de release

Branches de release são criadas para preparar uma nova versão de produção sem bloquear o desenvolvimento em andamento na branch develop.

Para iniciar um release, rode:

git flow release start <version-number>

Isso cria uma nova branch chamada release/<version-number>. Essa branch é criada a partir de develop.

Nessa branch, você normalmente finaliza números de versão, corrige bugs menores e atualiza documentação e changelogs.

Finalizando branches de release

Quando seu release estiver pronto para produção, finalize com:

git flow release finish <version-number>

Esse comando:

• Mescla a branch de release em master e develop.
• Cria uma tag do release em master (por exemplo, v1.0.0).
• Exclui a branch local release/<release-number>.

Não esqueça de enviar suas alterações e tags:

git push origin master
git push origin develop
git push --tags

# ou, de forma resumida
git push origin master develop --tags

Criando branches de hotfix

Hotfixes são usados para correções urgentes em produção quando um bug é encontrado na branch master.

Para iniciar um hotfix:

git flow hotfix start <version-number>

Isso cria uma branch hotfix/<version-number> a partir de master. Agora você pode aplicar as mudanças e fazer commit da correção.

Quando terminar, finalize com:

git flow hotfix finish <version-number>

Isso:

• Mescla o hotfix em master e develop.
• Cria a tag da correção em master.
• Exclui a branch local `hotfix/<version-number>`.

Envie suas alterações locais e tags como de costume:

git push origin master develop --tags

Hotfixes são especialmente poderosos porque permitem corrigir rapidamente problemas em produção sem interferir no desenvolvimento em andamento na branch develop.

Imagine que já existam novas features mescladas em develop que você não quer liberar ainda, mas surgiu um bug urgente e grave na aplicação em produção que precisa ser corrigido. 

É aí que os hotfixes brilham, pois são criados a partir de master e depois mesclados de volta em develop.

Exemplo de ramificação com GitFlow

Vamos passar por dois fluxos comuns — um ciclo de desenvolvimento de feature e um release com hotfix — para ver o GitFlow em ação e compará-lo com os comandos tradicionais do Git.

Ao ver os dois lados, você vai entender melhor como a extensão GitFlow simplifica o processo ao encapsular várias etapas do Git em comandos simples e padronizados.

Se precisar de um resumo rápido dos comandos tradicionais do Git, recomendo o Git Cheat Sheet completo. Se quiser um panorama rápido do Git, recomendo ler o tutorial de GitHub e Git para iniciantes.

Fluxo de desenvolvimento de feature

Vamos supor que você esteja implementando uma nova feature que permite aos usuários se autenticarem na sua aplicação. Você chama essa feature de user-authentication.

Usando GitFlow:

git flow feature start user-authentication

# Trabalhe na feature
git add .
git commit -m "feat: Implement basic user authentication"

# Quando terminar:
git flow feature finish user-authentication

git push origin develop

Agora, usando Git "puro":

# Crie e troque para uma nova branch manualmente
git checkout -b feature/user-authentication develop

# Trabalhe na feature
git add .
git commit -m "Implement basic user authentication"

# Quando terminar
git checkout develop
git merge feature/user-authentication
git branch -d feature/user-authentication
git push origin develop

Como você pode ver, o GitFlow reduz o número de comandos e, portanto, o nível de complexidade. Também diminui as chances de erro, como fazer merge na branch errada.

Para aprender mais sobre como o merge no Git funciona, leia o Git Merge Tutorial: um guia completo com exemplos.

Agora vamos supor que você esteja preparando o release 1.0.0. Mas pouco tempo depois de liberar a nova versão, foi encontrado um bug crítico que precisa ser corrigido com um hotfix. 

Usando GitFlow:

# Inicie um release
git flow release start 1.0.0

# Ajustes finais, atualização de números de versão
git commit -am "Prepare release v1.0.0"

# Finalize o release
git flow release finish 1.0.0
git push origin master develop --tags

Agora você encontrou o bug e precisa criar um hotfix:

# Inicie um hotfix
git flow hotfix start 1.0.1

# Aplique a correção
git commit -am "Fix login issue in production"

# Finalize o hotfix
git flow hotfix finish 1.0.1
git push origin master develop --tags

E fazendo tudo isso novamente com comandos Git tradicionais:

# Release manual
git checkout -b release/1.0.0 develop

# Faça mudanças
git commit -am "Prepare release v1.0.0"

# Merge manual
git checkout master
git merge release/1.0.0
git tag -a v1.0.0 -m "Release v1.0.0"
git checkout develop
git merge release/1.0.0

# Exclua a branch de release
git branch -d release/1.0.0
git push origin master develop --tags

# Hotfix manual
git checkout -b hotfix/1.0.1 master

# Aplique a correção
git commit -am "Fix login issue in production"
git checkout master
git merge hotfix/1.0.1
git tag -a v1.0.1 -m "Hotfix v1.0.1"
git checkout develop
git merge hotfix/1.0.1

# Exclua a branch de hotfix
git branch -d hotfix/1.0.1
git push origin master develop --tags

Boas práticas para usar GitFlow

O GitFlow é bem poderoso e ajuda a gerenciar o código do seu time. Porém, para tirar o máximo dessa estrutura, é importante seguir algumas boas práticas.

Elas ajudam a manter branches limpas, reduzir conflitos de merge e melhorar a produtividade do time, principalmente em ambientes colaborativos.

Nomes de branch consistentes

Consistência é essencial na colaboração. Siga as convenções de nomes padrão do GitFlow, a menos que seu time tenha um bom motivo para personalizá-las.

Padrões recomendados:

• Branches de feature: feature/<feature-name>
• Branches de release: release/<version-number>
• Branches de hotfix: hotfix/<version-number>

Use também kebab-case para nomes compostos (por exemplo, feature/user-authentication).

Mudanças pequenas e frequentes

Branches de longa duração costumam gerar merges dolorosos e pull requests gigantes, difíceis de revisar. 

Falo por experiência própria: já passei algumas vezes pelo inferno dos conflitos de merge, e você vai querer evitar isso sempre que possível!

Em vez disso, mantenha as branches de feature curtas e com foco em uma única tarefa. Faça commits e pushes com regularidade para evitar perder trabalho ou se distanciar demais de develop.

Mudanças menores e incrementais são mais fáceis de testar, revisar e integrar.

Sincronize regularmente com a develop

Ao trabalhar em uma branch de feature, não deixe ela ficar para trás. Garanta que você puxe regularmente as últimas mudanças da branch develop para minimizar conflitos de merge depois:

git checkout feature/<your-feature>
git fetch origin
git rebase origin/develop

Manter-se em sincronia torna a integração mais suave e mantém suas mudanças compatíveis com o que outras pessoas estão construindo.

Revise e teste antes do merge

Embora o GitFlow permita merges diretos com comandos como git flow feature finish, o ideal é usar pull requests (PRs) ou merge requests (MRs) para todos os merges em develop e master.

Benefícios:

• Permite revisão de código e fluxos de aprovação
• Dispara checagens automatizadas de CI/CD
• Gera uma trilha de auditoria clara das mudanças

Isso é especialmente crítico em ambientes de produção, onde o controle de qualidade faz diferença.

Solução de problemas no GitFlow

Mesmo com um fluxo estruturado como o GitFlow, podem surgir problemas, especialmente trabalhando em equipe ou com branches de longa duração. 

Esta seção cobre os desafios mais comuns e como resolvê-los com eficiência.

Conflitos de merge

Conflitos de merge são comuns ao trabalhar em um mesmo código com um time maior e são bem chatos.Geralmente acontecem quando duas branches modificam as mesmas linhas de código.

Passos para resolver um conflito de merge:

1. Interrompa o processo de git flow finish.
2. Faça o merge manualmente da branch no seu destino:

git checkout develop
git merge feature/<your-feature>

3. O Git vai pedir para resolver os conflitos. Abra os arquivos em conflito e procure marcadores como estes:

<<<<<<< HEAD
Code from develop
=======
Code from feature branch
>>>>>>> feature/my-feature

4. Edite e limpe o código manualmente.
5. Depois de resolver, marque os arquivos como resolvidos:

git add <resolved-file>

6. Em seguida, conclua o merge com:

git commit -m “resolve merge conflict …”

Limpando branches obsoletas

Às vezes, seu repositório fica com branches de feature, release ou hotfix desatualizadas. Para evitar confusão, mantenha seu repositório o mais limpo possível.

Você pode resolver seguindo os passos abaixo:

1. Liste todas as branches locais:

git branch

2. Exclua uma branch local:

git branch -d <branch-name>

3. Se a branch ainda não foi mesclada e você tem certeza de que pode excluí-la:

git branch -D <branch-name>

4. Exclua uma branch remota:

git push origin --delete <branch-name>

É essencial revisar suas branches com regularidade e limpar as obsoletas para manter o repositório organizado.

Conclusão

O GitFlow é um framework robusto para colaboração, clareza e controle no seu fluxo de desenvolvimento. Seja em um projeto solo com mais gente envolvida ou contribuindo em um time grande, o GitFlow ajuda você a se organizar ao separar com clareza o desenvolvimento de features, releases e hotfixes.

Quando comecei a usar o GitFlow, foi um divisor de águas. Chega de caos nos merges. Chega de adivinhar qual branch usar. Cada parte do trabalho tinha seu lugar, e cada release seguia um processo repetível e confiável. Com o tempo, apresentei o GitFlow a todos os times com quem trabalhei. E, sempre, ele trouxe mais estrutura, colaboração mais fluida e menos erros.

Neste tutorial, você aprendeu:

• O que é GitFlow e por que ele é útil
• Como instalar e inicializar o GitFlow
• Como trabalhar com features, releases e hotfixes
• Boas práticas para evitar problemas comuns
• Como adaptar o GitFlow a fluxos modernos usando pull requests

Se você está pronto para levar seu fluxo de trabalho com Git para o próximo nível, experimente usar o GitFlow no seu próximo projeto. E se você já domina o básico, comece a pensar em integrá-lo ao pipeline de CI/CD do seu time, ao processo de revisão ou até ao GitHub Actions.