5.3 Git Distribuído - Mantendo um Projeto

Se você recebeu o patch de alguém que o gerou com git diff ou alguma variação do comando diff do Unix (o que não é recomendado; veja a próxima seção), você pode aplicá-lo com o comando git apply. Supondo que você tenha salvo o patch em /tmp/patch-ruby-client.patch, você pode aplicar o patch assim:

Isso modifica os arquivos no seu diretório de trabalho. É quase idêntico a executar um comando patch -p1 para aplicar o patch, embora seja mais paranoico e aceite menos correspondências difusas (fuzzy matches) do que o patch. Ele também lida com adições, exclusões e renomeações de arquivos se estiverem descritos no formato git diff, o que o patch não faz. Finalmente, o git apply é um modelo de “aplique tudo ou aborte tudo” (apply all or abort all) onde tudo é aplicado ou nada é, enquanto o patch pode aplicar os arquivos de patch parcialmente, deixando o seu diretório de trabalho num estado estranho. O git apply é, no geral, muito mais conservador do que o patch. Ele não criará um commit para você — após executá-lo, você deve preparar (stage) e fazer o commit das alterações introduzidas manualmente.

Você também pode usar git apply para ver se um patch se aplica de forma limpa antes de tentar aplicá-lo de fato — você pode rodar git apply --check com o patch:

Se não houver saída, então o patch deve se aplicar de forma limpa. Esse comando também sai com um status diferente de zero se a verificação falhar, então você pode usá-lo em scripts se quiser.

Se o contribuidor for um usuário do Git e foi bom o suficiente para usar o comando format-patch para gerar o patch dele, então o seu trabalho é mais fácil porque o patch contém as informações do autor e uma mensagem de commit para você. Se você puder, encoraje os seus contribuidores a usar o format-patch em vez do diff para gerar patches para você. Você só deveria ter que usar o git apply para patches legados e coisas desse tipo.

Para aplicar um patch gerado pelo format-patch, você usa o git am (o comando é chamado de am porque é usado para "aplicar uma série de patches de uma caixa de correio"). Tecnicamente, o git am foi construído para ler um arquivo mbox, que é um formato simples de texto puro (plain-text) para armazenar uma ou mais mensagens de e-mail em um único arquivo de texto. Fica parecido com isso:

Este é o começo da saída do comando git format-patch que você viu na seção anterior; ele também representa um formato de e-mail mbox válido. Se alguém lhe enviou o patch de forma adequada por e-mail usando git send-email, e você fez o download dele no formato mbox, você pode apontar o git am para esse arquivo mbox, e ele começará a aplicar todos os patches que encontrar. Se você executa um cliente de e-mail que pode salvar vários e-mails no formato mbox, pode salvar uma série inteira de patches num arquivo e então usar o git am para aplicá-los um de cada vez.

No entanto, se alguém fez upload de um arquivo de patch gerado via git format-patch em um sistema de tickets ou algo semelhante, você pode salvar o arquivo localmente e depois passar esse arquivo salvo no seu disco para o git am aplicá-lo:

Você pode ver que ele foi aplicado de forma limpa e automaticamente criou o novo commit para você. As informações do autor são retiradas dos cabeçalhos From e Date do e-mail, e a mensagem do commit é retirada do Subject e do corpo (antes do patch) do e-mail. Por exemplo, se esse patch foi aplicado a partir do exemplo de mbox acima, o commit gerado se pareceria com isso:

A informação Commit indica a pessoa que aplicou o patch e a hora em que foi aplicado. A informação Author (Autor) é o indivíduo que originalmente criou o patch e quando ele foi originalmente criado.

Mas é possível que o patch não seja aplicado de forma limpa. Talvez o seu branch principal tenha divergido muito do branch a partir do qual o patch foi construído, ou o patch depende de outro patch que você ainda não aplicou. Nesse caso, o processo git am falhará e perguntará o que você deseja fazer:

