Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-format-patch last updated in 2.33.0

NOME

git-format-patch - Preparar os patches para o envio de e-mails

RESUMO

git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
		   [--no-thread | --thread[=<estilo>]]
		   [(--attach|--inline)[=<limite>] | --no-attach]
		   [-s | --signoff]
		   [--signature=<assinatura> | --no-signature]
		   [--signature-file=<arquivo>]
		   [-n | --numbered | -N | --no-numbered]
		   [--start-number <n>] [--numbered-files]
		   [--in-reply-to=<id-da-mensagem>] [--suffix=.<sfx>]
		   [--ignore-if-in-upstream]
		   [--cover-from-description=<modo>]
		   [--rfc] [--subject-prefix=<subject prefix>]
		   [(--reroll-count|-v) <n>]
		   [--to=<e-mail>] [--cc=<e-mail>]
		   [--[no-]cover-letter] [--quiet]
		   [--[no-]encode-email-headers]
		   [--no-notes | --notes[=<ref>]]
		   [--interdiff=<anterior>]
		   [--range-diff=<anterior> [--creation-factor=<percent>]]
		   [--progress]
		   [<opções-comuns-ao-diff>]
		   [ <desde> | <faixa-da-revisão> ]

DESCRIÇÃO

Prepare cada commit com o seu respectivo patch em um arquivo, formatado para que se assemelhe com uma caixa de correio UNIX. A saída deste comando é conveniente para o envio de um e-mail ou para a utilização com git am.

Existem duas maneiras de especificar em quais commits operar.

  1. Um único commit, <since>, determina que os commits que levem ao cume do ramo atual que não estão no histórico que levem ao <since> para ser gerado.

  2. Expressão genérica do <intervalo da revisão> (consulte a seção "DEFININDO AS REVISÕES" no gitrevisions[7]) define os commits no intervalo especificado.

A primeira regra tem precedência no caso de um único <commit>. Para aplicar a segunda regra, formate tudo desde o início do histórico até <commit>, utilize a opção --root, por exemplo: git format-patch --root <commit>. Caso queira formatar apenas o <commit> em si, faça com git format-patch -1 <commit>.

É predefinido que cada arquivo de saída seja numerado sequencialmente a partir de 1 e usa a primeira linha da mensagem do commit (trabalhada para a segurança do pathname) como o pathname. Com a opção --numbered-files, os nomes dos arquivos na saída serão apenas números, sem a primeira linha anexada do commit. Os nomes dos arquivos na saída são impressos na saída padrão a menos que a opção --stdout seja utilizada.

Caso a opção -o seja utilizada, os arquivos gerados serão criados no <dir>. Caso contrário, eles serão criados no diretório de trabalho atual. O caminho predefinido pode ser definido com a opção de configuração format.outputDirectory. A opção -o tem precedência sobre a opção de configuração format.outputDirectory. Para armazenar as correções no diretório de trabalho atual, mesmo quando a opção de configuração format.outputDirectory apontar para um outro lugar, utilize -o .. Todos os componentes do diretório serão criados.

É predefinido que o assunto de um único patch seja "[PATCH]" seguido da concatenação das linhas da mensagem do commit até a primeira linha em branco (consulte a seção DISCUSSÃO em git-commit[1]).

Quando vários patches são produzidos, o prefixo do assunto será "[PATCH n/m] ". Para forçar a adição 1/1 para um único patch, utilize -n. Para omitir os números do assunto, utilize -N.

Caso a opção --thread seja utilizada, o ` git-format-patch` irá gerar cabeçalhos In-Reply-To (Em-Resposta-Para) e References para fazer com que o e-mail do segundo e subsequentes patches apareçam como resposta ao primeiro e-mail; isso também gera um cabeçalho Message-Id para a referência.

OPÇÕES

-p
--no-stat

Gere correções simples sem qualquer diffstats.

-U<n>
--unified=<n>

Gere diffs com uma quantidade de <n> linhas de contexto em vez das três usuais. Implica no uso da opção --patch.

--output=<arquivo>

Escreve o arquivo para um determinado arquivo em vez de stdout.

--output-indicator-new=<caractere>
--output-indicator-old=<caractere>
--output-indicator-context=<caractere>

Informe o caractere que será utilizado para indicar as linhas novas, antigas ou do contexto no patch que foi gerado. Normalmente eles são +, - e ' ' respectivamente.

--indent-heuristic

Ativa a heurística que altera os limites dos pedaços diferentes para facilitar a leitura dos patches. Esta é a predefinição.

--no-indent-heuristic

Desative a heurística de recuo.

--minimal

Expenda um tempo extra para garantir que o menor diferencial possível seja produzido.

--patience

Gere um diff utilizando o algoritmo "patience diff" (ou diff de paciência).

--histogram

Gere um diff utilizando o algoritmo "histogram diff" (ou diff de histograma).

--anchored=<texto>

Gere um diff utilizando o algoritmo "anchored diff" (ou diff ancorado).

Esta opção pode ser especificada mais de uma vez.

Caso uma linha exista na origem e no destino, exista apenas uma vez e comece com este texto, este algoritmo tenta impedir que apareça como uma exclusão ou adição na saída. O algoritmo "patience diff" é utilizado internamente.

--diff-algorithm={patience|minimal|histogram|myers}

Escolha um algoritmo diff. As variantes são as seguintes:

default, myers

O algoritmo diff ganancioso básico. Atualmente, este é o valor predefinido.

minimal

Expenda um tempo extra para garantir que o menor diferencial possível seja produzido.

patience

Utilize o algoritmo "patience diff" (ou diff de paciência) ao gerar os patches.

