Este é um guia de estilo Git inspirado pelo How to Get Your Change Into the Linux Kernel, pela página do git e várias práticas populares dentro da comunidade.
Traduções do guia estão disponíveis nos seguintes idiomas :
Se você se sentir confortável para contribuir, por favor, o faça! Dê um fork no projeto e abra um pull request.
-
Escolha nomes curtos e descritivos:
# bom $ git checkout -b oauth-migration # ruim - muito vago $ git checkout -b login_fix
-
Identificadores correspondentes de tickets de um serviço externo (Ex. Issues do GitHub ) também são bons candidatos para usar em nomes de branches. Por exemplo:
# GitHub Issue #15 $ git checkout -b issue-15
-
Use traços para separar palavras.
-
Quando várias pessoas estão trabalhando na mesma funcionalidade, pode ser conveniente ter um branch de funcionalidade pessoal e um branch de funcionalidade para a equipe. Use a seguinte convenção de nomenclatura:
$ git checkout -b feature-a/master # Branch da equipe $ git checkout -b feature-a/maria # Branch pessoal da Maria $ git checkout -b feature-a/nick # Branch pessoal do Nick
Realizar o merge nos branchs pessoais para o branch da equipe (ver "Merging"). Eventualmente, o branch da equipe será integrado ao "master".
-
Apague seu branch do upstream do repositório depois de integrado (a menos que haja uma razão específica para não fazê-lo).
Dica: Use o seguinte comando quando estiver no "master" para listar os branches que foram feitos merge:
$ git branch --merged | grep -v "\*"
-
Cada commit deve ser uma mudança lógica simples. Não faça várias mudanças lógicas em um commit. Por exemplo, se uma alteração corrige um bug e otimiza a performance de uma funcionalidade, o divida em dois commits separados.
-
Não divida uma mudança lógica simples em vários commits. Por exemplo, a implementação de uma funcionalidade e os testes correspondentes à ela devem estar no mesmo commit.
-
Commit cedo e frequentemente. Commits pequenos e autônomos são mais fáceis de entender e reverter quando algo dá errado.
-
Commits devem ser ordenados logicamente. Por exemplo, se commit X depende de uma mudança feita no commit Y, então commit Y deve vir antes do commit X.
-
Use o editor, não o terminal, quando estiver escrevendo a mensagem do commit:
# bom $ git commit # ruim $ git commit -m "Correção rápida"
Committar do terminal encoraja uma ideia de ter que encaixar tudo em uma única linha, o que geralmente resulta em commits não informativos, mensagens ambíguas.
-
O sumário (ie. a primeira linha da mensagem) deve ser descritivo ainda que sucinto. O ideal é que não seja maior que 50 caracteres. Deve ser escrito com letra maiúscula e no modo imperativo. Não deve terminar com um ponto, uma vez que é efetivamente o título do title:
# bom - modo imperativo, letra maiúscula, menos que 50 caracteres Marcar grandes registros como obsoleto quando insinuar falhas # ruim corrigido ActiveModel::Errors mensagens de depreciado falham quando o AR era usado fora do Rails.
-
Depois disso deve aparecer uma linha em branco seguido de mais descrição. Deve possuir 72 caracteres e explicar por que a mudança é necessária, como está relacionado com a issue e o quais efeitos colaterais podem ter.
Também deve fornecer qualquer referência aos recursos relacionados (eg. link para a issue correspondente em um bug tracker):
Curto (50 chars ou menos) sumário de mudanças Texto explanatório mais detalhado, se necessário. Deve possuir 72 caracteres. Em alguns contextos, a primeira linha é tratado como o assunto de um email e o resto do texto como o corpo. A linha vazia separando o sumário do corpo é crucial (a menos que você omita inteiramente o corpo); ferramentas como rebase podem se confudir se você roda os dois juntos. Parágrafos adicionais vem depois das linhas vazias. - Marcador circulares são permitidos também - Use um hífen ou asterisco para o marcador, seguido por um espaço simples, com linhas vazias entre eles Fonte http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Por fim, quando estiver escrevendo uma mensagem do commit, pense sobre o que você precisaria saber olhando para o commit daqui um ano.
-
Se um commit A depende do commit B, a dependência deve ser evidenciada na mensagem do commit A. Use o hash do commit quando se referir a commits.
Similarmente, se o commit A corrige um bug introduzido pelo commit B, deve ser evidenciada na mensagem do commit A.
-
Se um commit sofrerá squash de outro commit use o
--squash
e--fixup
sintaxes respectivamente, a fim tornar sua intenção clara:$ git commit --squash f387cab2
(Dica: Use a
--autosquash
marcação quando estiver realizando rebase. Os commits terão o squash realizado automaticamente.)
-
Não reescreva histórico publicado. O histórico do repositório é valioso a sua maneira e muito importante para permitir dizer o que realmente aconteceu. Alterar histórico publicado é uma fonte comum de problemas para qualquer um que trabalhe no projeto.
-
Contudo, há casos em que reescrever o histórico é legítimo. Estes são quando:
-
Você é o único trabalhando no branch e não está sendo inspecionado.
-
Você quer arrumar seu branch (eg. commits squash ) e/ou realizar rebase dele para o "master" para realizar o merge depois.
Dito isso, nunca reescreva o histórico do branch "master" ou quaisquer branchs especiais (ie. usado em produção ou servidores de Integração Contínua).
-
-
Mantenha o histórico limpo e simples. Bem antes de realizar o merge em seu branch:
-
Tenha certeza que está em conformidade com o guia de estilo e realize qualquer ação necessária se não (squash/reordenar seus commits, refazer mensagens etc.)
-
Rebase em outro branch em que será feito:
[meu-branch] $ git fetch [meu-branch] $ git rebase origin/master # então merge
Isto resulta em um branch que pode ser diretamente aplicado no final do branch "master" e resulta em um histórico bem simples.
(Nota: Esta estratégia é mais adequada para projetos com branches com branches recentes. Caso contrário é melhor ocasionalmente realizar o merge do branch "master" em vez de fazer rebase nele.)
-
-
Se seu branch inclui mais de um commit, não faça merge como um branch avançado:
# bom - garante que o commit de merge seja criado $ git merge --no-ff meu-branch # ruim $ git merge meu-branch
-
Há vários fluxos de trabalho, e cada um tem suas forças e fraquezas. Se um fluxo de trabalho se encaixa para o seu caso, depende da equipe, do projeto e do seu processo de desenvolvimento.
Dito isso, é importante escolher um fluxo de trabalho e permanecer com ele.
-
Seja consistente. Isto é relacionado ao fluxo de trabalho, mas também se expande a coisas como, mensagens dos commits, nomes de branchs, tags. Ter um estilo consistente dentro do repositório torna as coisas mais fáceis para entender o que está acontecendo olhando no log, em uma mensagem do commit etc.
-
Teste antes de realizar o push. Não suba trabalho não terminado.
-
Use Tags Anotadas para marcação de releases ou outros pontos importantes no histórico
Prefira lightweight tags para uso pessoal, bem como para commit com marcações para referências futuras.
-
Mantenha seu repositório em boa forma, realizando ocasionalmente tarefas de manutenção de performance em seu repositório local e remoto:
Este trabalho está sobre licença da Creative Commons Attribution 4.0 International license.
Agis Anastasopoulos / @agisanast / http://agis.io
Guylherme Tabosa / @tabosag