Este comando coloca marcadores de conflito em quaisquer arquivos com os quais tenha problemas, muito parecido com uma operação de merge ou rebase em conflito. Você resolve esse problema da mesma maneira — edite o arquivo para resolver o conflito, prepare (stage) o novo arquivo, e então execute git am --resolved para continuar com o próximo patch:

Se você quiser que o Git tente resolver o conflito de forma um pouco mais inteligente, você pode passar uma opção -3 para ele, o que faz com que o Git tente um merge de três vias (three-way merge). Essa opção não está ativada por padrão porque ela não funciona se o commit no qual o patch diz que foi baseado não estiver no seu repositório. Se você tiver esse commit — se o patch for baseado em um commit público — então a opção -3 é geralmente muito mais inteligente para aplicar um patch conflitante:

Neste caso, sem a opção -3, o patch teria sido considerado como um conflito. Como a opção -3 foi usada, o patch foi aplicado de forma limpa.

Se você estiver aplicando vários patches a partir de um mbox, você também pode executar o comando am no modo interativo, que para em cada patch que encontra e pergunta se você deseja aplicá-lo:

Isso é bom se você tiver vários patches salvos, porque você pode visualizar o patch primeiro se não se lembrar do que se trata, ou não aplicar o patch se já o tiver feito.

Quando todos os patches para o seu tópico forem aplicados e tiverem sido confirmados (committed) no seu branch, você pode escolher se e como integrá-los em um branch de longa duração.

Um fluxo de trabalho básico é simplesmente mesclar todo esse trabalho diretamente no seu branch master. Neste cenário, você tem um branch master que contém código basicamente estável. Quando você tem trabalho num branch de tópico que você acha que concluiu, ou trabalho com o qual outra pessoa contribuiu e você verificou, você o mescla no seu branch master, exclui o branch de tópico recém-mesclado e repete.

Por exemplo, se temos um repositório com trabalho em dois branches chamados ruby_client e php_client que se parece com Histórico com vários branches de tópicos, e mesclamos ruby_client seguido de php_client, o seu histórico acabará ficando parecido com Após um merge de branch de tópico.

Esse é provavelmente o fluxo de trabalho mais simples, mas pode possivelmente ser problemático se você estiver lidando com projetos maiores ou mais estáveis, onde você quer ser muito cuidadoso com o que introduz.

Se você tem um projeto mais importante, talvez queira usar um ciclo de merge de duas fases. Neste cenário, você tem dois branches de longa duração, master e develop, em que você determina que o master é atualizado apenas quando uma versão (release) muito estável é criada, e todo o novo código é integrado ao branch develop. Você faz regularmente o push de ambos os branches para o repositório público. Toda vez que você tem um novo branch de tópico para mesclar (Antes de um merge de branch de tópico), você o mescla em develop (Após um merge de branch de tópico); em seguida, quando você cria uma tag de um lançamento, você faz um fast-forward do master para onde quer que o agora estável branch develop esteja (Após um lançamento (release) do projeto).

Desta forma, quando as pessoas clonarem o repositório do seu projeto, elas podem fazer o checkout do master para construir a versão estável mais recente e manter-se atualizadas com facilidade, ou podem fazer o checkout do develop, que é o conteúdo mais inovador (cutting-edge). Você também pode estender esse conceito tendo um branch integrate onde todo o trabalho é mesclado. Então, quando a base de código nesse branch estiver estável e passar nos testes, você o mescla em um branch develop; e quando ele provar estar estável por um tempo, você faz um fast-forward no seu branch master.

O projeto Git tem quatro branches de longa duração: master, next, e seen (antigamente 'pu' — proposed updates, ou atualizações propostas) para trabalhos novos, e maint para backports de manutenção. Quando um novo trabalho é introduzido por contribuidores, ele é coletado em branches de tópicos no repositório do mantenedor de uma maneira semelhante à que descrevemos (veja Gerenciando uma série complexa de branches de tópicos contribuídos paralelamente). Neste ponto, os tópicos são avaliados para determinar se eles são seguros e estão prontos para consumo ou se precisam de mais trabalho. Se forem seguros, eles são mesclados em next, e esse branch recebe um push para que todos possam testar os tópicos integrados juntos.