histogram

Este algoritmo estende o algoritmo "patience" (paciência) para "se compatível com os elementos comuns com baixa ocorrência".

Caso tenha configurado uma variável diff.algorithm para um valor sem predefinição e quer utilizar a variável predefinida por exemplo, então utilize a opção --diff-algorithm=default.

--stat[=<largura>[,<largura-do-nome>[,<count>]]]

Gera um diffstat. É predefinido que o espaço necessário será utilizado para a parte do nome do arquivo e o restante para a parte do grafo. A largura máxima a predefinição retorna para a largura do terminal ou 80 colunas, caso não esteja conectada em um terminal e pode ser substituída por <largura>. A largura da parte do nome do arquivo pode ser limitada, fornecendo outra largura <largura-do-nome> após uma vírgula. A largura da parte do grafo pode ser limitada utilizando --stat-graph-width=<largura> (afeta todos os comandos que geram um grafo estatístico) ou definindo diff.statGraphWidth=<largura> (não afeta o git format-patch). Ao fornecer um terceiro parâmetro <count>, é possível limitar a saída às primeiras linhas <count>, seguidas por ... caso haja mais.

Estes parâmetros também podem ser ajustados individualmente com --stat-width=<largura>, --stat-name-width=<largura-do-nome> e --stat-count=<count>.

--compact-summary

A saída de um resumo condensado das informações do cabeçalho estendido como criações ou exclusões dos arquivos ("novo" ou "desaparecido", opcionalmente "+l" se for um link simbólico) e alterações do modo ("+x" ou "-x" para adicionar ou remover um bit executável, respectivamente) no diffstat. As informações são colocadas entre a parte do nome do arquivo e a parte do grafo. Implica no uso da opção --stat.

--numstat

Semelhante ao --stat, exibe a quantidade de linhas adicionadas, excluídas, em notação decimal e o nome do caminho sem abreviação, para torná-lo mais amigável à máquina. Para arquivos binários, gera dois - em vez de 0 0.

--shortstat

Produz apenas a última linha do formato --stat contendo a quantidade total dos arquivos modificados, assim como a quantidade de linhas adicionadas e excluídas.

-X[<parâmetro1,parâmetro2,…​>]
--dirstat[=<parâmetro1,parâmetro2,…​>]

Produz a distribuição da quantidade relativa de alterações para cada subdiretório. O comportamento do --dirstat pode ser customizado passando uma lista de parâmetros separados por vírgula. As predefinições são controlados pela variável de configuração diff.dirstat (veja git-config[1]). Os seguintes parâmetros estão disponíveis:

changes

Calcule os números "dirstat" contando as linhas que foram removidas da fonte ou adicionadas ao destino. Ignora a quantidade de movimentos de código puro em um arquivo. Em outras palavras, reorganizar as linhas em um arquivo não conta tanto quanto as outras alterações. Este é o comportamento predefinido quando nenhum parâmetro for utilizado.

lines

Calcule os números "dirstat" fazendo a análise diferencial com base nas linhas regulares e somando as contagens das linhas removidas / adicionadas. (Para os arquivos binários, conte em blocos de 64 bytes, pois os arquivos binários não têm um conceito natural de linhas). Este é um comportamento mais dispendioso do --dirstat do que o comportamento changes (alterações), conta as linhas reorganizadas em um arquivo tanto quanto as outras alterações. A produção resultante é consistente com o que você obtém das outras opções --*stat.

files

Calcule os números "dirstat" contando a quantidade de arquivos alterados. Cada arquivo alterado conta igualmente na análise do "dirstat". Este é o comportamento computacional mais barato do --dirstat, pois não precisa olhar o conteúdo do arquivo.

cumulative

Conta as alterações em um diretório herdeiro e também para o diretório de origem. Observe que, ao utilizar cumulative (cumulativo), a soma das porcentagens relatadas pode exceder os 100%. O comportamento predefinido (não cumulativo) pode ser especificado com o parâmetro noncumulative (não cumulativo).

<limite>

Um parâmetro inteiro especifica uma porcentagem de corte (a predefinição retorna para 3%). Os diretórios que contribuem com menos que esta porcentagem nas alterações não são exibidos na saída.

Exemplo: O seguinte contará os arquivos alterados, ignorando os diretórios com menos de 10% da quantidade total dos arquivos alterados e acumulando as contagens de um diretório-herdado nos diretórios-raiz: ---dirstat=arquivos,10,cumulative.

--cumulative

É um sinônimo para --dirstat=cumulative

--dirstat-by-file[=<parâmetro1,parâmetro2>…​]

É um sinônimo para --dirstat=arquivos,parâmetro1,parâmetro2...

--summary

Produza um resumo condensado das informações estendidas do cabeçalho, como criações, renomeações e alterações do modo.

--no-renames

Desative a detecção da ação de renomear, mesmo quando o arquivo de configuração seja predefinido para tanto.

--[no-]rename-empty

Se usa ou não bolhas vazias como origem do nome.

--full-index

Em vez do primeiro punhado de caracteres, exiba os nomes completos dos objetos bolha antes e depois da imagem na linha "index" ao produzir a saída no formato patch.

--binary

Além de --full-index, gere um diff binário que possa ser aplicado com o comando git-apply. Implica no uso da opção --patch.

--abrev[=<n>]

Em vez de exibir o nome completo do objeto hexadecimal com 40 bytes na produção do formato diff-raw e nas linhas do cabeçalho da árvore diff, exiba apenas um prefixo parcial. Isso é independente da opção --full-index acima, que controla o formato da produção da saída do diff-patch. A quantidade de dígitos fora do preestabelecido pode ser especificado com a opção --abbrev=<n>.

