└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Guia de Estilo Git 2 | 3 | Este é um guia de estilo Git inspirado pelo [*How to Get Your Change Into the Linux 4 | Kernel*](https://www.kernel.org/doc/Documentation/process/submitting-patches.rst), 5 | pela [página do git](http://git-scm.com/doc) e várias práticas populares 6 | dentro da comunidade. 7 | 8 | Traduções do guia estão disponíveis nos seguintes idiomas : 9 | 10 | * [Coreano](https://github.com/ikaruce/git-style-guide) 11 | * [Chinês Simplificado](https://github.com/aseaday/git-style-guide) 12 | * [Francês](https://github.com/pierreroth64/git-style-guide) 13 | * [Japonês](https://github.com/objectx/git-style-guide) 14 | * [Inglês Simplificado](https://github.com/agis-/git-style-guide) 15 | * [Ucraniano](https://github.com/denysdovhan/git-style-guide) 16 | 17 | Se você se sentir confortável para contribuir, por favor, o faça! Dê um fork no projeto e abra um pull 18 | request. 19 | 20 | # Tabela de Conteúdo 21 | 22 | 1. [Branches](#branches) 23 | 2. [Commits](#commits) 24 | 1. [Mensagens](#messages) 25 | 3. [Merging](#merging) 26 | 4. [Misc.](#misc) 27 | 28 | ## Branches 29 | 30 | * Escolha nomes *curtos* e *descritivos*: 31 | 32 | ```shell 33 | # bom 34 | $ git checkout -b oauth-migration 35 | 36 | # ruim - muito vago 37 | $ git checkout -b login_fix 38 | ``` 39 | 40 | * Identificadores correspondentes de tickets de um serviço externo (Ex. Issues do GitHub 41 | ) também são bons candidatos para usar em nomes de branches. Por exemplo: 42 | 43 | ```shell 44 | # GitHub Issue #15 45 | $ git checkout -b issue-15 46 | ``` 47 | 48 | * Use *traços* para separar palavras. 49 | 50 | * Quando várias pessoas estão trabalhando na *mesma* funcionalidade, pode ser conveniente 51 | ter um branch de funcionalidade *pessoal* e um branch de funcionalidade para a *equipe*. 52 | Use a seguinte convenção de nomenclatura: 53 | 54 | ```shell 55 | $ git checkout -b feature-a/master # Branch da equipe 56 | $ git checkout -b feature-a/maria # Branch pessoal da Maria 57 | $ git checkout -b feature-a/nick # Branch pessoal do Nick 58 | ``` 59 | 60 | Realizar o merge nos branchs pessoais para o branch da equipe (ver ["Merging"](#merging)). 61 | Eventualmente, o branch da equipe será integrado ao "master". 62 | 63 | * Apague seu branch do upstream do repositório depois de integrado (a menos 64 | que haja uma razão específica para não fazê-lo). 65 | 66 | Dica: Use o seguinte comando quando estiver no "master" para listar os branches 67 | que foram feitos merge: 68 | 69 | ```shell 70 | $ git branch --merged | grep -v "\*" 71 | ``` 72 | 73 | ## Commits 74 | 75 | * Cada commit deve ser uma *mudança lógica* simples. Não faça várias 76 | *mudanças lógicas* em um commit. Por exemplo, se uma alteração corrige um bug e 77 | otimiza a performance de uma funcionalidade, o divida em dois commits separados. 78 | 79 | * Não divida uma *mudança lógica* simples em vários commits. Por exemplo, 80 | a implementação de uma funcionalidade e os testes correspondentes à ela devem estar no mesmo commit. 81 | 82 | * Commit *cedo* e *frequentemente*. Commits pequenos e autônomos são mais fáceis de entender e reverter 83 | quando algo dá errado. 84 | 85 | * Commits devem ser ordenados *logicamente*. Por exemplo, se *commit X* depende 86 | de uma mudança feita no *commit Y*, então *commit Y* deve vir antes do *commit X*. 87 | 88 | ### Mensagens 89 | 90 | * Use o editor, não o terminal, quando estiver escrevendo a mensagem do commit: 91 | 92 | ```shell 93 | # bom 94 | $ git commit 95 | 96 | # ruim 97 | $ git commit -m "Correção rápida" 98 | ``` 99 | 100 | Committar do terminal encoraja uma ideia de ter que encaixar tudo em uma 101 | única linha, o que geralmente resulta em commits não informativos, mensagens ambíguas. 102 | 103 | * O sumário (ie. a primeira linha da mensagem) deve ser 104 | *descritivo* ainda que *sucinto*. O ideal é que não seja maior que *50 caracteres*. 105 | Deve ser escrito com letra maiúscula e no modo imperativo. 106 | Não deve terminar com um ponto, uma vez que é efetivamente o título do *title*: 107 | 108 | ```shell 109 | # bom - modo imperativo, letra maiúscula, menos que 50 caracteres 110 | Marcar grandes registros como obsoleto quando insinuar falhas 111 | 112 | # ruim 113 | corrigido ActiveModel::Errors mensagens de depreciado falham quando o AR era usado fora do Rails. 114 | ``` 115 | 116 | * Depois disso deve aparecer uma linha em branco seguido de mais descrição. 117 | Deve possuir *72 caracteres* e explicar *por que* 118 | a mudança é necessária, *como* está relacionado com a issue e o quais *efeitos colaterais* 119 | podem ter. 120 | 121 | Também deve fornecer qualquer referência aos recursos relacionados (eg. link para a issue correspondente em um bug tracker): 122 | 123 | ```shell 124 | Curto (50 chars ou menos) sumário de mudanças 125 | 126 | Texto explanatório mais detalhado, se necessário. Deve possuir 127 | 72 caracteres. Em alguns contextos, a primeira linha 128 | é tratado como o assunto de um email e o resto 129 | do texto como o corpo. A linha vazia separando o sumário 130 | do corpo é crucial (a menos que você omita inteiramente 131 | o corpo); ferramentas como rebase podem se confudir se você roda os dois juntos. 132 | 133 | Parágrafos adicionais vem depois das linhas vazias. 134 | 135 | - Marcador circulares são permitidos também 136 | 137 | - Use um hífen ou asterisco para o marcador, seguido por um espaço simples, com linhas vazias entre eles 138 | 139 | Fonte http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 140 | ``` 141 | 142 | Por fim, quando estiver escrevendo uma mensagem do commit, pense sobre o que você precisaria saber olhando para o commit daqui um ano. 143 | 144 | * Se um *commit A* depende do *commit B*, a dependência deve ser evidenciada na mensagem 145 | do *commit A*. Use o hash do commit quando se referir a commits. 146 | 147 | Similarmente, se o *commit A* corrige um bug introduzido pelo *commit B*, deve ser evidenciada na mensagem 148 | do *commit A*. 149 | 150 | * Se um commit sofrerá squash de outro commit use o `--squash` e 151 | `--fixup` sintaxes respectivamente, a fim tornar sua intenção clara: 152 | 153 | ```shell 154 | $ git commit --squash f387cab2 155 | ``` 156 | 157 | *(Dica: Use a `--autosquash` marcação quando estiver realizando rebase. Os commits 158 | terão o squash realizado automaticamente.)* 159 | 160 | ## Merging 161 | 162 | * **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. 163 | 164 | * Contudo, há casos em que reescrever o histórico é legítimo. Estes são quando: 165 | 166 | * Você é o único trabalhando no branch e não está sendo inspecionado. 167 | 168 | * Você quer arrumar seu branch (eg. commits squash ) e/ou realizar rebase dele para o "master" para 169 | realizar o merge depois. 170 | 171 | Dito isso, *nunca reescreva o histórico do branch "master"* ou quaisquer 172 | branchs especiais (ie. usado em produção ou servidores de Integração Contínua). 173 | 174 | * Mantenha o histórico *limpo* e *simples*. *Bem antes de realizar o merge* em seu branch: 175 | 176 | 1. Tenha certeza que está em conformidade com o guia de estilo e realize qualquer ação necessária 177 | se não (squash/reordenar seus commits, refazer mensagens etc.) 178 | 179 | 2. Rebase em outro branch em que será feito: 180 | 181 | ```shell 182 | [meu-branch] $ git fetch 183 | [meu-branch] $ git rebase origin/master 184 | # então merge 185 | ``` 186 | 187 | Isto resulta em um branch que pode ser diretamente aplicado no final do 188 | branch "master" e resulta em um histórico bem simples. 189 | 190 | *(Nota: Esta estratégia é mais adequada para projetos com branches 191 | recentes. Caso contrário é melhor ocasionalmente realizar o merge do 192 | branch "master" em vez de fazer rebase nele.)* 193 | 194 | * Se seu branch inclui mais de um commit, não faça merge como um branch avançado: 195 | 196 | ```shell 197 | # bom - garante que o commit de merge seja criado 198 | $ git merge --no-ff meu-branch 199 | 200 | # ruim 201 | $ git merge meu-branch 202 | ``` 203 | 204 | ## Misc. 205 | 206 | * Há vários fluxos de trabalho, e cada um tem suas forças e fraquezas. 207 | Se um fluxo de trabalho se encaixa para o seu caso, depende da equipe, do projeto e do seu 208 | processo de desenvolvimento. 209 | 210 | Dito isso, é importante escolher um fluxo de trabalho e permanecer com ele. 211 | 212 | * *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. 213 | 214 | * *Teste antes de realizar o push.* Não suba trabalho não terminado. 215 | 216 | * Use [Tags Anotadas](http://git-scm.com/book/en/v2/Git-Basics-Tagging#Annotated-Tags) para 217 | marcação de releases ou outros pontos importantes no histórico 218 | 219 | Prefira [lightweight tags](http://git-scm.com/book/en/v2/Git-Basics-Tagging#Lightweight-Tags) para uso pessoal, bem como para commit com marcações para referências futuras. 220 | 221 | * Mantenha seu repositório em boa forma, realizando ocasionalmente tarefas de manutenção de performance em seu 222 | repositório local *e* remoto: 223 | 224 | * [`git-gc(1)`](http://git-scm.com/docs/git-gc) 225 | * [`git-prune(1)`](http://git-scm.com/docs/git-prune) 226 | * [`git-fsck(1)`](http://git-scm.com/docs/git-fsck) 227 | 228 | # Licença 229 | 230 | ![cc license](http://i.creativecommons.org/l/by/3.0/88x31.png) 231 | 232 | Este trabalho está sobre licença da Creative Commons Attribution 4.0 233 | International license. 234 | 235 | # Créditos 236 | 237 | Agis Anastasopoulos / [@agisanast](https://twitter.com/agisanast) / http://agis.io 238 | 239 | # Tradução 240 | Guylherme Tabosa / [@tabosag](https://twitter.com/tabosag) 241 | --------------------------------------------------------------------------------