Se os tópicos ainda precisarem de trabalho, eles são mesclados em seen. Quando for determinado que eles estão totalmente estáveis, os tópicos são mesclados novamente em master. Os branches next e seen são então reconstruídos a partir de master. Isso significa que o master quase sempre se move para frente, o next sofre rebase ocasionalmente e o seen sofre rebase ainda com mais frequência:

Quando um branch de tópico finalmente é mesclado no master, ele é removido do repositório. O projeto Git também tem um branch maint originado a partir do fork do último lançamento, a fim de fornecer patches de backport caso um lançamento de manutenção seja necessário. Assim, quando você clona o repositório Git, você tem quatro branches nos quais pode fazer checkout para avaliar o projeto em diferentes estágios de desenvolvimento, dependendo do quão inovador você deseja ser ou de como deseja contribuir; e o mantenedor tem um fluxo de trabalho estruturado para ajudá-lo a examinar (vet) novas contribuições. O fluxo de trabalho do projeto Git é especializado. Para entender claramente isso, você poderia conferir o Guia do Mantenedor do Git.

Outros mantenedores preferem fazer rebase ou cherry-pick do trabalho contribuído no topo do seu branch master, em vez de fazer o merge dele, para manter um histórico majoritariamente linear. Quando você tem trabalho em um branch de tópico e determina que deseja integrá-lo, você se move para esse branch e executa o comando rebase para reconstruir as alterações no topo do seu branch master (ou develop, e assim por diante) atual. Se isso funcionar bem, você pode fazer um fast-forward no seu branch master, e acabará com um histórico de projeto linear.

A outra maneira de mover o trabalho introduzido de um branch para outro é fazer o cherry-pick dele. Um cherry-pick no Git é como um rebase para um único commit. Ele pega o patch que foi introduzido em um commit e tenta reaplicá-lo no branch em que você está no momento. Isso é útil se você tem vários commits num branch de tópico e quer integrar apenas um deles, ou se tem apenas um commit num branch de tópico e prefere fazer o cherry-pick em vez de executar o rebase. Por exemplo, suponha que você tenha um projeto parecido com este:

Se você quiser puxar (pull) o commit e43a6 para o seu branch master, você pode executar:

Isso puxa a mesma alteração introduzida em e43a6, mas você obtém um novo valor SHA-1 de commit, porque a data de aplicação é diferente. Agora o seu histórico se parece com isso:

Agora você pode remover o seu branch de tópico e descartar os commits que você não quis puxar.

Se você está fazendo muitos merges e rebases, ou está mantendo um branch de tópico de longa vida, o Git tem um recurso chamado “rerere” que pode ajudar.

Rerere significa “reuse recorded resolution” (reutilizar resolução registrada) — é uma forma de atalhar a resolução manual de conflitos. Quando o rerere está ativado, o Git mantém um conjunto de pré e pós-imagens de merges bem-sucedidos e, se perceber que há um conflito exatamente igual a um que você já corrigiu, ele usará a correção da última vez, sem incomodá-lo com isso.

Esse recurso vem em duas partes: uma configuração e um comando. A configuração é rerere.enabled, e é útil o suficiente para ser colocada em sua configuração global:

Agora, sempre que você fizer um merge que resolva conflitos, a resolução será registrada no cache, caso você precise dela no futuro.

Se precisar, você pode interagir com o cache do rerere usando o comando git rerere. Quando é invocado sozinho, o Git verifica seu banco de dados de resoluções e tenta encontrar uma correspondência com quaisquer conflitos de merge atuais e resolvê-los (embora isso seja feito automaticamente se rerere.enabled estiver definido como true). Existem também subcomandos para ver o que será registrado, para apagar resoluções específicas do cache e para limpar todo o cache. Cobriremos o rerere em mais detalhes em Rerere.