-B[<n>][/<m>]
--break-rewrites[=[<n>][/<m>]]

Divida as alterações reescritas que foram completas em pares de exclusão e criação. Isso serve a dois propósitos:

Afeta a maneira como uma mudança que equivale a uma reescrita total de um arquivo, não como uma série de exclusão e inserção combinadas com poucas linhas que coincidem textualmente com o contexto, e sim como uma única exclusão de tudo o que é antigo seguido por um inserção única de tudo que for novo, o número m controla este aspecto da opção -B (a predefinição retorna para 60%). -B / 70% determina que menos de 30% do original deve permanecer no resultado para que o Git considere-o como uma reescrita total (ou seja, caso contrário, o patch resultante será uma série de exclusões e inserções combinados com linhas de contexto).

Quando utilizado com a opção -M, um arquivo totalmente reescrito também é considerado a fonte de uma renomeação (O -M geralmente considera apenas um arquivo que desapareceu como a origem de uma renomeação), o número n controla esse aspecto da opção -B (a predefinição retorna para 50%). O -B20% determina que uma alteração com a adição e a exclusão em comparação com 20% ou mais do tamanho do arquivo é elegível para ser selecionada como uma possível fonte de renomeação para um outro arquivo.

-M[<n>]
--find-renames[=<n>]

Detecte as renomeações. Caso n seja utilizado, é a limítrofe do índice da similaridade (A quantidade de adições/exclusões comparado ao tamanho do arquivo). -M90% significa que o Git deve considerar uma ação do par de exclusão/adição para ser renomeado caso mais que 90% do arquivo não tenha sido alterado. Sem um sinal de %, a quantidade deve ser lida como uma fração, com um ponto decimal antes dele. -M5 se torna por exemplo 0.5, portanto, é o mesmo que -M50%. Da mesma forma que -M05 é o mesmo que -M5%. Para limitar a detecção para renomeações exatas, utilize -M100%. A predefinição para o índice de similaridade é 50%.

-C[<n>]
--find-copies[=<n>]

Detecte as cópias e também o que for renomeado. Consulte também --find-copies-harder. Caso n seja utilizado, ele terá o mesmo significado que -M<n>.

--find-copies-harder

Por motivos de desempenho, a predefinição retorna para que a opção -C encontre as cópias apenas caso o arquivo original da cópia tenha sido modificado no mesmo conjunto de alterações. Essa flag faz com que o comando inspecione os arquivos que não modificados como candidatos à origem da cópia. Esta é uma operação muito dispendiosa em projetos grandes, portanto, utilize-a com cuidado. Tem o mesmo efeito caso a opção -C seja repetida.

-D
--irreversible-delete

Omita a imagem prévia que será excluída, ou seja, imprima apenas o cabeçalho, mas não a diferença entre a pré-imagem e /dev/null. O patch resultante não deve ser aplicado com com o comando patch ou git apply; é apenas para pessoas que desejam se concentrar em revisar o texto após a alteração. Além disso, a saída obviamente não possui informações suficientes para aplicar esse patch em sentido inverso, mesmo manualmente, daí o nome da opção.

Quando utilizado em conjunto com a opção -B, omita também a pré-imagem na parte da exclusão de um par excluir/criar.

-l<num>

As opções -M e -C requerem um tempo de processamento O(n^2) em que n é a quantidade de possíveis alvos para renomeações/cópia. Esta opção impede que a detecção da ação de renomear/cópia seja executada se a quantidade dos alvos a serem renomeados/copiados exceda o a quantidade especificada.

-O<ordem-do-arquivo>

Controlar a ordem em que os arquivos aparecem na saída. Substitui a variável de configuração diff.orderFile (consulte git-config[1]). Para cancelar a variável diff.orderFile, utilize -O/dev/null.

A ordem da saída é determinada pela ordem dos padrões bolha na <ordem-do-arquivo>. São enviados primeiro todos os arquivos cujos nomes do caminho coincidam com o primeiro padrão, em seguida todos os arquivos cujos nomes do caminho coincidam com o segundo padrão (mas não ao primeiro) e assim por diante. São exibidos por último todos os arquivos cujos nomes do caminho não coincidam com nenhum padrão como se houvesse um padrão de coincidência total implícito no final do arquivo. Caso vários nomes do caminho tenham a mesma classificação (eles coincidem com o mesmo padrão, mas não com os padrões anteriores), a sua ordem na saída em relação à outra é a ordem normal.

A <ordem-do-arquivo> é analisado da seguinte maneira:

  • As linhas em branco são ignoradas para que possam ser utilizadas como separadores, facilitando a leitura.

  • As linhas que começam com um hash ("#") são ignoradas para que possam ser utilizadas como comentários. Adicione uma barra invertida ("\") ao início do padrão caso ele comece com um hash.

  • Cada outra linha quem contenha um único padrão.

Os padrões têm a mesma sintaxe e semântica que os padrões utilizados para fnmatch(3) sem a flag FNM_PATHNAME, exceto que um nome do caminho também coincida com um padrão caso a remoção de qualquer quantidade dos componentes finais do nome do caminho coincida com o padrão. O padrão "foo*bar" coincide com "fooasdfbar" e "foo/bar/baz/asdf" mas não com "foobarx" por exemplo.

--relative[=<caminho>]
--no-relative

Com esta opção, quando executado a partir de um subdiretório do projeto, pode-se dizer para excluir as alterações fora do diretório e exibir os nomes do caminho relativos a ele. Quando não estiver em um subdiretório (em um repositório simples por exemplo), é possível nomear em qual subdiretório tornar a saída relativa, utilizando um <caminho> como argumento. A opção --no-relative pode ser utilizada para contrapor ambas as opções de configuração diff.relative e a anterior --relative.

-a
--text

Trate todos os arquivos como texto.

--ignore-cr-at-eol

Ignore o retorno do carro no final da linha durante uma comparação.

--ignore-space-at-eol

Ignore as alterações no espaço na EOL (fim da linha).

-b
--ignore-space-change

Ignore as alterações na quantidade do espaço. Ignora o espaço no final da linha e considera todas as outras sequências de um ou mais caracteres de espaço como equivalentes.

-w
--ignore-all-space

Ignore o espaço durante a comparação das linhas. Ignore as diferenças mesmo que uma linha tenha espaços quando a outra linha não tiver nenhuma.

--ignore-blank-lines

Ignore as alterações cujas linhas estejam todas em branco.

--inter-hunk-context=<linhas>

Exiba o contexto entre as diferenças, até a quantidade de linhas especificada, fundindo assim as que estão próximas umas das outras. A predefinição retorna para diff.interHunkContext ou 0 caso a opção de configuração não esteja definida.

-W
--function-context

Exiba todas as funções ao redor das alterações.

--ext-diff

Permitir que um auxiliar diff externo seja executado. Caso um controlador diff externo seja definido com gitattributes[5], será necessário a utilização desta opção com git-log[1] e seus companheiros.

--no-ext-diff

Não permitir o uso de um controladores diff externo.

--textconv
--no-textconv

Permita (ou não permita) a execução dos filtros externos para a conversão do texto durante a comparação dos arquivos binários. Para mais detalhes consulte gitattributes[5]. Como os filtros "textconv" são normalmente uma conversão unidirecional, o diff resultante é legível para as pessoas porém não pode ser aplicado. Por este motivo, é predefinido que os filtros "textconv" estejam ativos apenas para os comandos git-diff[1] e git-log[1], mas não para os comandos git-format-patch[1] ou comandos "diff" que possam ser redirecionados.

--ignore-submodules[=<quando>]

Ignore as alterações nos submódulos durante a geração dos diffs. O <quando> pode ser "none" (nenhum), "untracked" (sem monitoramento/rastreamento), "dirty" (sujo) ou "all" (todos), que é a predefinição. O "none" considera o submódulo modificado quando houver arquivos não estejam rastreados, modificados ou o seu HEAD seja diferente do commit registrado no superprojeto, pode ser utilizado para substituir qualquer configuração da opção ignore (ignorar) em git-config[1] ou gitmodules[5]. Quando o "untracked" é utilizado, os submódulos não são considerados sujos quando houver apenas um conteúdo sem rastreamento (porém o monitoramento de alterações do seu conteúdo continua) O uso de "dirty" ignora todas as alterações na árvore de trabalho dos submódulos, apenas as alterações nos commits armazenados no superprojeto são exibidos (este era o comportamento anterior até a versão 1.7.0). O uso de "all" oculta todas as alterações nos submódulos.

--src-prefix=<prefixo>

Exiba o prefixo da origem utilizada em vez de "a/".

--dst-prefix=<prefixo>

Exiba o prefixo do destino utilizado em vez de "b/".

--no-prefix

Não exiba nenhum prefixo da origem ou destino.

--line-prefix=<prefixo>

Prefira um prefixo adicional em cada linha produzida.

--ita-invisible-in-index

É predefinido que as entradas adicionadas através do comando "git add -N" apareçam como uma cadeia de caracteres vazia existente com o comando "git diff" e um novo arquivo com "git diff --cached". Esta opção faz com que a entrada apareça como um novo arquivo no "git diff" e inexistente no "git diff --cached". Esta opção pode ser revertida com --ita-visible-in-index. Ambas as opções são experimentais e podem ser removidas no futuro.

Para uma explicação mais detalhada sobre estas opções comuns, consulte também gitdiffcore[7].

-<n>

Prepare os patches a partir do <n> do nível mais alto dos commits.

-o <dir>
--output-directory <dir>

Utilize <dir> para armazenar os arquivos resultantes em vez do diretório de trabalho atual.

-n
--numbered

Nomeie a saída no formato [PATCH n/m], mesmo que seja com um único patch.

-N
--no-numbered

Nomeie a saída no formato [PATCH].

--start-number <n>

Comece a enumerar os patches a partir do <n> em vez de 1.

--numbered-files

Os nomes dos arquivos na saída serão uma sequência numérica simples sem a primeira linha predefinida do commit anexado.

-k
--keep-subject

Não retire/adicione [PATCH] da primeira linha da mensagem do registro log do commit.

-s
--signoff

Adicione a linha Signed-off-by: (Assinada por:) à mensagem do commit, utilizando a sua identidade. Para mais informações sobre a assinatura na saída da mensagem, consulte em git-commit[1].

--stdout

Imprima todos os commits na saída padrão no formato mbox em vez de criar um arquivo individual para cada um.

--attach[=<divisa>]

Crie anexos com diversas partes/misto onde a primeira parte é a mensagem do commit e o próprio patch na segunda parte utilizando Content-Disposition: attachment.

--no-attach

Desative a criação de um anexo, substituindo a configuração predefinida.

--inline[=<divisa>]

Crie um anexo com diversas partes/misto onde a primeira parte é a mensagem do commit e o próprio patch na segunda parte utilizando Content-Disposition: inline.

--thread[=<estilo>]
--no-thread

Controla a adição dos cabeçalhos In-Reply-To (Em resposta a) e References para fazer com que o segundo e os emails subsequentes apareçam como respostas ao primeiro. Também controla a geração do cabeçalho para a referência Message-Id.

O argumento opcional <estilo> pode ser shallow (superficial) ou deep (profundo). O argumento shallow (superficial) faz com que todo o e-mail respondido para o cabeçalho da série onde o cabeçalho é selecionado nessa ordem, pela carta de apresentação, pelo --in-reply-to e pelo primeiro patch. O argumento deep (profundo) faz com que cada e-mail seja uma uma resposta ao anterior.

A predefinição é --no-thread, a menos que a configuração format.thread esteja definida. Caso --thread seja utilizado sem um estilo, a predefinição retorna para o estilo determinado na opção de configuração format.thread caso exista ou então, shallow (superficial).

Lembre-se de que a predefinição para o comando git send-email é encadear os próprios emails. Caso queira que o comando git format-patch cuide do encadeamento, tenha certeza que o encadeamento esteja desativado para o comando git send-email.

--in-reply-to=<id-da-mensagem>

Faça com que o primeiro e-mail (ou todos os emails com --no-thread) apareça como uma resposta ao <id da mensagem> informado, o que evita quebras dos encadeamentos provendo uma nova série dos patches.

--ignore-if-in-upstream

Não inclua um patch que coincida a um commit em <until>..<since> (até..desde). Examina todos os patches acessíveis a partir de <since> (desde), mas não a partir de <until> (até), os comparará com os patches que estão sendo gerados e qualquer patch coincidente será ignorado.

--cover-from-description=<mode>

Controla quais as partes da carta de apresentação serão preenchidas automaticamente utilizando ao descritivo do ramo.

Caso <modo> seja message ou default, o assunto da carta de apresentação será preenchido com um texto em um espaço reservado. O corpo da carta de apresentação será preenchido com a descrição do ramo. Este é o modo predefinido quando nenhuma configuração ou opção na linha de comando for utilizada.

Caso o <modo> seja subject, o primeiro parágrafo do descritivo do ramo preencherá o assunto da carta de apresentação. O restante do descritivo preencherá o corpo da carta de apresentação.

Caso <modo> seja auto e se o primeiro parágrafo do descritivo do ramo for maior que 100 bytes, o modo será message, caso contrário, o subject será utilizado.

Caso <modo> seja none, tanto o assunto e o corpo da carta serão preenchidos com o texto do espaço reservado.

--subject-prefix=<subject prefix>

Em vez do prefixo [PATCH] predefinido na linha assunto, utilize [<prefixo do assunto>]. Permite a nomeação útil de uma série de patches e pode ser combinado com a opção --numbered.

--rfc

É um atalho --subject-prefix="RFC PATCH". O RFC significa "Solicitação de Comentários"; utilize isso ao enviar um patch experimental para que ele seja discutido em vez de um patch definitivo.

-v <n>
--reroll-count=<n>

Marque a série como a <n>-ésima iteração do tópico. Os nomes dos arquivos na saída têm v<n> anexado a eles e o prefixo do assunto (a predefinição retorna para "PATCH", porém pode ser alterado através da opção --subject-prefix). Por exemplo. --reroll-count=4 pode produzir o arquivo v4-0001-add-makefile.patch que contém "Assunto: [PATCH v4 1/20] Adicione o makefile".

--to=<e-mail>

Adicione um cabeçalho Para: nos cabeçalhos do email. É um acréscimo a qualquer cabeçalho configurado e pode ser utilizado várias vezes. A forma negada da opção --no-to descarta todos os cabeçalhos Para: que foram adicionados até agora (seja da configuração ou da linha de comando).

--cc=<e-mail>

Adicione um cabeçalho Cc: (Com Cópia Para) aos cabeçalhos do email. É um acréscimo a qualquer cabeçalho configurado e pode ser utilizado várias vezes. A forma negada da opção --no-cc descarta todos os cabeçalhos Cc: que foram adicionados até agora (seja da configuração ou da linha de comando).

--from
--from=<ident>

Utilize ident (identidade) no cabeçalho De: de cada email do commit. Caso o ident do autor do commit não seja textualmente idêntica ao ident informado, coloque um cabeçalho De: no corpo da mensagem com o autor original. Caso nenhum ident seja informado, utilize o ident de quem fez o commit.

Observe que esta opção só é útil caso esteja realmente enviando os e-mails e quiser se identificar como remetente mantendo o autor original (o git am pegará corretamente o cabeçalho interno). Observe também que o comando git send-email já lida com essa transformação para você, essa opção não deve ser utilizada caso esteja alimentando o resultado com o comando git send-email.

--add-header=<cabeçalho>

Adicione um cabeçalho arbitrário aos cabeçalhos do e-mail. É um acréscimo a qualquer cabeçalho configurado e pode ser utilizado várias vezes. Por exemplo, --add-header="Organization: git-foo". O formulário negado --no-add-header descarta todos os cabeçalhos (Para:, Cc: e customizado) adicionados até agora na configuração ou na linha de comando.

--[no-]cover-letter

Além dos patches, gere uma carta de apresentação contendo no arquivo a descrição da ramificação, o "shortlog" e o "diffstat" geral. Você pode preencher uma descrição no arquivo antes de enviá-lo.

--encode-email-headers
--no-encode-email-headers

Codifique os cabeçalhos do e-mail que possuam caracteres não ASCII com "Q-encoding" (descrito na RFC 2047), em vez de emitir os cabeçalhos de forma literal. A predefinição retorna para o valor da variável de configuração format.encodeEmailHeaders.

--interdiff=<anterior>

Como um auxílio ao revisor, insira um "interdiff" na carta de apresentação ou como um comentário único do patch de uma série de 1, exibindo as diferenças entre a versão anterior da série do patch e a série atualmente sendo formatada. previous (anterior) é uma única revisão que informa a ponta da série anterior que compartilha uma base comum com a série que está sendo formatada (git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2 por exemplo).

--range-diff=<anterior>

Como um assistente revisor, insira um "range-diff" (consulte git-range-diff[1]) na carta de apresentação ou como um comentário do patch solitário da série de 1-patch, exibindo as diferenças entre a versão anterior da série de patches e a série atualmente sendo formatada. O previous pode ser uma única revisão informando a ponta da série anterior, caso ela compartilhe uma base comum com a série que está sendo formatada (como por exemplo,o comando git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2), ou um intervalo das revisões caso as duas versões da série sejam separadas (como por exemplo, git format-patch --cover-letter --range-diff=feature/v1~3..feature/v1 -3 feature/v2).

Observe que as opções diff passadas ao comando afetam como o produto primário do format-patch será gerado, não são passadas para o mecanismo subjacente do range-diff usado para gerar o material da carta de apresentação (isso pode mudar no futuro).

--creation-factor=<percent>

Ao ser utilizado com a opção --range-diff, ajuste a heurística que coincida com os commits entre as séries de patches anteriores e atuais, ajustando o custo do fator de correção entre criação/exclusão. (Para mais detalhes, consulte git-range-diff[1]).

--notes[=<ref>]
--no-notes

Adiciona as anotações (consulte git-notes[1]) para o commit depois da linha com três traços.

É esperado que seja utilizado para escrever uma explicação de suporte para o commit que não pertença à mensagem do registro log do commit e seja incluída no envio do patch. Embora seja possível simplesmente escrever essas explicações após a execução do format-patch, antes do envio, mantê-las como notas do Git permite que elas sejam mantidas entre as versões da série de patches (ainda assim consulte a discussão das opções de configuração do notes.rewrite em git-notes[1] para compreender este fluxo de trabalho).

A predefinição é --no-notes, a menos que a configuração format.notes esteja definida.

--[no-]signature=<assinatura>

Adicione uma assinatura em cada mensagem produzida. De acordo com a RFC 3676, a assinatura é separada do corpo por uma linha com '-- '. Caso a opção da assinatura seja omitida, a predefinição da assinatura retorna para o número da versão do Git.

--signature-file=<arquivo>

Funciona exatamente como --signature, exceto que a assinatura é lida em um arquivo.

--suffix=.<sfx>

Em vez de usar .patch como o sufixo dos nomes dos arquivos gerados, utilize o sufixo especificado. Uma alternativa comum é --suffix=.txt. Deixando este campo vazio remove o sufixo .patch.

Observe que o caractere principal não precisa ser um ponto; você pode usar suffix=patch para obter 0001-description-of-my-change-patch por exemplo.

-q
--quiet

Não imprima os nomes dos arquivos gerados na saída padrão.

--no-binary

Não reproduza o conteúdo das alterações em arquivos binários; em vez disso, exiba um aviso que estes arquivos foram alterados. Os patches gerados utilizando esta opção não podem ser aplicados de forma adequada, porém ainda são úteis para a revisão do código.

--zero-commit

Gere um hash zerado no cabeçalho "From" de cada patch em vez do hash do commit.

--[no-]base[=<commit>]

Registre as informações da base da árvore que identifique a condição na qual a série de patches se aplica. Consulte a seção INFORMAÇÃO BASE DA ÁRVORE abaixo para obter detalhes. If <commit> is "auto", a base commit is automatically chosen. The --no-base option overrides a format.useAutoBase configuration.

--root

Trate o argumento revisão como um <intervalo de revisões>, mesmo que seja apenas um único commit (que normalmente seria tratado como um <since> (desde)). Observe que os commits raiz incluídos no intervalo especificado são sempre formatadas como patches de criação, independentemente dessa flag.

--progress

Exiba o progresso dos relatórios no stderr à medida que os patches são gerados.

CONFIGURAÇÃO

Você pode definir linhas extras no cabeçalho do e-mail que serão adicionadas em cada mensagem, predefinições para o prefixo do assunto e sufixo do arquivo, a quantidade das correções ao emitir mais de um patch, adicionar os cabeçalhos "Para:" ou "Cc:", configurar os anexos, alterar diretório de saída par ao patch e assinar os patches com variáveis de configuração.

[format]
	headers = "Organização: git-foo\n"
	subjectPrefix = CHANGE
	suffix = .txt
	numbered = auto
	to = <e-mail>
	cc = <e-mail>
	attach [ = mime-boundary-string ]
	signOff = true
	outputDirectory = <diretório>
	coverLetter = auto
	coverFromDescription = auto

DISCUSSÃO

O patch produzido pelo git format-patch está em formato mailbox (caixa de correio) UNIX, fixado com uma estampa "mágica" indicando que o arquivo foi gerado pelo patch em vez de um mailbox real, exemplo:

From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
From: Tony Luck <tony.luck@intel.com>
Date: Tue, 13 Jul 2010 11:42:54 -0700
Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Os arquivos da configuração arch/arm foram reduzidos utilizando um script python
(Veja o comentário c2330e286f68f1c408b4aa6515ba49d57f05beae do commit)

Faça o mesmo com o ia64, para que possamos ter uma aparência elegante e ornamentada
...

Normalmente, ele é colocado na pasta de rascunhos do MUA, editado para adicionar os comentários oportunos que não devem entrar no changelog após os três hífens e enviado como uma mensagem onde o corpo, no nosso exemplo, começa com "arquivos da configuração arch/arm onde…​". No lado do recebimento, os leitores podem salvar os patches interessantes em um mailbox UNIX e aplicá-los com git-am[1].

Quando um patch faz parte de uma discussão em andamento, o patch gerado pelo git format-patch pode ser ajustado para aproveitar o recurso git am --scissors. Após a sua resposta na discussão, surge uma linha que consiste apenas em "-- >8 --"(tesoura e perfuração), seguida pelo patch com campos desnecessários do cabeçalho que foram removidos:

...
> Então faremos assim e assado.

Faz sentido para mim.  Que tal este patch?

-- >8 --
Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet

Os arquivos da configuração arch/arm foram reduzidos utilizando um script python
...

Ao enviar um patch dessa forma, na maioria das vezes você está enviando o seu próprio patch, portanto, além do marcador "From $SHA1 $magic_timestamp", você deve omitir as linhas From: e Date: do arquivo patch. É provável que o título do patch seja diferente do assunto da discussão onde o patch é uma resposta, portanto, é provável que você queira manter a linha "Subject:", como no exemplo acima.

Verificando o corrompimento dos patches

Muitos clientes de e-mail se não configurados corretamente irão corromper os espaços. Aqui estão dois tipos comuns de corrompimento:

  • As linhas de contexto vazias que não possuem qualquer espaço.

  • As linhas de contexto não vazias que possuam um espaço extra no início.

Uma maneira de testar se o seu cliente de e-mail está configurado corretamente é fazendo o seguinte:

  • Envie o patch para você mesmo exatamente como você faria se fosse enviar para alguém sem adicionar a lista e o endereço do mantenedor em "To:" (Para:) e "Cc:".

  • Salve esse patch em um arquivo no formato mailbox do UNIX. Chame-o de "a.patch".

  • Aplique:

    $ git fetch <projeto> master:test-apply
    $ git switch test-apply
    $ git restore --source=HEAD --staged --worktree :/
    $ git am a.patch

Pode haver vários motivos caso o patch não seja aplicado corretamente.

  • O patch em si não está correto. Isso é ruim, mas não tem muito a ver com o seu cliente de e-mail. Você pode querer refazer o patch neste caso com git-rebase[1] antes de regenerá-lo.

  • O seu cliente de e-mail corrompeu o seu patch; o "am" reclamaria que o patch não pode ser aplicado. Procure no subdiretório .git/rebase-apply/ e veja o conteúdo do arquivo patch, verifique se os padrões mais comuns de corrupção mencionados acima se aplicam.

  • Enquanto isso, verifique os arquivos info e final-commit também. Caso o que estiver em final-commit não seja exatamente o que você quer ver na mensagem do registro log do commit, é muito provável que o destinatário acabe editando manualmente a mensagem do registro log durante a aplicação do seu patch. Coisas como "Olá, este é o meu primeiro patch.\n" no e-mail do patch deve vir após a linha de três traços que sinaliza o final da mensagem do commit.

DICAS ESPECÍFICAS PARA CLIENTES DE E-MAIL

Aqui estão algumas dicas sobre como enviar os patches com sucesso utilizando diferentes clientes de e-mail.

GMail

O GMail não tem como desativar a quebra de linha na interface da Web; portanto, ele altera os e-mails que você envia. Você pode entanto usar o "git send-email" e enviar os seus patches através do servidor SMTP do GMail ou usar qualquer cliente de email IMAP para conectar-se ao servidor IMAP do google e encaminhar os e-mails dessa maneira.

Para obter dicas sobre o uso do git send-email para enviar os seus patches através do servidor SMTP do GMail, consulte a seção EXEMPLO do git-send-email[1].

Para obter dicas sobre o envio utilizando a interface IMAP, consulte a seção EXEMPLO do git-send-email[1].

Thunderbird

É predefinido que o Thunderbird agrupe os e-mails e sinalize-os como format=flowed, o que tornará o e-mail resultante inutilizável pelo Git.

Existem três abordagens diferentes: utilize um complemento para desativar a quebra de linha, configure o Thunderbird para não alterar os patches ou utilize um editor externo para impedir que o Thunderbird manipule os patches.

Abordagem nº 1 (complemento)

Instale o complemento "Toggle Word Wrap" que está disponível em https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/. É adicionado uma entrada chamada "Enable Word Wrap Alt+W" (Ativar a quebra automática de linha Alt+W) na aba "Opções" do compositor que você pode de-selecionar. Agora você pode compor a mensagem da mesma maneira que você sempre fez (recortar + colar, git format-patch | git imap-send, etc), porém é necessário inserir as quebras das linhas manualmente em qualquer texto que for digitado.

Abordagem # 2 (configuração)

Três etapas:

  1. Ainda no Thunderbird, configure a redação da mensagem de e-mail como texto sem formatação, vá em Editar → Propriedades → suaconta@email.com → Redação e Endereçamento, desmarque a opção "Usar formatação (HTML)".

  2. Configure a sua janela de composição geral para não quebrar as linhas.

    No Thunderbird 2: Vá em Ferramentas → Opções → Edição → Geral, defina como 0 (zero) caracteres a opção "Quebrar a linha, em mensagem sem formatação, após"

    No Thunderbird 3: Vá em Ferramentas → Avançado → Editor de config. No campo localizar pesquise por "mail.wrap_long_lines". Clique duas vezes com o mouse e tenha certeza que o seu valor mudou para false. Pesquise também pela opção "mailnews.wraplength", clique duas vezes com o mouse e defina o seu valor para 0 (zero).

  3. Desative a utilização da opção "format=flowed": Vá em Ferramentas → Avançado → Editor de config. No campo localizar pesquise por "mailnews.send_plaintext_flowed". Clique duas vezes com o mouse e tenha certeza que o seu valor mudou para false.

Ao concluir, agora é possível compor o e-mail da mesma maneira que seria feito com (recortar + colar, git format-patch | git imap-send, etc), e os patches não ficarão mutilados.

Abordagem nº 3 (editor externo)

As seguintes extensões do Thunderbird são necessárias: O AboutConfig http://aboutconfig.mozdev.org/ (Observação: o AboutConfig não é mais compatível com as versões mais novas do Thunderbird.) e o "External Editor" http://globs.org/articles.php?lng=en&pg=8

  1. Prepare o patch como um arquivo de texto utilizando o seu método preferido.

  2. Antes de abrir uma janela de composição, vá em Editar → Propriedades → Configurações da conta → Redação e endereçamento e desmarque a opção "Usar formatação (HTML)" para que seja possível enviar o patch.

  3. Na janela principal do Thunderbird, antes de abrir a janela de composição do patch, vá em Ferramentas → Avançado → Editor de Configurações e defina os valores como indicado abaixo:

    	mailnews.send_plaintext_flowed  => false
    	mailnews.wraplength             => 0
  4. Abra uma janela de composição e clique no ícone do editor externo.

  5. Na janela do editor externo, carregue o arquivo patch e saia do editor normalmente.

Nota: Pode ser possível executar a segunda etapa para editar as seguintes configurações, mas ninguém tentou ainda.

	mail.html_compose                       => false
	mail.identity.default.compose_html      => false
	mail.identity.id?.compose_html          => false

Existe um script em contrib/thunderbird-patch-inline que pode ajudá-lo a incluir os patches com o Thunderbird facilmente. Para usá-lo, execute as etapas acima e utilize o script como um editor externo.

KMail

Isso deve ajudá-lo a enviar os patches em linha utilizando o KMail.

  1. Prepare o patch como um arquivo de texto.

  2. Clique em "New Mail".

  3. Vá em "Opções" na janela do Compositor verifique se "Quebra de linha" não está definido.

  4. Utilize Mensagem → Inserir arquivo → e insira o patch.

  5. De volta à janela de composição: adicione qualquer outro texto que desejar, preencha os campos de endereçamento, assunto e pressione Enviar.

INFORMAÇÃO BASE DA ÁRVORE

O bloco de informação da base da árvore é utilizado para que os mantenedores ou os testadores de terceiros saibam a condição exata ao qual a série de patches se aplicam. É a base do commit, é um commit informado que faz parte da parte estável do histórico do projeto onde todos os outros usam para trabalhar. Zero ou mais patches de pré-requisição são patches informados em transição, porém ainda não fazem parte da base do commit que precisam ser aplicados sobre o cume da base do commit em ordem topológica antes que os patches possam ser aplicados.

A base do commit é exibido como "base-commit:" seguido por 40 hexadecimais do nome do objeto commit. Um patch de pré-requisição é exibido como "prerequisite-patch-id:" seguido por um patch id com 40 hexadecimais, que pode ser obtido passando o patch pelo comando git patch-id --stable.

Imagine que, em cima do commit público P, foi aplicado os patches informados X, Y e Z de outra pessoa e construiu a sua série de três patches A, B, C, o histórico ficaria assim:

---P---X---Y---Z---A---B---C

Com o git format-patch --base = P -3 C (ou variantes do mesmo com --cover-letter ou utilizando Z..C em vez de -3 C para especificar o intervalo por exemplo), o bloco das informações da base da árvore é exibido no final da primeira mensagem que o comando gera (o primeiro patch ou a carta de apresentação), assim:

base-commit: P
prerequisite-patch-id: X
prerequisite-patch-id: Y
prerequisite-patch-id: Z

Para uma topologia não linear, como

---P---X---A---M---C
    \         /
     Y---Z---B

Você também pode usar o comando git format-patch --base = P -3 C para gerar as correções para A, B e C, os identificadores para P, X, Y, Z serão anexados no final da primeira mensagem.

Caso --base=auto seja definido no cmdline, ele rastreará automaticamente a base do commit, o commit da base será o cume do ramo do commit monitorado remotamente e o intervalo da revisão determinado pelo cmdline. Antes de utilizar esta opção para uma ramificação local, é necessário monitorar um ramo remoto com o comando git branch --set-upstream-to.

EXEMPLOS

  • Extraia os commits entre as revisões R1 e R2, aplique-as no cume do ramo atual utilizando o comando git am para selecioná-las:

    $ git format-patch -k --stdout R1..R2 | git am -3 -k
  • Extraia todos os commits que estão na ramificação atual, mas não na ramificação "origin":

    $ git format-patch origin

    Para cada commit é criado um arquivo separado no diretório atual.

  • Extraia todos os commits que levem à origin desde o início do projeto:

    $ git format-patch --root origin
  • É o mesmo que o anterior:

    $ git format-patch -M -B origin

    Além disso, ele detecta e manipula as renomeações e as reescritas completadas de maneira inteligente produzindo um patch de renomeação. Um patch de renomeação reduz a quantidade de saída do texto e geralmente facilita a revisão. Observe que os programas de "patches" que não sejam do Git não entenderão como renomear os patches; portanto, utilize-os apenas quando souber que o destinatário usa o Git para aplicar seu patch.

  • Extraia os três commits mais importantes do ramo atual, formate-os como patches que possam ser enviados por e-mail:

    $ git format-patch -3

GIT

Parte do conjunto git[1]